Abrufanforderungen mit dem REST-Datenservice

Eine RetrieveEntity-Anforderung wird von einem Client verwendet, um eine eXtreme-Scale-Entität abzurufen. Die Nutzdaten der Antwort enthalten die Entitätsdaten im AtomPub- oder JSON-Format. Außerdem kann der Systemoperator "$expand" verwendet werden, um die Relationen zu erweitern. Die Relationen werden inline in der Antwort des Datenservice als Atom Feed Document, das eine :N-Relation ist, oder als Atom Entry Document, das eine :1-Relation dargestellt.

Tipp: Weitere Einzelheiten zu dem Protokoll "RetrieveEntity", das in WCF Data Services definiert ist, finden Sie auf der Webseite MSDN: RetrieveEntity Request.

Entität abrufen

Die folgende RetrieveEntity-Beispielanforderung ruft eine Entität "Customer" mit einem Schlüssel ab.

AtomPub JSON

Abfragen

Mit einer RetrieveEntitySet- oder RetrieveEntity-Anforderung kann auch eine Abfrage verwendet werden. Eine Abfrage wird mit dem Systemoperator "$filter" angegeben.

Einzelheiten zum Operator "$filter" finden Sie auf der Webseite MSDN: Filter System Query Option ($filter).

Das Protokoll "OData" unterstützt mehrere allgemeine Ausdrücke. Der REST-Datenservice von eXtreme Scale unterstützt ein Subset der Ausdrücke, die in der Spezifikation definiert sind:

Die folgenden Ausdrücke sind nicht verfügbar:

Eine vollständige Liste und Beschreibungen der Ausdrücke, die in Microsoft WCF Data Services verfügbar sind, finden Sie im Abschnitt 2.2.3.6.1.1: Common Expression Syntax.

Das folgende Beispiel veranschaulicht eine RetrieveEntity-Anforderung mit einer Abfrage. In diesem Beispiel werden alle Customer (Kunden) mit dem Kontaktnamen "RoadRunner" abgerufen. Der einzige Customer, der diesem Filter entspricht, ist "Customer('ACME')", der in den Nutzdaten der Antwort angezeigt wird.

Einschränkung: Diese Abfrage funktioniert nur für nicht partitionierte Entitäten. Wenn Customer partitioniert it, ist der Schlüssel für den Customer erforderlich.
AtomPub
  • Methode: GET
  • Anforderungs-URI: http://localhost:8080/wxsrestservice/restservice/NorthwindGrid/Customer?$filter=contactName eq 'RoadRunner'
  • Anforderungsheader: Accept: application/atom+xml
  • Nutzdaten der Eingabe: Ohne
  • Antwortheader: Content-Type: application/atom+xml
  • Nutzdaten der Antwort:
    <?xml version="1.0" encoding="iso-8859-1"?>
    <feed
    	xml:base="http://localhost:8080/wxsrestservice/restservice"
    	xmlns:d="http://schemas.microsoft.com/ado/2007/08/
    			dataservices"
    xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"
    xmlns="http://www.w3.org/2005/Atom">
    	<title type="text">Customer</title>
    	<id>		http://localhost:8080/wxsrestservice/restservice/
    			NorthwindGrid/Customer	</id>
    	<updated>2009-09-16T04:59:28.656Z</updated>
    	<link rel="self" title="Customer" href="Customer" />
    	<entry>
    <category term="NorthwindGridModel.Customer"
    scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />
    		<id>
    http://localhost:8080/wxsrestservice/restservice/NorthwindGrid/		Customer('ACME')</id>
    		<title type="text" />
    		<updated>2009-09-16T04:59:28.656Z</updated>
    		<author>
    			<name />
    		</author>
    		<link rel="edit" title="Customer" href="Customer('ACME')" />
    		<link
    			rel="http://schemas.microsoft.com/ado/2007/08/dataservices/
    						related/orders"
    			type="application/atom+xml;type=feed" title="orders"
    			href="Customer('ACME')/orders" />
    		<content type="application/xml">
    			  <m:properties>
                <d:customerId>ACME</d:customerId>
                <d:city m:null = "true"/>
                <d:companyName>RoaderRunner</d:companyName>
                <d:contactName>ACME</d:contactName>
                <d:country m:null = "true"/>
                <d:version m:type = "Edm.Int32">3</d:version>
            </m:properties>
    		</content>
    	</entry>
    </feed>
  • Antwortcode: 200 OK
