Recuperar registros de tabla relacionados con una consulta
Use la opción de consulta del sistema $expand con las propiedades de navegación para controlar cómo se devuelven los datos de registros de tabla relacionadps.
Nota
- Usted está limitado a no más de 15 opciones
$expanden una consulta. La razón es proteger el rendimiento. Cada una de las opciones$expandcrea una unión que puede afectar al rendimiento. - Las consultas que expanden propiedades de navegación valorada como colección pueden devolver datos en caché para las propiedades que no reflejan cambios recientes. Se recomienda usar el encabezado
If-None-Matchcon valornullpara reemplazar el almacenamiento en la memoria caché del explorador. Más información: Encabezados HTTP para obtener más detalles.
Puede aplicar las siguientes opciones de consulta del sistema dentro de ciertas opciones de $expand:
| Opción | Description |
|---|---|
$select |
Seleccione qué propiedades se devuelven. Más información: Limitar columnas con $select |
$filter |
Para las propiedades de navegación con valor de colección, limite los registros devueltos. Más información: Filtrar resultados |
$orderby |
Para las propiedades de navegación con valor de colección, controle el orden de los registros devueltos. No es compatible con $expand anidado. Más información: $expand anidado en propiedades de navegación valorada en una colección |
$top |
Para las propiedades de navegación con valor de colección, limite el número de registros devueltos. No es compatible con $expand anidado. Más información: $expand anidado en propiedades de navegación valorada en una colección |
$expand |
Expanda las propiedades de navegación en el conjunto de entidades relacionadas. El uso de $expand dentro de $expand se denomina $expand anidado. Más información: Expansión anidada de propiedades de navegación de un único valor y $expand anidado en propiedades de navegación con valor de colección |
Estas opciones son un subconjunto de las opciones de consulta del sistema descritas en la sección 11.2.4.2.1 Opciones de ampliación de OData versión 4.0 parte 1, Protocol Plus Errata 02. Las opciones $skip, $count, $search y $levels no se admiten para la API web de Dataverse.
Use estas opciones con $expand agregándolas entre paréntesis después del nombre de la propiedad de navegación. Separe cada opción con punto y coma. Por ejemplo:
/accounts?$select=name&$expand=Account_Tasks($select=subject;$filter=contains(subject,'Task');$orderby=createdon desc)
Limitar columnas con $select
Siempre limite las columnas devueltas usando $select cuando use $expand. Por ejemplo, la siguiente solicitud devuelve los valores contact.fullname y task.subject en los resultados expandidos del tipo de entidad account.
Solicitar
GET [Organization URI]/api/data/v9.2/accounts?$select=name
&$expand=primarycontactid($select=fullname),Account_Tasks($select=subject) HTTP/1.1
Prefer: odata.maxpagesize=1
If-None-Match: null
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
Response
HTTP/1.1 200 OK
OData-Version: 4.0
Preference-Applied: odata.maxpagesize=1
{
"@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts(name,primarycontactid(fullname),Account_Tasks(subject))",
"value": [
{
"@odata.etag": "W/\"80649578\"",
"name": "Litware, Inc. (sample)",
"accountid": "78914942-34cb-ed11-b596-0022481d68cd",
"primarycontactid": {
"fullname": "Susanna Stubberod (sample)",
"contactid": "70bf4d48-34cb-ed11-b596-0022481d68cd"
},
"Account_Tasks": [
{
"@odata.etag": "W/\"80649460\"",
"subject": "Task 1 for Litware",
"_regardingobjectid_value": "78914942-34cb-ed11-b596-0022481d68cd",
"activityid": "f68393c1-34cb-ed11-b597-000d3a993550"
}
],
"Account_Tasks@odata.nextLink": "[Organization URI]/api/data/v9.2/accounts(78914942-34cb-ed11-b596-0022481d68cd)/Account_Tasks?$select=subject"
}
],
"@odata.nextLink": "[Organization URI]/api/data/v9.2/accounts?$select=name&$expand=primarycontactid($select=fullname),Account_Tasks($select=subject)&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%253e%253caccountid%2520last%253d%2522%257b78914942-34CB-ED11-B596-0022481D68CD%257d%2522%2520first%253d%2522%257b78914942-34CB-ED11-B596-0022481D68CD%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E"
}
Diferencias de tipo de propiedad de navegación
Es importante recordar que hay dos tipos de propiedades de navegación. Más información: Propiedades de navegación de la API web
Las propiedades de navegación de un solo valor corresponden a atributos de búsqueda que admiten relaciones de varios a uno y permiten establecer una referencia a otro registro.
Las propiedades de navegación valoradas como colección corresponden a relaciones de uno a varios o de varios a varios.
Expandir una propiedad de navegación con valor de colección puede hacer que el tamaño de la respuesta sea grande en formas difíciles de anticipar. Es importante que incluya límites para controlar la cantidad de datos que se devuelven. El encabezado de solicitud Prefer: odata.maxpagesize es la forma más común de limitar la cantidad de registros devueltos, aunque también puede usar $top. Más información: Especifique el número de filas para devolver a una página
Nota
Hay una diferencia significativa en cómo se aplica la paginación a las opciones $expand anidadas que se aplican a las propiedades de navegación con valor de colección. Más información: Expandir propiedades de navegación con valor de colección
Expandir propiedades de navegación de un solo valor
El siguiente ejemplo demuestra cómo recuperar registros de contacto, incluido el contacto principal y el usuario que creó los registros.
Solicitar
GET [Organization URI]/api/data/v9.2/accounts?$select=name
&$expand=primarycontactid($select=contactid,fullname),createdby($select=fullname) HTTP/1.1
Prefer: odata.maxpagesize=2
If-None-Match: null
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
Response
HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
Preference-Applied: odata.maxpagesize=2
OData-Version: 4.0
{
"@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts(name,primarycontactid(contactid,fullname),createdby(fullname))",
"value": [
{
"@odata.etag": "W/\"80649578\"",
"name": "Litware, Inc. (sample)",
"accountid": "78914942-34cb-ed11-b596-0022481d68cd",
"primarycontactid": {
"contactid": "70bf4d48-34cb-ed11-b596-0022481d68cd",
"fullname": "Susanna Stubberod (sample)"
},
"createdby": {
"fullname": "System Administrator",
"systemuserid": "4026be43-6b69-e111-8f65-78e7d1620f5e",
"ownerid": "4026be43-6b69-e111-8f65-78e7d1620f5e"
}
},
{
"@odata.etag": "W/\"80649580\"",
"name": "Adventure Works (sample)",
"accountid": "7a914942-34cb-ed11-b596-0022481d68cd",
"primarycontactid": {
"contactid": "72bf4d48-34cb-ed11-b596-0022481d68cd",
"fullname": "Nancy Anderson (sample)"
},
"createdby": {
"fullname": "System Administrator",
"systemuserid": "4026be43-6b69-e111-8f65-78e7d1620f5e",
"ownerid": "4026be43-6b69-e111-8f65-78e7d1620f5e"
}
}
],
"@odata.nextLink": "[Organization URI]/api/data/v9.2/accounts?$select=name%0A&$expand=primarycontactid($select=contactid,fullname),createdby($select=fullname)&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%253e%253caccountid%2520last%253d%2522%257b7A914942-34CB-ED11-B596-0022481D68CD%257d%2522%2520first%253d%2522%257b78914942-34CB-ED11-B596-0022481D68CD%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E"
}
Devolver referencias
En lugar de devolver datos, también puede devolver referencias (vínculos) a los registros relacionados expandiendo la propiedad de navegación de un solo valor con la opción /$ref. El siguiente ejemplo devuelve objetos JSON con una propiedad @odata.id que tiene una URL para cada contacto principal.
Solicitar
GET [Organization URI]/api/data/v9.2/accounts?$select=name
&$expand=primarycontactid/$ref HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
Response
HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
Preference-Applied: odata.maxpagesize=2
OData-Version: 4.0
{
"@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts(name,primarycontactid,primarycontactid/$ref())",
"value": [
{
"@odata.etag": "W/\"80649578\"",
"name": "Litware, Inc. (sample)",
"_primarycontactid_value": "70bf4d48-34cb-ed11-b596-0022481d68cd",
"accountid": "78914942-34cb-ed11-b596-0022481d68cd",
"primarycontactid": {
"@odata.id": "[Organization URI]/api/data/v9.2/contacts(70bf4d48-34cb-ed11-b596-0022481d68cd)"
}
},
{
"@odata.etag": "W/\"80649580\"",
"name": "Adventure Works (sample)",
"_primarycontactid_value": "72bf4d48-34cb-ed11-b596-0022481d68cd",
"accountid": "7a914942-34cb-ed11-b596-0022481d68cd",
"primarycontactid": {
"@odata.id": "[Organization URI]/api/data/v9.2/contacts(72bf4d48-34cb-ed11-b596-0022481d68cd)"
}
}
],
"@odata.nextLink": "[Organization URI]/api/data/v9.2/accounts?$select=name%0A&$expand=primarycontactid/$ref&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%253e%253caccountid%2520last%253d%2522%257b7A914942-34CB-ED11-B596-0022481D68CD%257d%2522%2520first%253d%2522%257b78914942-34CB-ED11-B596-0022481D68CD%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E"
}
Solo puede usar la opción /$ref con propiedades de navegación de un único valor. Si la usa con una propiedad de navegación con valor de colección, obtiene el error siguiente:
{
"error": {
"code": "0x80060888",
"message": "Expand with $ref is only supported on lookup type navigation property."
}
}
Expansión anidada de propiedades de navegación de un único valor
Puede expandir las propiedades de navegación de un único valor a varios niveles, anidando una opción $expand dentro de otra opción $expand.
La siguiente consulta devuelve registros de task y expande el contact relacionado, la account relacionada con el contact y finalmente el systemuser que creó el registro de account.
Solicitar
GET [Organization URI]/api/data/v9.2/tasks?$select=subject
&$expand=regardingobjectid_contact_task($select=fullname;
$expand=parentcustomerid_account($select=name;
$expand=createdby($select=fullname))) HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
Response
HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
Preference-Applied: odata.maxpagesize=2
OData-Version: 4.0
{
"@odata.context": "[Organization URI]/api/data/v9.2/$metadata#tasks(subject,regardingobjectid_contact_task(fullname,parentcustomerid_account(name,createdby(fullname))))",
"value": [
{
"@odata.etag": "W/\"80730855\"",
"subject": "Task 1 for Susanna Stubberod",
"activityid": "e9a8c72c-dbcc-ed11-b597-000d3a993550",
"regardingobjectid_contact_task": {
"fullname": "Susanna Stubberod (sample)",
"contactid": "70bf4d48-34cb-ed11-b596-0022481d68cd",
"parentcustomerid_account": {
"name": "Litware, Inc. (sample)",
"accountid": "78914942-34cb-ed11-b596-0022481d68cd",
"createdby": {
"fullname": "System Administrator",
"systemuserid": "4026be43-6b69-e111-8f65-78e7d1620f5e",
"ownerid": "4026be43-6b69-e111-8f65-78e7d1620f5e"
}
}
}
},
{
"@odata.etag": "W/\"80730861\"",
"subject": "Task 2 for Susanna Stubberod",
"activityid": "c206f534-dbcc-ed11-b597-000d3a993550",
"regardingobjectid_contact_task": {
"fullname": "Susanna Stubberod (sample)",
"contactid": "70bf4d48-34cb-ed11-b596-0022481d68cd",
"parentcustomerid_account": {
"name": "Litware, Inc. (sample)",
"accountid": "78914942-34cb-ed11-b596-0022481d68cd",
"createdby": {
"fullname": "System Administrator",
"systemuserid": "4026be43-6b69-e111-8f65-78e7d1620f5e",
"ownerid": "4026be43-6b69-e111-8f65-78e7d1620f5e"
}
}
}
}
],
"@odata.nextLink": "[Organization URI]/api/data/v9.2/tasks?$select=subject&$expand=regardingobjectid_contact_task($select=fullname;$expand=parentcustomerid_account($select=name;$expand=createdby($select=fullname)))&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%253e%253cactivityid%2520last%253d%2522%257bC206F534-DBCC-ED11-B597-000D3A993550%257d%2522%2520first%253d%2522%257bE9A8C72C-DBCC-ED11-B597-000D3A993550%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E"
}
Expandir propiedades de navegación valoradas como colección
Hay algunas diferencias importantes en la respuesta que dependen de si usa anidado $expand con una propiedad de navegación con valor de colección en cualquier parte de su consulta.
| $expand anidado | $expand único | |
|---|---|---|
| Paging | Paginación en filas expandidas. | Paginación solo en conjunto de entidades de recursos. Las direcciones URL <property name>@odata.nextLink de las filas expandidas no incluyen información de paginación. |
Se admiten $top o $orderby |
No | Sí |
$expand único en propiedades de navegación valoradas como colección
Si usa solo $expand único, no se aplica paginación a las filas expandidas. Si incluye el encabezado de solicitud Prefer: odata.maxpagesize, la paginación solo se aplica al recurso del conjunto de entidades de la consulta.
Cada propiedad de navegación expandida con valor de colección devuelve una URL <property>@odata.nextLink que no incluye información de paginación. Es una URL que lleva a la colección filtrada por la relación. Puede usar esa URL para enviar una solicitud GET por separado y devuelve las mismas filas que se devolvieron en su solicitud original. Puede aplicar paginación a esa solicitud.
Debido a que no se aplica paginación a los registros expandidos, se pueden devolver hasta 5000 registros relacionados. Puede usar las opciones $top, $filter y $orderby para controlar el número total de registros devueltos.
El siguiente ejemplo incluye la expansión única de Account_Tasks y contact_customer_accounts mientras recupera registros de cuenta. El encabezado de solicitud Prefer: odata.maxpagesize=1 garantiza que solo se devuelva un registro de cuenta con la primera página.
Solicitar
GET [Organization URI]/api/data/v9.2/accounts?$select=name,accountid
&$expand=Account_Tasks($select=subject),contact_customer_accounts($select=fullname) HTTP/1.1
Prefer: odata.maxpagesize=1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
Response
HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
Preference-Applied: odata.maxpagesize=1
OData-Version: 4.0
{
"@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts(name,accountid,Account_Tasks(subject),contact_customer_accounts(fullname))",
"value": [
{
"@odata.etag": "W/\"80649578\"",
"name": "Litware, Inc. (sample)",
"accountid": "78914942-34cb-ed11-b596-0022481d68cd",
"Account_Tasks": [
{
"@odata.etag": "W/\"80730894\"",
"subject": "Task 1 for Litware",
"_regardingobjectid_value": "78914942-34cb-ed11-b596-0022481d68cd",
"activityid": "be9f6557-e2cc-ed11-b597-000d3a993550"
},
{
"@odata.etag": "W/\"80730903\"",
"subject": "Task 2 for Litware",
"_regardingobjectid_value": "78914942-34cb-ed11-b596-0022481d68cd",
"activityid": "605dbd65-e2cc-ed11-b597-000d3a993550"
},
{
"@odata.etag": "W/\"80730909\"",
"subject": "Task 3 for Litware",
"_regardingobjectid_value": "78914942-34cb-ed11-b596-0022481d68cd",
"activityid": "a718856c-e2cc-ed11-b597-000d3a993550"
}
],
"Account_Tasks@odata.nextLink": "[Organization URI]/api/data/v9.2/accounts(78914942-34cb-ed11-b596-0022481d68cd)/Account_Tasks?$select=subject",
"contact_customer_accounts": [
{
"@odata.etag": "W/\"80648695\"",
"fullname": "Susanna Stubberod (sample)",
"_parentcustomerid_value": "78914942-34cb-ed11-b596-0022481d68cd",
"contactid": "70bf4d48-34cb-ed11-b596-0022481d68cd"
}
],
"contact_customer_accounts@odata.nextLink": "[Organization URI]/api/data/v9.2/accounts(78914942-34cb-ed11-b596-0022481d68cd)/contact_customer_accounts?$select=fullname"
}
],
"@odata.nextLink": "[Organization URI]/api/data/v9.2/accounts?$select=name,accountid&$expand=Account_Tasks($select=subject),contact_customer_accounts($select=fullname)&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%253e%253caccountid%2520last%253d%2522%257b7A914942-34CB-ED11-B596-0022481D68CD%257d%2522%2520first%253d%2522%257b78914942-34CB-ED11-B596-0022481D68CD%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E"
}
Nota
Compare esta respuesta con el siguiente ejemplo que incluye un $expand anidado.
Debe desplazarse horizontalmente por la respuesta de ejemplo para ver que solo la URL @odata.nextLink del resultado de la cuenta contiene información de paginación.
$expand anidado en propiedades de navegación valoradas como colección
Si usa un $expand anidado en cualquier parte de su consulta y ha incluido el encabezado de solicitud Prefer: odata.maxpagesize, la paginación se aplica a cada una de las colecciones expandidas.
Cada propiedad de navegación expandida con valor de colección devuelve una URL <property>@odata.nextLink que incluye información de paginación. Puede usar esa URL para enviar una solicitud GET por separado y devolverá el siguiente conjunto de registros que no se incluyeron en su solicitud original.
No puede usar las opciones $top o $orderby para limitar la cantidad total de registros devueltos con un $expand anidado. Se devuelve el siguiente error si utiliza estas opciones:
{
"error": {
"code": "0x80060888",
"message": "Only $select and $filter clause can be provided while doing $expand on many-to-one relationship or nested one-to-many relationship."
}
}
Este ejemplo se basa en el ejemplo anterior y utiliza los mismos datos. La única diferencia en la URL es la adición de este $expand anidado en una propiedad de navegación de un solo valor para devolver el usuario propietario del contacto: ;$expand=owninguser($select=fullname).
Solicitar
GET [Organization URI]/api/data/v9.2/accounts?$select=name,accountid
&$expand=Account_Tasks($select=subject),contact_customer_accounts($select=fullname;
$expand=owninguser($select=fullname)) HTTP/1.1
Prefer: odata.maxpagesize=1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
Response
HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
Preference-Applied: odata.maxpagesize=1
OData-Version: 4.0
{
"@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts(name,accountid,Account_Tasks(subject),contact_customer_accounts(fullname,owninguser(fullname)))",
"value": [
{
"@odata.etag": "W/\"80649578\"",
"name": "Litware, Inc. (sample)",
"accountid": "78914942-34cb-ed11-b596-0022481d68cd",
"Account_Tasks": [
{
"subject": "Task 1 for Litware",
"activityid": "be9f6557-e2cc-ed11-b597-000d3a993550"
}
],
"Account_Tasks@odata.nextLink": "[Organization URI]/api/data/v9.2/accounts(78914942-34cb-ed11-b596-0022481d68cd)/Account_Tasks?$select=subject,description&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%2520countOfRecords%253d%25221%2522%253e%253cactivityid%2520last%253d%2522%257bbe9f6557-e2cc-ed11-b597-000d3a993550%257d%2522%2520first%253d%2522%257bbe9f6557-e2cc-ed11-b597-000d3a993550%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E",
"contact_customer_accounts": [
{
"fullname": "Susanna Stubberod (sample)",
"contactid": "70bf4d48-34cb-ed11-b596-0022481d68cd",
"owninguser": {
"fullname": "System Administrator",
"systemuserid": "4026be43-6b69-e111-8f65-78e7d1620f5e",
"ownerid": "4026be43-6b69-e111-8f65-78e7d1620f5e"
}
}
],
"contact_customer_accounts@odata.nextLink": "[Organization URI]/api/data/v9.2/accounts(78914942-34cb-ed11-b596-0022481d68cd)/contact_customer_accounts?$select=fullname&$expand=owninguser($select=fullname)&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%2520countOfRecords%253d%25221%2522%253e%253ccontactid%2520last%253d%2522%257b70bf4d48-34cb-ed11-b596-0022481d68cd%257d%2522%2520first%253d%2522%257b70bf4d48-34cb-ed11-b596-0022481d68cd%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E"
}
],
"@odata.nextLink": "[Organization URI]/api/data/v9.2/accounts?$select=name,accountid&$expand=Account_Tasks($select=subject,description),contact_customer_accounts($select=fullname;$expand=owninguser($select=fullname))&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%2520countOfRecords%253d%25221%2522%253e%253caccountid%2520last%253d%2522%257b78914942-34cb-ed11-b596-0022481d68cd%257d%2522%2520first%253d%2522%257b78914942-34cb-ed11-b596-0022481d68cd%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E"
}
Nota
Compare esta respuesta con el ejemplo anterior que no usa $expand anidado.
En esta respuesta, el encabezado de solicitud Prefer: odata.maxpagesize=1 se aplica a lo sregistros task devueltos con Account_Tasks. Solo se devuelve una tarea en lugar de tres. La URL Account_Tasks@odata.nextLink devolverá las siguientes dos tareas.
Debe desplazar la respuesta de ejemplo horizontalmente para ver que las URL Account_Tasks@odata.nextLink, contact_customer_accounts@odata.nextLink y @odata.nextLink contienen información de paginación.
Consulte también
Consultar datos utilizando la API web
Recuperar una fila de tabla usando la API web
Ejemplo de datos de consulta de API web (C#)
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