OData Connector | X4Documentation

Dieser Adapter ermöglicht die Kommunikation zu Systemen, die ReST-Services nach OData-Standard bereitstellen z.B. SAP S4/Hana, Microsoft Sharepoint, Microsoft Dynamics Navision und weitere.

Eigenschaften (Properties)

Operation

Vom Adapter ausgeführte Operationen

Mögliche Werte:

ReadMetadata: Ruft das Datenmodell und die Operationen ab, die von einem bestimmten Dienst ausgeführt werden.
ReadCollections: Ruft alle verfügbaren Auflistungen aus dem Dienst ab.
ReadEntitySet: Ruft eine bestimmte Auflistung aus dem Service ab.
ReadSingleEntity: Ruft eine einzelne Entität aus dem Dienst auf, spezifiziert durch die Auflistung und die ID.
ReadNavigationEntity: Ruft die zugehörige Auflistung für eine Entität ab.
ReadAssociation: Ruft die zugehörige Zuordnung zur Entität ab.
ReadSingleton: Ruft das spezifische Singleton ab.
ReadMediaEntity: Ruft die Medienentität ab.
CreateEntity: Erstellt neue Entitäten im System, spezifiziert durch die Auflistung und die ID in einem XML-Inputdokument.
UpdateEntity: Aktualisiert im System vorhandene Entitäten, spezifiziert durch die Auflistung und die ID in einem XML-Inputdokument.
DeleteEntity: Löscht im System vorhandene Entitäten, spezifiziert durch die Auflistung und die ID in einem XML-Inputdokument.
CreateSingleton: Erstellt ein neues Singleton im System, spezifiziert durch die Auflistung und die ID in einem XML-Inputdokument.
UpdateSingleton: Aktualisiert ein Singleton im System, spezifiziert durch die Auflistung und die ID in einem XML-Inputdokument.
DeleteSingleton: Löscht ein Singleton im System, spezifiziert durch die Auflistung und die ID in einem XML-Inputdokument.
CreateMediaEntity: Erstellt neue Medienentitäten im System, spezifiziert durch die Auflistung und die ID innerhalb der Parameter entitySet und entityId.
UpdateMediaEntity: Aktualisiert Medienentitäten im System, spezifiziert durch die Auflistung und die ID innerhalb der Parameter entitySet und entityId.
DeleteMediaEntity: Löscht Medienentitäten im System, spezifiziert durch die Auflistung und die ID innerhalb der Parameter entitySet und entityId.
Functions: Fragt eine durch den Dienst ausgeführte Operation (Funktion, Aktion) an, wobei die entsprechenden Ausgabewerte abgerufen werden.

Parameter

`serviceUrl`	OData-Service-URL, z.B. `https://services.odata.org/V4/TripPinServiceRW`
`entitySet`	Entitäts-Auflistung
`entityId`	Entitäts-ID
`navigationProperty`	Zur Entität zugehörige Auflistung abrufen
`association`	Zur Entität zugehörige Zuordnung abrufen
`singletonId`	Singleton-ID
`contentTypeMetadata`	ContenType der Service-Metadaten Mögliche Werte: `Full`: Vollständige Metadaten ausgeben `Minimnal`: Nur grundlegende Metadaten ausgeben `None`: Keine Metadaten ausgeben

Statuswerte

`1`	Die Operation wurde erfolgreich ausgeführt und ein Output wurde ausgegeben
`-1`	Es kam zu einem Fehler während der Ausführung und es wurde kein Output ausgegeben

Input

Abhängig von der gewählten Operation erwartet der Adapter folgende Input-Struktur:

Die Operationen ReadaMetadata, ReadSingleEntity, ReadNavigationEntity, ReadSet und ReadSingleton benötigen kein Input-Dokument. Die Parameter entitySet und entityId werden jedoch benötigt.
Die Operation ReadAssociation benötigen kein Input-Dokument. Die Parameter entitySet , entityId und association werden jedoch benötigt.
Operation ReadEntitySet:
Folgende Systemabfrageoptionen können für die Operation ReadEntitySet verwendet werden:
- $count: Ignoriert $top, $skip, oder $expand Abfrageoptionen und gibt die Gesamtzahl der Ergebnisse auf allen Seiten zurück, einschließlich der Ergebnisse, die mit einem bestimmten $filter und einer bestimmten $search übereinstimmen.
- $skip: Werden $top und $skip gemeinsam verwendet, muss $skip vor $top verwendet unabhängig davon, in welcher Reihenfolge sie in der Abfrage vorkommen.
- $top: Ermöglicht es dem Benutzer eines OData-Dienstes, die maximale Anzahl von Einträgen anzugeben, die von Anfang an zurückgegeben werden sollen.
- $orderby: Beim Anfordern einer Liste von Entitäten aus einem Dienst, liegt es an der Service-Implementierung zu entscheiden, in welcher Reihenfolge sie präsentiert werden.
- $filter: Beim Anfordern einer Liste von Entitäten aus einem Dienst, werden standardmäßig alle Entitäten aus der Liste zurückgegeben. Der Verbraucher eines OData-Dienstes möchte möglicherweise eine Teilmenge empfangen können, indem er bestimmte Kriterien angibt, die jede der zurückgegebenen Entitäten erfüllen muss.
- $select: Beim Anfordern einer Entitätsauflistung aus dem Backend, gibt der OData-Dienst eine Liste von Entitäten zurück und jede Entität enthält eine Liste von Eigenschaften.
  - Nur einen Eigenschaftsnamen angeben: $select=Name
  - Eine kommagetrennte Liste von Eigenschaften angeben: $select=Name,Description
  - Mit einem Stern (*) alle Eigenschaften einschließen: $select=*
