Compartir a través de

Recuperación de una fila de tabla mediante la API web

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

Nota:

Para obtener información sobre cómo recuperar definiciones de tabla, consulte Query table definitions using the Web API (Consultar definiciones de tabla mediante la API web).

Recuperación básica

En el ejemplo siguiente se devuelven datos de un registro de entidad de cuenta con el valor de clave principal igual a 00000000-0000-0000-00000000000001:

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

En este ejemplo se devuelven todas las propiedades del registro de cuenta, lo cual no es una mejor práctica de rendimiento. Siempre debe usar la $select opción de consulta del sistema para limitar las propiedades devueltas al recuperar datos. Esto es especialmente importante al recuperar varias filas de datos. Para obtener más información, consulte Consultar datos mediante la API web.

Recuperar propiedades específicas

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

En el ejemplo siguiente se recuperan name y revenue propiedades de 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 devolverá la _transactioncurrencyid_valuepropiedad 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. Como alternativa, puede obtener más datos en la misma solicitud solicitando anotaciones.

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

Recuperación del registro mediante una clave alternativa

Si una entidad tiene definida una clave alternativa, puede usarla en lugar del identificador único para recuperar, actualizar o eliminar la entidad. De forma predeterminada, no hay claves alternativas configuradas para las entidades. Las claves alternativas solo están disponibles si su organización o una solución las agrega.

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

Por ejemplo, si la Contact entidad tiene una definición de clave alternativa que incluye las firstname propiedades y emailaddress1 , puede recuperar el contacto mediante una consulta con datos proporcionados para esas claves:

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

Si la definición de clave alternativa contiene un campo de tipo de búsqueda (por ejemplo, la primarycontactid propiedad de la account entidad), puede recuperar el account utilizando las propiedades Lookup, como en el ejemplo siguiente:

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

Recuperación de documentos en particiones de almacenamiento

Al recuperar un registro en una tabla elástica que se almacena en una partición, asegúrese de especificar la clave de partición.

Recuperación de un único valor de propiedad

Cuando solo necesite recuperar el valor de una sola propiedad, puede anexar el nombre de la propiedad al URI de la entidad. Reducir la cantidad de datos devueltos es un procedimiento recomendado de rendimiento.

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

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 sin procesar de una propiedad primitiva, en lugar de JSON, anexe /$value a la dirección 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)

El uso del valor sin procesar no es habitual, a menos que esté trabajando con datos de archivo o imagen. Más información: Descargue un archivo en una sola solicitud mediante la API web.

Recuperar valores de propiedad de navegación

Puede tener acceso a los valores de las propiedades de navegación o a los campos de búsqueda anexando el nombre de la propiedad de navegación al URI de 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"  
}

En el caso de las propiedades de navegación con valores de colección, puede solicitar que devuelva solo referencias a las entidades relacionadas o simplemente un recuento de las entidades relacionadas.

En el ejemplo siguiente se devolverán referencias a 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 los caracteres de marca de orden de bytes (BOM) UTF-8 (), que indica que se trata de un documento UTF-8.

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

Detectar si un registro ha cambiado desde que se recuperó

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

Recuperar valores formateados

Solicite valores con formato para las recuperaciones de registros individuales de la misma manera que se consultan los conjuntos de entidades.

Consulte también

Realización de operaciones mediante la API web
Redacción de solicitudes HTTP y control de errores
Consultar datos utilizando la API web

  • Last updated on