Partekatu honen bidez:

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 práctica recomendada para el rendimiento. Use siempre la $select opción de consulta del sistema para limitar las propiedades devueltas al recuperar datos. Esta práctica es especialmente importante cuando se recuperan varias filas de datos. Para obtener más información, consulte Consulta de 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. Solicite solo las propiedades que necesita para mejorar el rendimiento. Si no especifica propiedades que se van a devolver, la solicitud devuelve todas las propiedades.

En el ejemplo siguiente se recuperan las name y revenue propiedades de la entidad de la 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, verá que se devuelven automáticamente más propiedades de solo lectura.

Si solicita un valor monetario, se devolverá la _transactioncurrencyid_valuepropiedad de búsqueda. Esta propiedad contiene únicamente el valor GUID de la moneda de la transacción, por lo que se puede utilizar para recuperar información sobre la moneda mediante el 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 registros 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, anexe el nombre de la propiedad al URI de 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 común a menos que esté trabajando con datos de archivo o imagen. Para obtener más información, consulte Descarga de 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.

En el ejemplo siguiente se devuelve el fullname del contact principal de un account mediante la propiedad de navegación de valor único 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 devuelven 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)" }
  ]
}

En el ejemplo siguiente se devuelve el número de tareas relacionadas con una cuenta específica mediante la Account_Tasks propiedad de navegación con valores de colección 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 este valor es un documento UTF-8.

Use la opción de consulta del $expand sistema para controlar qué datos de las entidades relacionadas se devuelven. Para obtener más información, vea Combinar tablas.

Detectar si un registro ha cambiado desde que se recuperó

Como procedimiento recomendado de rendimiento, solicite solo los datos que necesita. Si recuperó previamente un registro de entidad, use el ETag asociado a dicho registro para realizar recuperaciones condicionales. Para obtener más información, consulte 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