- $expand: Zeigt die zugehörigen Entitäten und Stream-Werte an, die inline angegeben werden müssen.
- $search: Beschränkt das Ergebnis auf die Elemente, die dem angegebenen Suchbegriff entsprechen.
- $format: Gibt den Medientyp der Antwort an.

ReadEntitySet

XML

<Request>
	<QueryOptions entitySet="Products">
		<Parameter name="format" value="application/xml"></Parameter>
		<Parameter name="search" value="Ergo"></Parameter>
		<Parameter name="top" value="10"></Parameter>
		<Parameter name="skip" value="5"></Parameter>
		<Parameter name="count"></Parameter>
		<Parameter name="filter" value="ID le 10"></Parameter>
		<Parameter name="count" value="true"></Parameter>
		<Parameter name="expand">
			<Items>Category</Items>
		</Parameter>
		<Parameter name="select">
			<Items>ID</Items>
			<Items>Description</Items>
		</Parameter>	
	</QueryOptions>
</Request>

Operationen CreateEntity, UpdateEntity und DeleteEntity:

Create-, Update- und Delete-Anfrage

XML

<Request>
       <Entity qualifiedName="Microsoft.OData.SampleService.Models.TripPin.Person" entitySet="People">
             <Property name="UserName" value="carlosreyestest" type="String" isId="true"/>
             <Property name="FirstName" value="Carlos" type="String"/>
             <Property name="LastName" value="Carlos" type="String"/>
             <Collection name="AddressInfo">
                  <Property type="Microsoft.OData.SampleService.Models.TripPin.Location">
                     <Property name="Address" value="Calle Falsa 123" type="String"/>
                     <Property name="City" type="Microsoft.OData.SampleService.Models.TripPin.City">
                           <Property name="CountryRegion" value="Espana" type="String"/>
                           <Property name="Name" value="Madrid" type="String"/>
                           <Property name="Region" value="Madrid" type="String"/>
                     </Property>
                  </Property>
             </Collection>
       </Entity>
</Request>

Operationen CreateSingleton, UpdateSingleton und DeleteSingleton:

CreateSingleton-, UpdateSingleton- und DeleteSingleton-Anfrage

XML

<Request>
       <Singleton qualifiedName="Microsoft.OData.SampleService.Models.TripPin.Person" entitySet="People">
             <Property name="UserName" value="carlosreyestest" type="String" isId="true"/>
             <Property name="FirstName" value="Carlos" type="String"/>
             <Property name="LastName" value="Carlos" type="String"/>
             <Collection name="AddressInfo">
                  <Property type="Microsoft.OData.SampleService.Models.TripPin.Location">
                     <Property name="Address" value="Calle Falsa 123" type="String"/>
                     <Property name="City" type="Microsoft.OData.SampleService.Models.TripPin.City">
                           <Property name="CountryRegion" value="Espana" type="String"/>
                           <Property name="Name" value="Madrid" type="String"/>
                           <Property name="Region" value="Madrid" type="String"/>
                     </Property>
                  </Property>
             </Collection>
       </Singleton>
</Request>

Für die Operationen CreateMediaEntity, UpdateMediaEntity und DeleteMediaEntity sind sowohl die Parameter entitySet und entityId als auch der Medien-Input im Adapter notwendig.

Operation ExecuteFunction:

Anfrage ExecuteFunction

XML

<?xml version="1.0" encoding="UTF-8"?>
<Request>
       <Function name="CountCategories">
             <Parameter name="Amount" value="2"></Parameter>
       </Function>
</Request>

Unterstützte Typen

