Recuperar una fila de tabla usando la API web

Artigo
06/21/2022
5 minutos de lectura

Nota

¿No está seguro de entidad frente a tabla? Vea Desarrolladores: comprender la terminología en Microsoft Dataverse.

Use una solicitud GET para recuperar datos de una tabla especificados como el recurso con un identificador único. Al recuperar una fila de tabla (registro de entidad), también puede solicitar propiedades específicas y expandir las propiedades de navegación para devolver propiedades de tablas relacionadas.

Nota

Para obtener información sobre cómo recuperar definiciones de tablas, consulte Consultar definiciones de tablas mediante la API web.

Ejemplo de recuperación básica

Este ejemplo devuelve datos para un registro de entidad de cuenta con el valor de clave primaria igual a 00000000-0000-0000-0000-000000000001.

GET [Organization URI]/api/data/v9.0/accounts(00000000-0000-0000-0000-000000000001)

Para recuperar más de un registro de entidad a la vez, consulte Ejemplo de consulta básica en el tema Consultar datos con la API web.

Precaución

El ejemplo anterior devolverá todas las propiedades del registro de la cuenta, lo que no es una práctica recomendada de rendimiento para recuperar datos. Este ejemplo fue solo para ilustrar cómo puede hacer una recuperación básica de un registro de entidad en Microsoft Dataverse. Puesto que todas las propiedades se devolvieron, no hemos incluido la información de respuesta para la solicitud en este ejemplo.

Como práctica recomendada para mejorar el rendimiento, debe usar siempre la opción de consulta del sistema $select para limitar las propiedades devueltas al recuperar datos. Consulte la siguiente sección, Recuperar propiedades específicas, para obtener información sobre este.

Recuperar propiedades específicas

Use la opción de consulta del sistema $select para limitar las propiedades devueltas incluyendo una lista separada por comas de nombres de propiedad. Esta es una práctica recomendada importante de rendimiento. Si las propiedades no se especifican utilizando $select, todas las propiedades se devolverán.

El ejemplo siguiente recupera propiedades name y revenue para la entidad de cuenta con el valor de clave principal igual a 00000000-0000-0000-0000-000000000001

Solicitud

GET [Organization URI]/api/data/v9.0/accounts(00000000-0000-0000-0000-000000000001)?$select=name,revenue HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
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.0/$metadata#accounts(name,revenue)/$entity",  
"@odata.etag": "W/\"502186\"",  
"name": "A. Datum Corporation (sample)",  
"revenue": 10000,  
"accountid": "00000000-0000-0000-0000-000000000001",  
"_transactioncurrencyid_value":"b2a6b689-9a39-e611-80d2-00155db44581"  
}

Al solicitar determinados tipos de propiedades puede esperar que las propiedades de solo lectura adicionales se devuelvan automáticamente.

Si solicita un valor monetario, se devolverá la propiedad de búsqueda _transactioncurrencyid_value. Esta propiedad solo contiene el valor GUID de la divisa de transacción para que pueda usar este valor para recuperar información acerca de la divisa con la transactioncurrency EntityType /. De forma alternativa, al solicitar anotaciones también puede obtener más datos en la misma solicitud. Más información:Recuperar datos sobre propiedades de búsqueda

Si solicita una propiedad que forma parte de un atributo compuesto para una dirección, obtendrá además la propiedad compuesta. Por ejemplo, si la consulta solicita la propiedad address1_line1 para un contacto, se devolverá además la propiedad address1_composite.

Recuperar con una clave alternativa

Si una entidad tiene una clave alternativa definida, también puede usar la clave alternativa para recuperar la entidad en lugar del identificador único para la entidad. Por ejemplo, si la entidad Contact tiene una definición de clave alternativa que incluye las propiedades firstname y emailaddress1, puede recuperar el contacto mediante el uso de una consulta con los datos proporcionados para esas claves como se indica a continuación.

GET [Organization URI]/api/data/v9.0/contacts(firstname='Joe',emailaddress1='abc@example.com')

Si la definición clave alternativa contiene un campo de tipo de búsqueda (por ejemplo, la propiedad primarycontactid para la entidad account), puede recuperar account utilizando las propiedades de búsqueda como se muestra aquí.

GET [Organization URI]/api/data/v9.0/accounts(_primarycontactid_value=00000000-0000-0000-0000-000000000001)

