Verwenden von FetchXML mit Web-API
FetchXML ist eine proprietäre Abfragesprache, mit der Daten über die Web-API und das .NET SDK abgerufen und aggregiert werden können. Weitere Informationen: Verwendung von FetchXML zum Abfragen von Daten.
Hinweis
Anders als Abfragen, die die OData-Syntax verwenden, geben FetchXML-Abfragen keine Eigenschaften mit null-Werten zurück.
Sie können eine FetchXML-Abfrage für eine bestimmte Tabelle erstellen. Anschließend kodieren Sie das XML per URL und verwenden den Parameter fetchXml für die Zeichenfolge der Abfrage, um es an die Entität zu übergeben.
Das folgende FetchXML hat zum Beispiel account als Entität:
<fetch mapping='logical'>
<entity name='account'>
<attribute name='accountid'/>
<attribute name='name'/>
<attribute name='accountnumber'/>
</entity>
</fetch>
Dieses FetchXML hat den folgenden URL-verschlüsselten Wert:
%3Cfetch%20mapping%3D%27logical%27%3E%3Centity%20name%3D%27account%27%3E%3Cattribute%20name%3D%27accountid%27%2F%3E%3Cattribute%20name%3D%27name%27%2F%3E%3Cattribute%20name%3D%27accountnumber%27%2F%3E%3C%2Fentity%3E%3C%2Ffetch%3E
Die meisten Programmiersprachen enthalten eine Funktion zur URL-Kodierung einer Zeichenfolge.
- In JavaScript verwenden Sie die Funktion encodeURI.
- In .NET können Sie die Methode System.NET.WebUtility.UrlEncode(String) verwenden.
Sie sollten jede Anfrage, die Sie an einen RESTful Web Service senden, mit einer URL-Kodierung versehen. Wenn Sie eine URL in die Adressleiste Ihres Browsers einfügen, sollte die URL-Kodierung der Adresse automatisch erfolgen.
Das folgende Beispiel zeigt eine GET-Abfrage unter Verwendung des vorherigen FetchXML mit dem Pfad für die Entität accounts. Sie übergibt das kodierte XML mit diesem Parameter: ?fetchXml=
Anforderung:
GET [Organization URI]/api/data/v9.2/accounts?fetchXml=%3Cfetch%20mapping%3D%27logical%27%3E%3Centity%20name%3D%27account%27%3E%3Cattribute%20name%3D%27accountid%27%2F%3E%3Cattribute%20name%3D%27name%27%2F%3E%3Cattribute%20name%3D%27accountnumber%27%2F%3E%3C%2Fentity%3E%3C%2Ffetch%3E HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
Antwort:
HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
{
"@odata.context":"[Organization URI]/api/data/v9.2/$metadata#accounts(accountid,name)","value":[
{
"@odata.etag":"W/\"506678\"",
"accountid":"89390c24-9c72-e511-80d4-00155d2a68d1",
"name":"Fourth Coffee (sample)",
"accountnumber":"1234",
},{
"@odata.etag":"W/\"502172\"",
"accountid":"8b390c24-9c72-e511-80d4-00155d2a68d1",
"name":"Litware, Inc. (sample)"
},{
"@odata.etag":"W/\"502174\"",
"accountid":"8d390c24-9c72-e511-80d4-00155d2a68d1",
"name":"Adventure Works (sample)"
},{
"@odata.etag":"W/\"506705\"",
"accountid":"8f390c24-9c72-e511-80d4-00155d2a68d1",
"name":"Fabrikam, Inc. (sample)"
}
]
}
Erinnern Sie sich daran, dass Eigenschaften mit Nullwerten in den mit FetchXML zurückgegebenen Ergebnissen nicht enthalten sind. In diesem Beispiel hat nur der erste zurückgegebene Datensatz den Wert accountnumber.
Paging mit FetchXML
Mit FetchXML können Sie ein einfaches Paging anwenden, indem Sie die Attribute page und count des Elements fetch setzen. Die folgende FetchXML-Abfrage fragt z.B. Konten ab, begrenzt die Anzahl der Entitäten auf 2 und gibt nur die erste Seite zurück:
<fetch mapping="logical"
page="1"
count="2">
<entity name="account">
<attribute name="accountid" />
<attribute name="name" />
<attribute name="industrycode" />
<order attribute="name" />
</entity>
</fetch>
Paging von umfangreichen Ergebnissätzen
Wenn Sie mit großen Ergebnismengen arbeiten, die die Auslagerungsgrenze von 5.000 erreichen, können Sie die Leistung durch die Verwendung von Auslagerungs-Cookies in der Abfrage verbessern. Fordern Sie einen Paging-Cookie als Anmerkung an. Verwenden Sie den Anfrage-Header prefer: odata.include-annotations, um Microsoft.Dynamics.CRM.fetchxmlpagingcookie zu verwenden oder einzuschließen, und eine @Microsoft.Dynamics.CRM.fetchxmlpagingcookie-Anmerkung wird mit dem Ergebnis zurückgegeben.
Die folgende Reihe von FetchXML-Anfragen zeigt die Verwendung von Paging-Cookies. In diesem Beispiel wird der Einfachheit halber ein kleiner count-Wert (3) verwendet. Normalerweise würden Sie keine Paging-Cookies für so kleine Seitengrößen verwenden.
<fetch page='1'
count='3'
paging-cookie=''
mapping='logical'
output-format='xml-platform'
version='1.0'
distinct='false'>
<entity name ='contact'>
<attribute name ='fullname' />
<attribute name ='jobtitle' />
<attribute name ='annualincome' />
<order descending ='true'
attribute='fullname' />
<filter type ='and'>
<condition value ='%(sample)%'
attribute='fullname'
operator='like' />
<condition value ='18717e9c-643f-ed11-9db0-002248225e95'
attribute='parentcustomerid'
operator='eq' />
</filter>
</entity>
</fetch>
Erste Seite
Senden Sie die erste Seite mit dem page-Wert von '1'. Verwenden Sie die Abfragekopfzeile Prefer: odata.include-annotations="*", um sicherzustellen, dass die notwendigen Anmerkungen in der Antwort zurückgegeben werden.
Anforderung:
GET [Organization Uri]/api/data/v9.2/contacts?fetchXml=%3Cfetch+page%3D%221%22+count%3D%223%22+mapping%3D%22logical%22+output-format%3D%22xml-platform%22+version%3D%221.0%22+distinct%3D%22false%22%3E%0D%0A++%3Centity+name%3D%22contact%22%3E%0D%0A++++%3Cattribute+name%3D%22fullname%22+%2F%3E%0D%0A++++%3Cattribute+name%3D%22jobtitle%22+%2F%3E%0D%0A++++%3Cattribute+name%3D%22annualincome%22+%2F%3E%0D%0A++++%3Corder+descending%3D%22true%22+attribute%3D%22fullname%22+%2F%3E%0D%0A++++%3Cfilter+type%3D%22and%22%3E%0D%0A++++++%3Ccondition+value%3D%22%25(sample)%25%22+attribute%3D%22fullname%22+operator%3D%22like%22+%2F%3E%0D%0A++++++%3Ccondition+value%3D%2218717e9c-643f-ed11-9db0-002248225e95%22+attribute%3D%22parentcustomerid%22+operator%3D%22eq%22+%2F%3E%0D%0A++++%3C%2Ffilter%3E%0D%0A++%3C%2Fentity%3E%0D%0A%3C%2Ffetch%3E&$count=true HTTP/1.1
Prefer: odata.include-annotations="*"
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json
Antwort:
HTTP/1.1 200 OK
OData-Version: 4.0
Preference-Applied: odata.include-annotations="*"
{
"@odata.context": "[Organization Uri]/api/data/v9.2/$metadata#contacts(fullname,jobtitle,annualincome,_transactioncurrencyid_value,transactioncurrencyid,contactid,transactioncurrencyid())",
"@odata.count": 8,
"@Microsoft.Dynamics.CRM.totalrecordcount": 8,
"@Microsoft.Dynamics.CRM.totalrecordcountlimitexceeded": false,
"@Microsoft.Dynamics.CRM.globalmetadataversion": "74343461",
"@Microsoft.Dynamics.CRM.fetchxmlpagingcookie": "<cookie pagenumber=\"2\" pagingcookie=\"%253ccookie%2520page%253d%25221%2522%253e%253cfullname%2520last%253d%2522Robert%2520Lyon%2520%2528sample%2529%2522%2520first%253d%2522Susanna%2520Stubberod%2520%2528sample%2529%2522%2520%252f%253e%253ccontactid%2520last%253d%2522%257b30717E9C-643F-ED11-9DB0-002248225E95%257d%2522%2520first%253d%2522%257b20717E9C-643F-ED11-9DB0-002248225E95%257d%2522%2520%252f%253e%253c%252fcookie%253e\" istracking=\"False\" />",
"@Microsoft.Dynamics.CRM.morerecords": true,
"value": [
{
"@odata.etag": "W/\"74359676\"",
"fullname": "Susanna Stubberod (sample)",
"jobtitle": "Senior Purchaser",
"annualincome@OData.Community.Display.V1.FormattedValue": "$52,000.00",
"annualincome": 52000.0,
"contactid": "20717e9c-643f-ed11-9db0-002248225e95"
},
{
"@odata.etag": "W/\"74359706\"",
"fullname": "Scott Konersmann (sample)",
"jobtitle": "Accounts Manager",
"annualincome@OData.Community.Display.V1.FormattedValue": "$38,000.00",
"annualincome": 38000.0,
"contactid": "2c717e9c-643f-ed11-9db0-002248225e95"
},
{
"@odata.etag": "W/\"74359716\"",
"fullname": "Robert Lyon (sample)",
"jobtitle": "Senior Technician",
"annualincome@OData.Community.Display.V1.FormattedValue": "$78,000.00",
"annualincome": 78000.0,
"contactid": "30717e9c-643f-ed11-9db0-002248225e95"
}
]
}
In der Antwort zeigt der Wert der Anmerkung @Microsoft.Dynamics.CRM.morerecords an, dass mehr Datensätze existieren, die den Kriterien entsprechen.
Der @Microsoft.Dynamics.CRM.fetchxmlpagingcookie-Anmerkungswert stellt die Paging-Informationen über den zurückgegebenen Datensatz bereit. Der @Microsoft.Dynamics.CRM.fetchxmlpagingcookie-Wert ist ein XML-Dokument. Sie müssen den Wert des Attributs pagingcookie dieses Dokuments in der nächsten Anfrage verwenden.
Der Wert des Attributs pagingcookie ist zweimal URL-kodiert. Die decodierte Wert sieht wie folgt aus:
<cookie page="1"><fullname last="Robert Lyon (sample)" first="Susanna Stubberod (sample)" /><contactid last="{30717E9C-643F-ED11-9DB0-002248225E95}" first="{20717E9C-643F-ED11-9DB0-002248225E95}" /></cookie>
Folgende Seiten
In allen nachfolgenden Anfragen, bei denen der Wert der Anmerkung @Microsoft.Dynamics.CRM.morerecords auf der vorherigen Seite anzeigt, dass weitere Datensätze vorhanden sind, müssen Sie dies tun:
Erhöhung des
fetch-Elementpage-Attributwerts.URL-dekodiert den Wert des Attributs
pagingcookiezweimal.Den dekodierten Wert des Attributs
pagingcookiein XML kodieren und ihn als Wert eines Attributspaging-cookieauf dem Elementfetchfestlegen.Ob Sie den Wert explizit XML-kodieren müssen, kann von der von Ihnen verwendeten Technologie abhängen. In .NET wird dies möglicherweise für Sie erledigt, wenn Sie den XML-Wert auf ein Attribut eines anderen XML-Elements setzen.
URL-codieren Sie den gesamten FetchXml-Wert wie bei der ersten Anforderung.
In der folgenden Anfrage sieht die FetchXML vor der URL-Kodierung wie folgt aus:
<fetch page="2" count="3" mapping="logical" output-format="xml-platform" version="1.0" distinct="false" paging-cookie="<cookie page="1"><fullname last="Robert Lyon (sample)" first="Susanna Stubberod (sample)" /><contactid last="{30717E9C-643F-ED11-9DB0-002248225E95}" first="{20717E9C-643F-ED11-9DB0-002248225E95}" /></cookie>">
<entity name="contact">
<attribute name="fullname" />
<attribute name="jobtitle" />
<attribute name="annualincome" />
<order descending="true" attribute="fullname" />
<filter type="and">
<condition value="%(sample)%" attribute="fullname" operator="like" />
<condition value="18717e9c-643f-ed11-9db0-002248225e95" attribute="parentcustomerid" operator="eq" />
</filter>
</entity>
</fetch>
Anforderung:
GET [Organization Uri]/api/data/v9.2/contacts?fetchXml=%3Cfetch+page%3D%222%22+count%3D%223%22+mapping%3D%22logical%22+output-format%3D%22xml-platform%22+version%3D%221.0%22+distinct%3D%22false%22+paging-cookie%3D%22%26lt%3Bcookie+page%3D%26quot%3B1%26quot%3B%26gt%3B%26lt%3Bfullname+last%3D%26quot%3BRobert+Lyon+(sample)%26quot%3B+first%3D%26quot%3BSusanna+Stubberod+(sample)%26quot%3B+%2F%26gt%3B%26lt%3Bcontactid+last%3D%26quot%3B%7B30717E9C-643F-ED11-9DB0-002248225E95%7D%26quot%3B+first%3D%26quot%3B%7B20717E9C-643F-ED11-9DB0-002248225E95%7D%26quot%3B+%2F%26gt%3B%26lt%3B%2Fcookie%26gt%3B%22%3E%0D%0A++%3Centity+name%3D%22contact%22%3E%0D%0A++++%3Cattribute+name%3D%22fullname%22+%2F%3E%0D%0A++++%3Cattribute+name%3D%22jobtitle%22+%2F%3E%0D%0A++++%3Cattribute+name%3D%22annualincome%22+%2F%3E%0D%0A++++%3Corder+descending%3D%22true%22+attribute%3D%22fullname%22+%2F%3E%0D%0A++++%3Cfilter+type%3D%22and%22%3E%0D%0A++++++%3Ccondition+value%3D%22%25(sample)%25%22+attribute%3D%22fullname%22+operator%3D%22like%22+%2F%3E%0D%0A++++++%3Ccondition+value%3D%2218717e9c-643f-ed11-9db0-002248225e95%22+attribute%3D%22parentcustomerid%22+operator%3D%22eq%22+%2F%3E%0D%0A++++%3C%2Ffilter%3E%0D%0A++%3C%2Fentity%3E%0D%0A%3C%2Ffetch%3E&$count=true HTTP/1.1
Prefer: odata.include-annotations="*"
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json
Antwort:
HTTP/1.1 200 OK
OData-Version: 4.0
Preference-Applied: odata.include-annotations="*"
{
"@odata.context": "[Organization Uri]/api/data/v9.2/$metadata#contacts(fullname,jobtitle,annualincome,_transactioncurrencyid_value,transactioncurrencyid,contactid,transactioncurrencyid())",
"@odata.count": 8,
"@Microsoft.Dynamics.CRM.totalrecordcount": 8,
"@Microsoft.Dynamics.CRM.totalrecordcountlimitexceeded": false,
"@Microsoft.Dynamics.CRM.globalmetadataversion": "74343461",
"@Microsoft.Dynamics.CRM.fetchxmlpagingcookie": "<cookie pagenumber=\"2\" pagingcookie=\"%253ccookie%2520page%253d%25222%2522%253e%253cfullname%2520last%253d%2522Nancy%2520Anderson%2520%2528sample%2529%2522%2520first%253d%2522Rene%2520Valdes%2520%2528sample%2529%2522%2520%252f%253e%253ccontactid%2520last%253d%2522%257b24717E9C-643F-ED11-9DB0-002248225E95%257d%2522%2520first%253d%2522%257b38717E9C-643F-ED11-9DB0-002248225E95%257d%2522%2520%252f%253e%253c%252fcookie%253e\" istracking=\"False\" />",
"@Microsoft.Dynamics.CRM.morerecords": true,
"value": [
{
"@odata.etag": "W/\"74359736\"",
"fullname": "Rene Valdes (sample)",
"jobtitle": "Data Analyst III",
"annualincome@OData.Community.Display.V1.FormattedValue": "$86,000.00",
"annualincome": 86000.0,
"contactid": "38717e9c-643f-ed11-9db0-002248225e95"
},
{
"@odata.etag": "W/\"74359726\"",
"fullname": "Paul Cannon (sample)",
"jobtitle": "Ski Instructor",
"annualincome@OData.Community.Display.V1.FormattedValue": "$68,500.00",
"annualincome": 68500.0,
"contactid": "34717e9c-643f-ed11-9db0-002248225e95"
},
{
"@odata.etag": "W/\"74359686\"",
"fullname": "Nancy Anderson (sample)",
"jobtitle": "Activities Manager",
"annualincome@OData.Community.Display.V1.FormattedValue": "$55,500.00",
"annualincome": 55500.0,
"contactid": "24717e9c-643f-ed11-9db0-002248225e95"
}
]
}
Letzte Seite
Auf der endgültigen Seite sind die Anmerkungen @Microsoft.Dynamics.CRM.morerecords und @Microsoft.Dynamics.CRM.fetchxmlpagingcookie nicht in der Antwort enthalten.
Anforderung:
GET [Organization Uri]/api/data/v9.2/contacts?fetchXml=%3Cfetch+page%3D%223%22+count%3D%223%22+mapping%3D%22logical%22+output-format%3D%22xml-platform%22+version%3D%221.0%22+distinct%3D%22false%22+paging-cookie%3D%22%26lt%3Bcookie+page%3D%26quot%3B2%26quot%3B%26gt%3B%26lt%3Bfullname+last%3D%26quot%3BNancy+Anderson+(sample)%26quot%3B+first%3D%26quot%3BRene+Valdes+(sample)%26quot%3B+%2F%26gt%3B%26lt%3Bcontactid+last%3D%26quot%3B%7B24717E9C-643F-ED11-9DB0-002248225E95%7D%26quot%3B+first%3D%26quot%3B%7B38717E9C-643F-ED11-9DB0-002248225E95%7D%26quot%3B+%2F%26gt%3B%26lt%3B%2Fcookie%26gt%3B%22%3E%0D%0A++%3Centity+name%3D%22contact%22%3E%0D%0A++++%3Cattribute+name%3D%22fullname%22+%2F%3E%0D%0A++++%3Cattribute+name%3D%22jobtitle%22+%2F%3E%0D%0A++++%3Cattribute+name%3D%22annualincome%22+%2F%3E%0D%0A++++%3Corder+descending%3D%22true%22+attribute%3D%22fullname%22+%2F%3E%0D%0A++++%3Cfilter+type%3D%22and%22%3E%0D%0A++++++%3Ccondition+value%3D%22%25(sample)%25%22+attribute%3D%22fullname%22+operator%3D%22like%22+%2F%3E%0D%0A++++++%3Ccondition+value%3D%2218717e9c-643f-ed11-9db0-002248225e95%22+attribute%3D%22parentcustomerid%22+operator%3D%22eq%22+%2F%3E%0D%0A++++%3C%2Ffilter%3E%0D%0A++%3C%2Fentity%3E%0D%0A%3C%2Ffetch%3E&$count=true HTTP/1.1
Prefer: odata.include-annotations="*"
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json
Antwort:
HTTP/1.1 200 OK
OData-Version: 4.0
Preference-Applied: odata.include-annotations="*"
{
"@odata.context": "[Organization Uri]/api/data/v9.2/$metadata#contacts(fullname,jobtitle,annualincome,_transactioncurrencyid_value,transactioncurrencyid,contactid,transactioncurrencyid())",
"@odata.count": 8,
"@Microsoft.Dynamics.CRM.totalrecordcount": 8,
"@Microsoft.Dynamics.CRM.totalrecordcountlimitexceeded": false,
"@Microsoft.Dynamics.CRM.globalmetadataversion": "74343461",
"value": [
{
"@odata.etag": "W/\"74359696\"",
"fullname": "Maria Cambell (sample)",
"jobtitle": "Accounts Manager",
"annualincome@OData.Community.Display.V1.FormattedValue": "$31,000.00",
"annualincome": 31000.0,
"contactid": "28717e9c-643f-ed11-9db0-002248225e95"
},
{
"@odata.etag": "W/\"74359746\"",
"fullname": "Jim Glynn (sample)",
"jobtitle": "Senior International Sales Manager",
"annualincome@OData.Community.Display.V1.FormattedValue": "$81,400.00",
"annualincome": 81400.0,
"contactid": "3c717e9c-643f-ed11-9db0-002248225e95"
}
]
}
Verwenden Sie FetchXML innerhalb einer Batch-Anforderung
Die Länger einer URL in einer GET-Anforderung wird auf 32 KB (32.768 Zeichen) begrenzt. Wenn Sie FetchXML als Parameter in die URL aufnehmen, kann das Limit erreicht werden. Sie können einen $batch-Vorgang mit einer POST-Anfrage ausführen, um die FetchXML aus der URL in den Hauptteil der Anfrage zu verschieben, wo das Limit nicht gilt. Das Senden einer GET-Anfrage innerhalb eines $batch lässt URLs mit einer Länge von bis zu 64 KB (65.536 Zeichen) zu. Mehr als bei einer normalen GET-Abfrage, aber es ist nicht unbegrenzt. Weitere Informationen: Ausführen von Batchvorgängen mit der Web-API.
Beispiel
Anforderung:
POST [Organization URI]/api/data/v9.2/$batch HTTP/1.1
Content-Type:multipart/mixed;boundary=batch_AAA123
Accept:application/json
OData-MaxVersion:4.0
OData-Version:4.0
--batch_AAA123
Content-Type: application/http
Content-Transfer-Encoding: binary
GET [Organization URI]/api/data/v9.2/accounts?fetchXml=%3Cfetch%20mapping='logical'%3E%3Centity%20name='account'%3E%3Cattribute%20name='accountid'/%3E%3Cattribute%20name='name'/%3E%3Cattribute%20name='telephone1'/%3E%3Cattribute%20name='accountid'/%3E%3Cattribute%20name='creditonhold'/%3E%3C/entity%3E%3C/fetch%3E HTTP/1.1
Content-Type: application/json
OData-Version: 4.0
OData-MaxVersion: 4.0
--batch_AAA123--
Antwort:
--batchresponse_cbfd44cd-a322-484e-913b-49e18af44e34
Content-Type: application/http
Content-Transfer-Encoding: binary
HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
{
"@odata.context":"[Organization URI]/api/data/v9.2/$metadata#accounts(accountid,name,telephone1,creditonhold)",
"value":[
{
"@odata.etag":"W/\"563737\"",
"accountid":"1f55c679-485e-e811-8151-000d3aa3c22a",
"name":"Fourth Coffee (sample)",
"telephone1":"+1-425-555-0121",
"creditonhold":false
},
{
"@odata.etag":"W/\"563739\"",
"accountid":"2555c679-485e-e811-8151-000d3aa3c22a",
"name":"Litware, Inc. (sample)",
"telephone1":"+1-425-555-0120",
"creditonhold":false
}
]
}
--batchresponse_cbfd44cd-a322-484e-913b-49e18af44e34--
Siehe auch
FetchXML verwenden, um eine Abfrage zu erstellen
Abfrage von Daten über die Web-API
Vordefinierte Abfragen abrufen und ausführen
Hinweis
Können Sie uns Ihre Präferenzen für die Dokumentationssprache mitteilen? Nehmen Sie an einer kurzen Umfrage teil. (Beachten Sie, dass diese Umfrage auf Englisch ist.)
Die Umfrage dauert etwa sieben Minuten. Es werden keine personenbezogenen Daten erhoben. (Datenschutzbestimmungen).
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für