Adapter Input-Typ	Typ	Bedeutung
`Binary`	`Edm.Binary`	Binärdaten
`Boolean`	`Edm.Boolean`	Binäre Logik
`Byte`	`Edm.Byte`	Vorzeichenlose 8-Bit Ganzzahl
`Date`	`Edm.Date`	Datum ohne Zeitzonenversatz
`DateTimeOffset`	`Edm.DateTimeOffset`	Datum und Uhrzeit mit Zeitzonenversatz, keine Schaltsekunden
`Decimal`	`Edm.Decimal`	Zahlenwerte mit dezimaler Darstellung
`Double`	`Edm.Double`	IEEE 754 binary64-Gleitkommazahl (15-17 Dezimalstellen)
`Duration`	`Edm.Duration`	Signierte Dauer in Tagen, Stunden, Minuten und (Teil-)Sekunden
`Guid`	`Edm.Guid`	16 Byte (128 Bit) eindeutige Kennung
`Int16`	`Edm.Int16`	Vorzeichenbehaftete 16-Bit Ganzzahl
`Int32`	`Edm.Int32`	Vorzeichenbehaftete 32-Bit Ganzzahl
`Int64`	`Edm.Int64`	Vorzeichenbehaftete 64-Bit Ganzzahl
`SByte`	`Edm.SByte`	Vorzeichenbehaftete 8-Bit Ganzzahl
`Single`	`Edm.Single`	IEEE 754 binary32-Gleitkommazahl (6-9 Dezimalstellen)
`String`	`Edm.String`	Folge von UTF-8 Zeichen

Output

Abhängig von der gewählten Operation gibt der Adapter folgende Strukturen aus:

Operation ReadMetadata:

Antwort ReadMetadata

XML

<?xml version="1.0" encoding="UTF-8"?>
<edmx:Edmx Version="4.0"
	xmlns:edmx="http://docs.oasis-open.org/odata/ns/edmx">
	<edmx:DataServices>
		<Schema xmlns="http://docs.oasis-open.org/odata/ns/edm"
			Namespace="OData.Demo">
			<EntityType Name="Product">
				<Key>
					<PropertyRef Name="ID" />
				</Key>
				<Property Name="ID" Type="Edm.Int32"></Property>
				<Property Name="Name" Type="Edm.String"></Property>
				<Property Name="Description" Type="Edm.String"></Property>
				<NavigationProperty Name="Category"
					Type="OData.Demo.Category" Partner="Products"></NavigationProperty>
			</EntityType>
			<EntityType Name="Category">
				<Key>
					<PropertyRef Name="ID" />
				</Key>
				<Property Name="ID" Type="Edm.Int32"></Property>
				<Property Name="Name" Type="Edm.String"></Property>
				<NavigationProperty Name="Products"
					Type="Collection(OData.Demo.Product)" Partner="Category"></NavigationProperty>
			</EntityType>
			<EntityType Name="Advertisement" HasStream="true">
				<Key>
					<PropertyRef Name="ID" />
				</Key>
				<Property Name="ID" Type="Edm.Guid"></Property>
				<Property Name="Name" Type="Edm.String"></Property>
				<Property Name="AirDate" Type="Edm.DateTimeOffset"></Property>
			</EntityType>
			<Action Name="Reset" IsBound="false">
				<Parameter Name="Amount" Type="Edm.Int32"></Parameter>
			</Action>
			<Function Name="CountCategories">
				<Parameter Name="Amount" Type="Edm.Int32" Nullable="false"></Parameter>
				<ReturnType Type="Collection(OData.Demo.Category)" />
			</Function>
			<EntityContainer Name="Container">
				<EntitySet Name="Products" EntityType="OData.Demo.Product">
					<NavigationPropertyBinding
						Path="Category" Target="Categories" />
				</EntitySet>
				<EntitySet Name="Categories"
					EntityType="OData.Demo.Category">
					<NavigationPropertyBinding
						Path="Products" Target="Products" />
				</EntitySet>
				<EntitySet Name="Advertisements"
					EntityType="OData.Demo.Advertisement"></EntitySet>
				<ActionImport Name="Reset" Action="OData.Demo.Reset"></ActionImport>
				<FunctionImport Name="CountCategories"
					Function="OData.Demo.CountCategories"
					EntitySet="OData.Demo.Categories" IncludeInServiceDocument="true"></FunctionImport>
			</EntityContainer>
		</Schema>
	</edmx:DataServices>
</edmx:Edmx>

Operationen ReadSingleEntity und ReadSingleton:

Antwort ReadSingleEntity

XML

<?xml version="1.0" encoding="UTF-8"?>
<Object>
	<Value type="String" name="@odata.context">$metadata#Products/$entity</Value>
	<Value type="Number" name="ID">1</Value>
	<Value type="String" name="Name">Notebook Professional 17</Value>
	<Value type="String" name="Description">Notebook Professional, 2.8GHz - 15 XGA
		- 8GB DDR3 RAM - 500GB</Value>
</Object>

Operation ReadEntitySet:

Antwort ReadCollectionEntity

XML