En cualquier momento que necesite identificar de forma exclusiva una entidad para recuperar, actualizar o eliminar, puede usar las claves alternativas configuradas para la entidad. De forma predeterminada, no hay claves alternativas configuradas para entidades. Las claves alternativas sólo estarán disponibles si la organización o una solución las agrega.

Recuperar documentos en particiones de almacenamiento

Si está recuperando datos de entidad almacenados en particiones, asegúrese de especificar la clave de partición cuando recupere esos datos.

Más información: Obtener acceso a los datos de tabla más rápido utilizando particiones de almacenamiento

Recuperar un solo valor de propiedad

Cuando solo necesita recuperar el valor de una sola propiedad de una entidad, se puede anexar el nombre de la propiedad a la URI para una entidad para devolver solo el valor de esa propiedad. Esto es una recomendación de rendimiento porque necesitan devolverse menos datos en la respuesta.

Este ejemplo sólo devuelve el valor de la propiedad name para una entidad account.

Solicitud

GET [Organization URI]/api/data/v9.0/accounts(00000000-0000-0000-0000-000000000001)/name 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
OData-Version: 4.0

{
"@odata.context":"[Organization URI]/api/data/v9.0/$metadata#accounts(00000000-0000-0000-0000-000000000001)/name",
"value":"Adventure Works (sample)"
}

De la misma forma que puede recuperar valores de propiedad individuales, también puede obtener acceso a los valores de propiedades de navegación (campos de búsqueda) anexando el nombre de la propiedad de navegación a la URI que hace referencia a una entidad individual.

El siguiente ejemplo devuelve el fullname del contact primario de una account usando la propiedad de navegación de un solo valor primarycontactid.

Solicitud

GET [Organization URI]/api/data/v9.0/accounts(00000000-0000-0000-0000-000000000001)/primarycontactid?$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
OData-Version: 4.0

{  
"@odata.context": "[Organization URI]/api/data/v9.0/$metadata#contacts(fullname)/$entity",  
"@odata.etag": "W/\"500128\"",  
"fullname": "Rene Valdes (sample)",  
"contactid": "ff390c24-9c72-e511-80d4-00155d2a68d1"  
}

Para propiedades de navegación valoradas como colección tiene la opción de solicitar devolver solo referencias a las entidades relacionadas o simplemente un recuento de entidades relacionadas.

El siguiente ejemplo solo devolverá referencias a las tareas relacionadas con una cuenta específica agregando /$ref a la solicitud.

Solicitud

GET [Organization URI]/api/data/v9.0/accounts(00000000-0000-0000-0000-000000000001)/AccountTasks/$ref 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.0/$metadata#Collection($ref)",
    "value":
  [
    { "@odata.id": "[Organization URI]/api/data/v9.0/tasks(6b5941dd-d175-e511-80d4-00155d2a68d1)" },
    { "@odata.id": "[Organization URI]/api/data/v9.0/tasks(fcbb60ed-d175-e511-80d4-00155d2a68d1)" }
  ]
}

El siguiente ejemplo devuelve el número de tareas relacionadas con una cuenta específica mediante la propiedad de navegación valorada como colección Account_Tasks con /$count anexado.

Solicitud

GET [Organization URI]/api/data/v9.0/accounts(00000000-0000-0000-0000-000000000001)/Account_Tasks/$count HTTP/1.1  
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

Respuesta

ï»¿2

Nota

El valor devuelto incluye caracteres de marca de orden de butes (BOM) UTF-8 (ï»¿) que representan que es un documento UTF-8.

Use la opción de consulta del sistema $expand para controlar qué datos de entidades relacionadas se devuelven. Hay dos tipos de propiedades de navegación:

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 otra entidad.
Las propiedades de navegación valoradas como colección corresponden a relaciones de uno a varios o de varios a varios.

Si incluye simplemente el nombre de la propiedad de navegación, recibirá todas las propiedades de registros relacionados. Puede limitar las propiedades devueltas para registros relacionados con la opción de la consulta del sistema $select entre paréntesis después del nombre de propiedad de navegación. Use esta opción para las propiedades de navegación de un solo valor y valoradas como colección.

Nota

Para recuperar entidades relacionadas para conjuntos de entidades, consulte Recuperar registros de tablas relacionados con una consulta.

Recuperar entidades relacionadas para una instancia de entidad expandiendo las propiedades de navegación de un solo valor
El ejemplo siguiente muestra cómo recuperar el contacto para una entidad de cuenta. Para el registro de contacto relacionado, solo recuperamos contactid y fullname.

Solicitud

