Compartir vía

Recuperar una fila de tabla usando la API web

  • Artículo

Use una solicitud GET para recuperar datos de un registro especificado 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 desde registros relacionados en diferentes tablas.

Nota

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

Recuperación básica

El ejemplo siguiente 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.2/accounts(00000000-0000-0000-0000-000000000001)

Este ejemplo devuelve todas las propiedades del registro de la cuenta, lo que no es una práctica recomendada de rendimiento. Debe usar siempre la opción de consulta del sistema $select para limitar las propiedades devueltas al recuperar datos. Esto es especialmente importante cuando se recuperan varias filas de datos. Más información: Consultar datos mediante la API web.

Recuperar propiedades específicas

Para limitar las propiedades devueltas al recuperar dtos con la solicitud GET, use la opción de consulta del sistema $select con una lista separada por comas de nombres de propiedad. Solicitar solo las propiedades que necesita es una práctica recomendada importante de rendimiento. Si no especifica propiedades para devolver, se devolverán todas las propiedades.

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.2/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.2/$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 se devuelvan automáticamente más propiedades de solo lectura.

Si solicita un valor monetario, se devuelve la _transactioncurrencyid_value propiedad de búsqueda . 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 transactioncurrency EntityType. De forma alternativa, al solicitar anotaciones puede obtener más datos en la misma solicitud.

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

Recuperar el registro con una clave alternativa

Si una entidad tiene una clave alternativa definida, también puede usar la clave alternativa para recuperar, actualizra o eliminar la entidad. De forma predeterminada, no hay claves alternativas configuradas para entidades. Las claves alternativas sólo están disponibles si su organización o una solución las agrega.

Actualmente no se admiten los valores de clave alternativos con los siguientes caracteres: /,<,>,*,%,&,:,\\,?,+.

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:

GET [Organization URI]/api/data/v9.2/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 en el ejemplo siguiente:

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

Recuperar documentos en particiones de almacenamiento

Cuando recupera un registro en una tabla elástica que está almacenado en una partición, asegúrese de especificar la clave de partición.

Recuperar un solo valor de propiedad

Cuando solo necesita recuperar el valor de una sola propiedad, puede agregar el nombre de la propiedad al URI de la entidad. Reducir la cantidad de datos devueltos es una práctica recomendada de rendimiento.

Este ejemplo siguiente devuelve solo el valor de la propiedad name para una entidad account:

Solicitud:

GET [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001)/name 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(00000000-0000-0000-0000-000000000001)/name",
"value":"Adventure Works (sample)"
}

Recuperar el valor sin procesar de una propiedad

Para recuperar el valor bruto de una propiedad primitiva, en lugar de JSON, agregue /$value a la URL; Por ejemplo:

Solicitud:

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

Respuesta:

HTTP/1.1 200 OK
Content-Type: text/plain
OData-Version: 4.0

Adventure Works (sample)

Usar el valor bruto no es común, a menos que esté trabajando con datos de archivos o imágenes. Más información: Descargue un archivo en una sola solicitud utilizando la API web.

Recuperar valores de propiedad de navegación

Puede obtener acceso a los valores de propiedades de navegación o 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.2/accounts(00000000-0000-0000-0000-000000000001)/primarycontactid?$select=fullname 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#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, puede solicitar la devolución solo de referencias a las entidades relacionadas o simplemente un recuento de entidades relacionadas.

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

Solicitud:

GET [Organization URI]/api/data/v9.2/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.2/$metadata#Collection($ref)",
    "value":
  [
    { "@odata.id": "[Organization URI]/api/data/v9.2/tasks(6b5941dd-d175-e511-80d4-00155d2a68d1)" },
    { "@odata.id": "[Organization URI]/api/data/v9.2/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.2/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 indica que es un documento UTF-8.

Use la opción de consulta del sistema $expand para controlar qué datos de entidades relacionadas se devuelven. Más información: Unir tablas

Detectar si un registro 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

Solicite valores formateados para recuperaciones de registros individuales de la misma manera que consulta conjuntos de entidades.

Consulte también

Realizar operaciones mediante la API web
Componer solicitudes HTTP y administrar errores
Consultar datos 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).