Usar FetchXML con API web
FetchXML es un lenguaje de consulta patentado que puede recuperar y agregar datos mediante la API web y el SDK de .NET. Más información: Usar FetchXML para consultar datos.
Nota
A diferencia de las consultas que utilizan la sintaxis de OData, las consultas de FetchXML no devuelven propiedades con valores null.
Puede redactar una consulta FetchXML para una tabla específica. Luego, codifique en URL el XML y use el parámetro fetchXml de cadena de consulta para pasarlo al conjunto de entidades.
Por ejemplo, el siguiente FetchXML tiene account como la entidad:
<fetch mapping='logical'>
<entity name='account'>
<attribute name='accountid'/>
<attribute name='name'/>
<attribute name='accountnumber'/>
</entity>
</fetch>
Este FetchXML tiene el siguiente valor codificado en URL:
%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
La mayoría de los lenguaje de programación incluyen una función para codificar como dirección URL una cadena.
- En JavaScript, usa la función encodeURI.
- En .NET, puede usar el método System.NET.WebUtility.UrlEncode(String)
Debe codificar como dirección URL cualquier solicitud que envíe a cualquier servicio web RESTful. Si pega una dirección URL en la barra de direcciones del explorador, debe codificar como dirección URL la dirección automáticamente.
El siguiente ejemplo muestra una solicitud GET mediante el FetchXML anterior con la ruta del conjunto de entidades para accounts. Pasa el XML codificado usando este parámetro: ?fetchXml=
Solicitud:
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
Respuesta:
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)"
}
]
}
Recuerde que las propiedades con valores nulos no se incluuen en los resultados devueltos mediante FetchXML. En este ejemplo, solo el primer registro devuelto tiene un valor accountnumber.
Paginación con FetchXML
Con FetchXML, puede aplicar paginación simple estableciendo los atributos page y count del elemento fetch. Por ejemplo, las siguientes cuentas de consultas fetchXML, limita el número de entidades a 2 y devuelve solamente la primera página:
<fetch mapping="logical"
page="1"
count="2">
<entity name="account">
<attribute name="accountid" />
<attribute name="name" />
<attribute name="industrycode" />
<order attribute="name" />
</entity>
</fetch>
Paginar grandes conjuntos de resultados
Cuando trabaja con grandes conjuntos de resultados que alcanzan el límite de paginación de 5000, el uso de cookies de paginación con la consulta ayuda a mejorar el rendimiento. Solicite una cookie de paginación como anotación. Utilice el encabezado de solicitud prefer: odata.include-annotations para usar o incluir Microsoft.Dynamics.CRM.fetchxmlpagingcookie y se devuelve una anotación @Microsoft.Dynamics.CRM.fetchxmlpagingcookie con el resultado.
La siguiente serie de solicitudes de FetchXML muestra el uso de cookies de paginación. Este ejemplo utiliza un pequeño valor count (3) por brevedad. Normalmente no usaría cookies de paginación para tamaños de página tan pequeños.
<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>
Primera página
Envíe la primera página con el conjunto de valores page en '1'. Utilice el encabezado de solicitud Prefer: odata.include-annotations="*" para asegurarse de que se devuelvan las anotaciones necesarias en la respuesta.
Solicitud:
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
Respuesta:
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"
}
]
}
En la respuesta, el valor de anotación @Microsoft.Dynamics.CRM.morerecords indica que existen más registros que coinciden con los criterios.
El valor de anotación @Microsoft.Dynamics.CRM.fetchxmlpagingcookie proporciona la información de paginación sobre el registro devuelto. El valor @Microsoft.Dynamics.CRM.fetchxmlpagingcookie es un documento XML. Debe usar el valor de atributo pagingcookie de ese documento en la siguiente solicitud.
El valor del atributo pagingcookie se codifica dos veces medianate URL. El valor descodificado tiene este aspecto:
<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>
Siguientes páginas
En todas las solicitudes posteriores donde el valor de anotación de la página anterior @Microsoft.Dynamics.CRM.morerecords indica que existen más registros, debe:
Incrementar el valor de atributo
pagedel elementofetch.Decodificar la URL del valor de atributo
pagingcookiedos veces.Codificar en XML el valor de atributo
pagingcookiedecodificado y establecerlo como el valor de un atributopaging-cookieen el elementofetch.Si debe codificar XML explícitamente el valor puede depender de la tecnología que utilice. En .NET, se puede hacer por usted cuando establece el valor XML en un atributo de otro elemento XML.
URL codifica todo el valor de FetchXML como lo hizo en la primera solicitud.
En la siguiente solicitud, el FetchXML tiene este aspecto antes de codificarse como URL:
<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>
Solicitud:
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
Respuesta:
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"
}
]
}
Última página
En la página final, las anotaciones @Microsoft.Dynamics.CRM.morerecords y @Microsoft.Dynamics.CRM.fetchxmlpagingcookie no se incluyen en la respuesta.
Solicitud:
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
Respuesta:
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"
}
]
}
Use FetchXML en una solicitud de lote
La longitud de una URL en una solicitud GET está limitada a 32 KB (32 768 caracteres). Incluir FetchXML como parámetro en la dirección URL pueden alcanzar el límite. Puede ejecutar una operación $batch con una solicitud POST como método para mover el FetchXML de la dirección URL al cuerpo de la solicitud donde no aplica el límite. Enviar una solicitud de GET dentro de un $batch permite que las tengan hasta 64 KB (65 536 caracteres). Más que con una solicitud de GET normal, pero no es ilimitada. Más información:Ejecute las operaciones por lotes mediante API web
Ejemplo
Solicitud:
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--
Respuesta:
--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--
Consulte también
Usar FetchXML para crear una consulta
Consultar datos utilizando la API web
Recuperar y ejecutar consultas predefinidas
Nota
¿Puede indicarnos sus preferencias de idioma de documentación? Realice una breve encuesta. (tenga en cuenta que esta encuesta está en inglés)
La encuesta durará unos siete minutos. No se recopilan datos personales (declaración de privacidad).
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de