GET [Organization URI]/api/data/v9.0/accounts(00000000-0000-0000-0000-000000000001)?$select=name&$expand=primarycontactid($select=contactid,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  
OData-Version: 4.0  

{  
  "@odata.context":"[Organization URI]/api/data/v9.0/$metadata#accounts(name,primarycontactid,primarycontactid(contactid,fullname))/$entity",  
  "@odata.etag":"W/\"550616\"",  
  "name":"Adventure Works (sample)",  
  "accountid":"00000000-0000-0000-0000-000000000001",  
  "primarycontactid":
  {  
  "@odata.etag":"W/\"550626\"",  
  "contactid":"c59648c3-68f7-e511-80d3-00155db53318",  
  "fullname":"Nancy Anderson (sample)"  
  }
}

En lugar de devolver entidades relacionadas para registros de entidades, también puede devolver referencias (vínculos) a las entidades relacionadas expandiendo la propiedad de navegación de un solo valor con la opción $ref. El siguiente ejemplo devuelve vínculos al registro de contacto para la entidad de cuenta.

Solicitud

GET [Organization URI]/api/data/v9.0/accounts(00000000-0000-0000-0000-000000000001)?$select=name&$expand=primarycontactid/$ref 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.0/$metadata#accounts(name,primarycontactid)/$entity",  
  "@odata.etag":"W/\"550616\"",  
  "name":"Adventure Works (sample)",  
  "accountid":"00000000-0000-0000-0000-000000000001",  
  "_primarycontactid_value":"c59648c3-68f7-e511-80d3-00155db53318",  
  "primarycontactid": { "@odata.id":"[Organization URI]/api/data/v9.0/contacts(c59648c3-68f7-e511-80d3-00155db53318)" }
}

Recuperar entidades relacionadas para una instancia de entidad expandiendo las propiedades de navegación valorada como colección:
El ejemplo siguiente muestra cómo recuperar todas las tareas asignadas a un registro de cuenta.

Solicitar

GET [Organization URI]/api/data/v9.0/accounts(915e89f5-29fc-e511-80d2-00155db07c77)?$select=name
&$expand=Account_Tasks($select=subject,scheduledstart)
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

Response

HTTP/1.1 200 OK  
Content-Type: application/json; odata.metadata=minimal  
OData-Version: 4.0

{
  "@odata.context": "[Organization URI]/api/data/v9.0/$metadata#accounts(name,Account_Tasks,Account_Tasks(subject,scheduledstart))/$entity",
  "@odata.etag": "W/\"514069\"",
  "name": "Sample Child Account 1",
  "accountid": "915e89f5-29fc-e511-80d2-00155db07c77",
  "Account_Tasks":
   [
    {
      "@odata.etag": "W/\"514085\"",
      "subject": "Sample Task 1",
      "scheduledstart": "2016-04-11T15:00:00Z",
      "activityid": "a983a612-3ffc-e511-80d2-00155db07c77"
    },
    {
      "@odata.etag": "W/\"514082\"",
      "subject": "Sample Task 2",
      "scheduledstart": "2016-04-13T15:00:00Z",
      "activityid": "7bcc572f-3ffc-e511-80d2-00155db07c77"
    }
   ]
}

Recupere entidades relacionadas para una instancia de entidad expandiendo las propiedades de navegación de un solo valor y valoradas como colección: El siguiente ejemplo demuestra cómo puede expandir entidades relacionadas para una instancia de entidad utilizando propiedades de navegación de un solo valor y valoradas como colección.

Solicitud

GET [Organization URI]/api/data/v9.0/accounts(99390c24-9c72-e511-80d4-00155d2a68d1)?$select=accountid
&$expand=parentaccountid($select%20=%20createdon,%20name),Account_Tasks($select%20=%20subject,%20scheduledstart) 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.0/$metadata#accounts(accountid,parentaccountid,Account_Tasks,parentaccountid(createdon,name),Account_Tasks(subject,scheduledstart))/$entity",
"@odata.etag": "W/\"514069\"",
"accountid": "915e89f5-29fc-e511-80d2-00155db07c77",
"parentaccountid": 
    {
      "@odata.etag": "W/\"514074\"",
      "createdon": "2016-04-06T00:29:04Z",
      "name": "Adventure Works (sample)",
      "accountid": "3adbf27c-8efb-e511-80d2-00155db07c77"
    },
  "Account_Tasks":
    [
      {
        "@odata.etag": "W/\"514085\"",
        "subject": "Sample Task 1",
        "scheduledstart": "2016-04-11T15:00:00Z",
        "activityid": "a983a612-3ffc-e511-80d2-00155db07c77"
      },
      {
        "@odata.etag": "W/\"514082\"",
        "subject": "Sample Task 2",
        "scheduledstart": "2016-04-13T15:00:00Z",
        "activityid": "7bcc572f-3ffc-e511-80d2-00155db07c77"
      }
    ]
}

