Verwendung FetchXML mit Web-API
FetchXML ist eine proprietäre Abfragesprache, die Daten mithilfe der Web-API und des .NET SDK abrufen und aggregieren kann. Weitere Informationen: Verwenden FetchXML Sie können damit Daten abfragen.
Hinweis
Im Gegensatz zu Abfragen, die die OData-Syntax verwenden, FetchXML geben 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.
Beispielsweise hat das Folgende FetchXML die account
Entität:
<fetch mapping='logical'>
<entity name='account'>
<attribute name='accountid'/>
<attribute name='name'/>
<attribute name='accountnumber'/>
</entity>
</fetch>
Dies FetchXML hat den folgenden URL-codierten 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
Anforderung unter Verwendung der vorherigen FetchXML mit dem Entitätspfad für 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)"
}
]
}
Denken Sie daran, dass Eigenschaften mit Nullwerten nicht in den mit FetchXML zurückgegebenen Ergebnissen enthalten sind. In diesem Beispiel hat nur der erste zurückgegebene Datensatz den Wert accountnumber
.
Paging mit FetchXML
Mit FetchXML können Sie eine einfache Paginierung anwenden, indem Sie die Attribute page
und count
des fetch
Elements festlegen. 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
pagingcookie
zweimal.Den dekodierten Wert des Attributs
pagingcookie
in XML kodieren und ihn als Wert eines Attributspaging-cookie
auf dem Elementfetch
festlegen.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 das FetchXML vor der URL-Codierung folgendermaßen 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"
}
]
}
Verwendung FetchXML innerhalb einer Batch-Anfrage
Die Länger einer URL in einer GET
-Anforderung wird auf 32 KB (32.768 Zeichen) begrenzt. Das Einfügen von FetchXML als Parameter in die URL kann das Limit erreichen. Sie können einen $batch
Vorgang mithilfe einer POST
Anforderung ausführen, um den FetchXML Wert aus der URL in den Textkörper der Anforderung zu verschieben, wo die Beschränkung 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
Verwenden Sie FetchXML zum Erstellen einer Abfrage
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).