<?xml version="1.0" encoding="UTF-8"?>
<Object>
   <Value type="String" name="@odata.context">$metadata#Products</Value>
   <Array name="value">
      <Object>
         <Value type="Number" name="ID">0</Value>
         <Value type="String" name="Name">Notebook Basic 15</Value>
         <Value type="String" name="Description">Notebook Basic, 1.7GHz - 15 XGA - 1024MB DDR2 SDRAM - 40GB</Value>
      </Object>
      <Object>
         <Value type="Number" name="ID">1</Value>
         <Value type="String" name="Name">Notebook Professional 17</Value>
         <Value type="String" name="Description">Notebook Professional, 2.8GHz - 15 XGA - 8GB DDR3 RAM - 500GB</Value>
      </Object>
      <Object>
         <Value type="Number" name="ID">2</Value>
         <Value type="String" name="Name">1UMTS PDA</Value>
         <Value type="String" name="Description">Ultrafast 3G UMTS/HSDPA Pocket PC, supports GSM network</Value>
      </Object>
      <Object>
         <Value type="Number" name="ID">3</Value>
         <Value type="String" name="Name">Comfort Easy</Value>
         <Value type="String" name="Description">32 GB Digital Assitant with high-resolution color screen</Value>
      </Object>
      <Object>
         <Value type="Number" name="ID">4</Value>
         <Value type="String" name="Name">Ergo Screen</Value>
         <Value type="String" name="Description">19 Optimum Resolution 1024 x 768 @ 85Hz, resolution 1280 x 960</Value>
      </Object>
      <Object>
         <Value type="Number" name="ID">5</Value>
         <Value type="String" name="Name">Flat Basic</Value>
         <Value type="String" name="Description">Optimum Hi-Resolution max. 1600 x 1200 @ 85Hz, Dot Pitch: 0.24mm</Value>
      </Object>
   </Array>
</Object>

Operation ReadCollections:

Antwort ReadCollections

XML

<?xml version="1.0" encoding="UTF-8"?>
<Object>
	<Value type="String" name="@odata.context">$metadata</Value>
	<Array name="value">
		<Object>
			<Value type="String" name="name">Products</Value>
			<Value type="String" name="url">Products</Value>
		</Object>
		<Object>
			<Value type="String" name="name">Categories</Value>
			<Value type="String" name="url">Categories</Value>
		</Object>
		<Object>
			<Value type="String" name="name">Advertisements</Value>
			<Value type="String" name="url">Advertisements</Value>
		</Object>
		<Object>
			<Value type="String" name="name">CountCategories</Value>
			<Value type="String" name="url">CountCategories</Value>
			<Value type="String" name="kind">FunctionImport</Value>
		</Object>
	</Array>
</Object>

Operationen CreateEntity, UpdateEntity und DeleteEntity:

CreateEntity-, UpdateEntity- und DeleteEntity-Antwort

XML

<Response>
	<OKEntities entitySet="Products" qualifiedName="OData.Demo.Product">
		<Property isId="true" type="int32" value="1" name="ID"/>
		<Property type="String" value="Car" name="Name"/>
		<Property type="String" value="Good car" name="Description"/>
	</OKEntities>
	<FailEntities entitySet="Products" qualifiedName="OData.Demo.Product">
		<Property isId="true" type="int32" value="2" name="ID"/>
		<Property type="String" value="Cookie" name="Name"/>
		<Property type="String" value="Great cookie" name="Description"/>
	</FailEntities>
</Response>

Operationen CreateSingleton, UpdateSingleton und DeleteSingleton:

CreateSingleton-, UpdateSingleton- und DeleteSingleton-Antwort

XML

<Response>
	<OKEntities entitySet="Products" qualifiedName="OData.Demo.Product">
		<Property isId="true" type="int32" value="1" name="ID"/>
		<Property type="String" value="Car" name="Name"/>
		<Property type="String" value="Good car" name="Description"/>
	</OKEntities>
	<FailEntities entitySet="Products" qualifiedName="OData.Demo.Product">
		<Property isId="true" type="int32" value="2" name="ID"/>
		<Property type="String" value="Cookie" name="Name"/>
		<Property type="String" value="Great cookie" name="Description"/>
	</FailEntities>
</Response>

Operation ExecuteFunction:

Antwort ExecuteFunction

XML

<?xml version="1.0" encoding="UTF-8"?>
<Object>
       <Value type="String" name="@odata.context">$metadata#Collection(OData.Demo.Category)
       </Value>
       <Array name="value">
             <Object>
                    <Value type="Number" name="ID">0</Value>
                    <Value type="String" name="Name">Notebooks</Value>
             </Object>
             <Object>
                    <Value type="Number" name="ID">1</Value>
                    <Value type="String" name="Name">Organizers</Value>
             </Object>
             <Object>
                    <Value type="Number" name="ID">2</Value>
                    <Value type="String" name="Name">Monitors</Value>
             </Object>
       </Array>
</Object>