Nota

No puede usar los segmentos de ruta /$ref o /$count para devolver solo el URI para la entidad relacionada o el número de entidades relacionadas.

Opciones para aplicar a tablas expandidas

Puede aplicar algunas opciones de consulta del sistema a las entidades devueltas para una propiedad de navegación valorada como colección. Use una lista separada por punto y coma de opciones de consulta del sistema entre paréntesis después del nombre de la propiedad de navegación valorada como colección. Puede utilizar $select, $filter, $orderby, $top y $expand.

El siguiente ejemplo filtra los resultados de las entidades de tareas relacionadas con una account a las que tienen un sujeto que termina con “1”.

?$expand=Account_Tasks($filter=endswith(subject,'1');$select=subject)

El siguiente ejemplo especifica que las tareas relacionadas deben devolverse en orden ascendente basándose en la propiedad createdon.

?$expand=Account_Tasks($orderby=createdon asc;$select=subject,createdon)

El siguiente ejemplo devuelve solamente la primera tarea relacionada.

?$expand=Account_Tasks($top=1;$select=subject)

El siguiente ejemplo aplica opciones $expand anidadas para devolver detalles sobre el systemuser que modificó por última vez la cuenta y el nombre del businessunit al que pertenece ese usuario.

?$select=name&$expand=modifiedby($select=fullname;$expand=businessunitid($select=name))

Nota

Las opciones $expand anidadas solo se pueden aplicar a las propiedades de navegación de un único valor.
Cada solicitud puede incluir un máximo de 15 opciones $expand. No hay límite en la profundidad de las opciones $expand anidadas, pero el límite de 15 opciones $expand en total también se aplica a estas.
Este es un subconjunto de las opciones de consulta del sistema descritas en la sección 11.2.4.2 .1 de 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.

Más información sobre el uso anidado de la opción $expand: Expansión multinivel de propiedades de navegación de un único valor

Detectar si una tabla ha cambiado desde que se recuperó

Como recomendación de rendimiento solo debe solicitar los datos que necesite. Si ha recuperado anteriormente un registro de entidad, puede usar la ETag asociada a un registro anteriormente recuperado para realizar recuperaciones condicionales en dicho registro. Más información: Recuperaciones condicionales.

Recuperar valores con formato

La solicitud de valores con formato para recuperaciones de registros individuales se hace la misma forma que cuando se consultan conjuntos de entidades. Más información:Incluir valores con formato.

Vea también

Ejemplo de operaciones básicas de la API web (C#)
Ejemplo de operaciones básicas de la API web (JavaScript del lado del cliente)
Realizar operaciones mediante la API web
Componer solicitudes HTTP y administrar errores
Consultar datos utilizando la API web
Crear una tabla usando la API web
Actualizar y eliminar tablas mediante la API web
Asociar y anular la asociación de tablas mediante la API web
Usar funciones de la API web
Usar acciones de la API web
Ejecute las operaciones por lotes mediante API web
Suplantar a otro usuario utilizando la API web
Realizar operaciones condicionales mediante la API web

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).

Recuperar una fila de tabla usando la API web

Ejemplo de recuperación básica

Recuperar propiedades específicas

Recuperar con una clave alternativa

Recuperar documentos en particiones de almacenamiento

Recuperar un solo valor de propiedad

Recuperar valores de propiedad de navegación

Opciones para aplicar a tablas expandidas

Detectar si una tabla ha cambiado desde que se recuperó

Recuperar valores con formato

Vea también

Comentarios

Recuperar una fila de tabla usando la API web

Ejemplo de recuperación básica

Recuperar propiedades específicas

Recuperar con una clave alternativa

Recuperar documentos en particiones de almacenamiento

Recuperar un solo valor de propiedad

Recuperar valores de propiedad de navegación

Recuperar tablas relacionadas para una tabla ampliando las propiedades de navegación

Opciones para aplicar a tablas expandidas

Detectar si una tabla ha cambiado desde que se recuperó

Recuperar valores con formato

Vea también

Comentarios