JSON
  • Methode: GET
  • Anforderungs-URI:

    http://localhost:8080/wxsrestservice/restservice/NorthwindGrid/Customer?$filter=contactName eq 'RoadRunner'

  • Anforderungsheader: Accept: application/json
  • Nutzdaten der Anforderung: Ohne
  • Antwortheader: Content-Type: application/json
  • Nutzdaten der Antwort:
    {"d":[{"__metadata":{"uri":"http://localhost:8080/wxsrestservice/
    			restservice/NorthwindGrid/Customer('ACME')",
    			"type":"NorthwindGridModel.Customer"},
    			"customerId":"ACME",
    			"city":null,
    			"companyName":"RoaderRunner",
    			"contactName":"ACME",
    			"country":null,
    			"version":3,
    			"orders":{"__deferred":{"uri":"http://localhost:8080/
    					wxsrestservice/restservice/NorthwindGrid/
    					Customer('ACME')/orders"}}}]}
  • Antwortcode: 200 OK

Systemoperator "$expand"

Der Systemoperator "$expand" kann verwendet werden, um Assoziationen zu erweitern. Die Assoziationen werden inline in der Antwort des Datenservice dargestellt. Assoziationen mit mehreren Werten (:N-Assoziationen) werden als Atom Feed Document oder JSON-Feldgruppe dargestellt. Assoziationen mit einem einzelnen Wert (:1-Assoziationen) werden als Atom Entry Document oder JSON-Objekt dargestellt.

Weitere Einzelheiten zum Systemoperator "$expand" finden Sie auf der Webseite Expand System Query Option ($expand).

Im Folgenden sehen Sie ein Beispiel für die Verwendung des Systemoperators "$expand2. In diesem Beispiel wird die Entität "Customer('IBM')" abgerufen, der die Bestellungen (Order) 5000, 5001 und andere zugeordnet sind. Die Klausel "$expand" wird auf "orders" gesetzt, so dass die Bestellsammlung inline in die Nutzdaten der Antwort aufgenommen wird. Hier werden nur die Bestellungen (Order) 5000 und 5001 gezeigt.

AtomPub
  • Methode: GET
  • Anforderungs-URI: http://localhost:8080/wxsrestservice/restservice/NorthwindGrid/Customer('IBM')?$expand=orders
  • Anforderungsheader: Accept: application/atom+xml
  • Nutzdaten der Anforderung: Ohne
  • Antwortheader: Content-Type: application/atom+xml
  • Nutzdaten der Antwort:
    <?xml version="1.0" encoding="utf-8"?>
    <entry xml:base = "http://localhost:8080/wxsrestservice/restservice"
    			xmlns:d ="http://schemas.microsoft.com/ado/2007/08/dataservices"
    			xmlns:m = "http://schemas.microsoft.com/ado/2007/08/dataservices/
    			metadata" xmlns = "http://www.w3.org/2005/Atom">
    <category term = "NorthwindGridModel.Customer" scheme = "http://schemas.
    
    microsoft.com/ado/2007/08/dataservices/scheme"/>
        <id>http://localhost:8080/wxsrestservice/restservice/NorthwindGrid/
    				Customer('IBM')</id>
        <title type = "text"/>
        <updated>2009-12-16T22:50:18.156Z</updated>
        <author>
            <name />
        </author><link rel = "edit" title = "Customer" href =
    				"Customer('IBM')"/>
        <link rel = "http://schemas.microsoft.com/ado/2007/08/dataservices/
    				related/orders" type = "application/atom+xml;type=feed" title =
    				"orders" href = "Customer('IBM')/orders">
            <m:inline>
                <feed>
                    <title type = "text">orders</title>
                    <id>http://localhost:8080/wxsrestservice/restservice/
    									NorthwindGrid/Customer('IBM')/orders</id>
                    <updated>2009-12-16T22:50:18.156Z</updated>
                    <link rel = "self" title = "orders" href = "Customer
    										('IBM')/orders"/>
                    <entry>
                        <category term = "NorthwindGridModel.Order" scheme =
    											"http://schemas.microsoft.com/ado/2007/08/
    											dataservices/scheme"/>
                        <id>http://localhost:8080/wxsrestservice/restservice/
    										NorthwindGrid/Order(orderId=5000,customer_customerId=
    												'IBM')</id>
                        <title type = "text"/>
                        <updated>2009-12-16T22:50:18.156Z</updated>
                        <author>
                            <name />
                        </author>
                        <link rel = "edit" title = "Order" href =
    									 "Order(orderId=5000,customer_customerId='IBM')"/>
                        <link rel = "http://schemas.microsoft.com/ado/2007/08/
    									 dataservices/related/customer" type = "application/
    									 atom+xml;type=entry" title ="customer" href =
    									 "Order(orderId=5000,customer_customerId='IBM')/customer"/>
                        <link rel = "http://schemas.microsoft.com/ado/2007/08/
    									 dataservices/related/orderDetails" type = "application/
    											atom+xml;type=feed" title ="orderDetails" href =
    											"Order(orderId=5000,customer_customerId='IBM')/orderDetails"/>
                        <content type="application/xml">
                            <m:properties>
                                <d:orderId m:type = "Edm.Int32">5000</d:orderId>
                                <d:customer_customerId>IBM</d:customer_customerId>
                                <d:orderDate m:type = "Edm.DateTime">
    																2009-12-16T19:46:29.562</d:orderDate>
                                <d:shipCity>Rochester</d:shipCity>
                                <d:shipCountry m:null = "true"/>
                                <d:version m:type = "Edm.Int32">0</d:version>
                            </m:properties>
                        </content>
                    </entry>
                    <entry>
                        <category term = "NorthwindGridModel.Order" scheme =
    											"http://schemas.microsoft.com/ado/2007/08/
    											dataservices/scheme"/>
                        <id>http://localhost:8080/wxsrestservice/restservice/
    									 NorthwindGrid/Order(orderId=5001,customer_customerId=
    									 'IBM')</id>
                        <title type = "text"/>
                        <updated>2009-12-16T22:50:18.156Z</updated>
                        <author>
                            <name/></author>
                        <link rel = "edit" title = "Order" href = "Order(
    orderId=5001,customer_customerId='IBM')"/>
                        <link rel = "http://schemas.microsoft.com/ado/2007/
    											08/dataservices/related/customer" type =
    											"application/atom+xml;type=entry" title =
    											"customer" href = "Order(orderId=5001,customer_customerId=
    											'IBM')/customer"/>
                        <link rel = "http://schemas.microsoft.com/ado/2007/08/
    												dataservices/related/orderDetails" type =
    												"application/atom+xml;type=feed" title =
    												"orderDetails" href = "Order(orderId=5001,
    												customer_customerId='IBM')/orderDetails"/>
                        <content type="application/xml">
                            <m:properties>
                                <d:orderId m:type = "Edm.Int32">5001</d:orderId>
                                <d:customer_customerId>IBM</d:customer_customerId>
                                <d:orderDate m:type = "Edm.DateTime">2009-12-16T19:
    															50:11.125</d:orderDate>
                                <d:shipCity>Rochester</d:shipCity>
                                <d:shipCountry m:null = "true"/>
                                <d:version m:type = "Edm.Int32">0</d:version>
                            </m:properties>
                        </content>
                    </entry>
                </feed>
            </m:inline>
        </link>
        <content type="application/xml">
            <m:properties>
                <d:customerId>IBM</d:customerId>
                <d:city m:null = "true"/>
                <d:companyName>IBM Corporation</d:companyName>
                <d:contactName>John Doe</d:contactName>
                <d:country m:null = "true"/>
                <d:version m:type = "Edm.Int32">4</d:version>
            </m:properties>
        </content>						
    </entry>
  • Antwortcode: 200 OK
JSON
  • Methode: GET
  • Anforderungs-URI: http://localhost:8080/wxsrestservice/restservice/NorthwindGrid/Customer('IBM')?$expand=orders
  • Anforderungsheader: Accept: application/json
  • Nutzdaten der Anforderung: Ohne
  • Antwortheader: Content-Type: application/json
  • Nutzdaten der Antwort:
    {"d":{"__metadata":{"uri":"http://localhost:8080/wxsrestservice/
    			restservice/NorthwindGrid/Customer('IBM')",
    	"type":"NorthwindGridModel.Customer"},
    "customerId":"IBM",
    "city":null,
    "companyName":"IBM Corporation",
    "contactName":"John Doe",
    "country":null,
    "version":4,
    "orders":[{"__metadata":{"uri":"http://localhost:8080/
    				wxsrestservice/restservice/NorthwindGrid/Order(
    				orderId=5000,customer_customerId='IBM')",
    "type":"NorthwindGridModel.Order"},
    "orderId":5000,
    "customer_customerId":"IBM",
    "orderDate":"\/Date(1260992789562)\/",
    "shipCity":"Rochester",
    "shipCountry":null,
    "version":0,
    "customer":{"__deferred":{"uri":"http://localhost:8080/
    			wxsrestservice/restservice/NorthwindGrid/Order(
    			orderId=5000,customer_customerId='IBM')/customer"}},
    "orderDetails":{"__deferred":{"uri":"http://localhost:
    					8080/wxsrestservice/restservice/NorthwindGrid/
    					Order(orderId=5000,customer_customerId='IBM')/
    					orderDetails"}}},
    {"__metadata":{"uri":"http://localhost:8080/wxsrestservice/
    					restservice/NorthwindGrid/Order(orderId=5001,
    					customer_customerId='IBM')","type":
    					"NorthwindGridModel.Order"},
    "orderId":5001,
    "customer_customerId":"IBM",
    "orderDate":"\/Date(1260993011125)\/",
    "shipCity":"Rochester",
    "shipCountry":null,
    "version":0,
    "customer":{"__deferred":{"uri":"http://localhost:
    			8080/wxsrestservice/restservice/
    NorthwindGrid/Order(orderId=5001,customer_customerId
    			='IBM')/customer"}},
    "orderDetails":{"__deferred":{"uri":"http://localhost:8080/
    			wxsrestservice/restservice/NorthwindGrid/Order(
    			orderId=5001,	customer_customerId='IBM')/
    			orderDetails"}}}]}}
  • Antwortcode: 200 OK