Partekatu honen bidez:

Selección de columnas mediante OData

Importante

Al consultar los datos, limite la cantidad de datos devueltos para optimizar el rendimiento. Seleccione solo las columnas con datos que necesite.

Al seleccionar columnas mediante OData en consultas de API web de Dataverse, use la $selectopción de consulta para elegir qué columnas se van a devolver. En OData, cada columna se representa como una propiedad . Si no incluye una $select opción de consulta, la consulta devuelve todas las propiedades, lo que puede reducir el rendimiento.

En el ejemplo siguiente se solicitan las propiedades name y revenue de la primera fila del recurso accounts EntitySet.

Solicitud:

GET [Organization URI]/api/data/v9.2/accounts?$select=name,revenue&$top=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(name,revenue)",
    "value": [
        {
            "@odata.etag": "W/\"81052965\"",
            "name": "Litware, Inc. (sample)",
            "revenue": 20000.0000,
            "_transactioncurrencyid_value": "228f42f8-e646-e111-8eb7-78e7d162ced1",
            "accountid": "4624eff7-53d3-ed11-a7c7-000d3a993550"
        }
    ]
}

La propiedad de clave principal siempre se devuelve, por lo que no es necesario incluirla en $select. En este ejemplo, accountid es la clave principal.

Es posible que vea otros valores de propiedad incluidos en la respuesta. En este caso, la _transactioncurrencyid_valuepropiedad de búsqueda para la referencia de entidad/tabla de divisas (TransactionCurrency) relacionada se incluye porque revenue es una propiedad de moneda.

¿Qué propiedades están disponibles?

Puede encontrar todas las propiedades disponibles para una entidad en el documento de servicio de $metadata. Para obtener más información, consulte Propiedades de api web.

Sugerencia

Para detectar rápidamente qué propiedades están disponibles, envíe una solicitud mediante la $top opción de consulta con un valor de 1 sin usar $select. Por ejemplo, GET [Organization URI]/api/data/v9.2/accounts?$top=1.

Web API Entity Type Reference Describe los tipos de entidad incluidos con Dataverse.

Valores con formato

El servidor genera valores con formato como valores de cadena que puede usar en la aplicación. Los valores con formato incluyen:

  • Las etiquetas localizadas para las columnas elección, opciones, sí/no, estado y razón para el estado
  • El valor de nombre principal para las propiedades de búsqueda y propietario
  • Valores monetarios con símbolos de moneda
  • Valores de fecha formateados según la zona horaria del usuario

Para incluir valores con formato en los resultados, use el encabezado de solicitud Prefer para enviar la preferencia odata.include-annotations.

Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

Los valores formateados son una de diversas anotaciones que puede solicitar. Use Prefer: odata.include-annotations="*" para incluir todas las anotaciones. Para obtener más información, consulte Anotaciones de solicitud.

El valor con formato se devuelve con el registro mediante una anotación que sigue a esta convención:

<property name>@OData.Community.Display.V1.FormattedValue

Por ejemplo:

Solicitud:

GET [Organization URI]/api/data/v9.2/accounts?$select=name,revenue,_primarycontactid_value,customertypecode,modifiedon
&$top=1
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0
Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

En la tabla siguiente se describen los valores y los valores con formato que se devuelven para las propiedades solicitadas.

Propiedad Importancia Valor con formato
name Litware, Inc. (sample) Ninguno
revenue 20000.0000 $20,000.00
_primarycontactid_value 70bf4d48-34cb-ed11-b596-0022481d68cd Susanna Stubberod (sample)
customertypecode 1 Competitor
modifiedon 2023-04-07T21:59:01Z 4/7/2023 2:59 PM
_transactioncurrencyid_value 228f42f8-e646-e111-8eb7-78e7d162ced1 US Dollar
accountid 78914942-34cb-ed11-b596-0022481d68cd Ninguno

Respuesta:

HTTP/1.1 200 OK  
Content-Type: application/json; odata.metadata=minimal  
OData-Version: 4.0
Preference-Applied: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts(name,revenue)",
    "value": [
{
            "@odata.etag": "W/\"81359849\"",
            "name": "Litware, Inc. (sample)",
            "revenue@OData.Community.Display.V1.FormattedValue": "$20,000.00",
            "revenue": 20000.0000,
            "_primarycontactid_value@OData.Community.Display.V1.FormattedValue": "Susanna Stubberod (sample)",
            "_primarycontactid_value": "70bf4d48-34cb-ed11-b596-0022481d68cd",
            "customertypecode@OData.Community.Display.V1.FormattedValue": "Competitor",
            "customertypecode": 1,
            "modifiedon@OData.Community.Display.V1.FormattedValue": "4/7/2023 2:59 PM",
            "modifiedon": "2023-04-07T21:59:01Z",
            "_transactioncurrencyid_value@OData.Community.Display.V1.FormattedValue": "US Dollar",
            "_transactioncurrencyid_value": "228f42f8-e646-e111-8eb7-78e7d162ced1",
            "accountid": "78914942-34cb-ed11-b596-0022481d68cd"
        }
    ]
}

Búsqueda de datos de propiedades

Cuando una propiedad de búsqueda representa una relación polimórfica (o de varias tablas), debe solicitar anotaciones específicas para determinar qué tabla contiene los datos relacionados.

Por ejemplo, muchas tablas tienen registros que poseen usuarios o equipos. El sistema almacena los datos de propiedad en una columna de búsqueda denominada ownerid. Esta columna es una propiedad de navegación con un solo valor en OData. Puede usar $expand para crear una combinación para obtener este valor, pero no puede usar $select. Sin embargo, puede usar $select para obtener la propiedad de búsqueda correspondiente _ownerid_value .

Cuando incluyes la propiedad de búsqueda _ownerid_value con tu $select, devuelve un valor GUID. Este valor no indica si el propietario del registro es un usuario o un equipo. Debe solicitar anotaciones para obtener estos datos.

Para incluir estas anotaciones en los resultados, use el encabezado de solicitud de preferencia para enviar la preferencia odata.include-annotations con esta configuración.

Prefer: odata.include-annotations="Microsoft.Dynamics.CRM.associatednavigationproperty,Microsoft.Dynamics.CRM.lookuplogicalname"

Sugerencia

O bien, use Prefer: odata.include-annotations="*" para incluir todas las anotaciones. Para obtener más información, consulte Anotaciones de solicitud.

Solicitud:

GET [Organization URI]/api/data/v9.2/accounts?$select=name,_ownerid_value&$top=2
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0
Prefer: odata.include-annotations="Microsoft.Dynamics.CRM.associatednavigationproperty,Microsoft.Dynamics.CRM.lookuplogicalname"

La siguiente respuesta devuelve dos registros de cuenta diferentes. La _ownerid_value@Microsoft.Dynamics.CRM.lookuplogicalname anotación le indica que team posee la primera y posee systemuser la segunda.

Respuesta:

HTTP/1.1 200 OK  
Content-Type: application/json; odata.metadata=minimal  
OData-Version: 4.0
Preference-Applied: odata.include-annotations="Microsoft.Dynamics.CRM.associatednavigationproperty,Microsoft.Dynamics.CRM.lookuplogicalname"

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts(name,_ownerid_value)",
    "value": [
        {
            "@odata.etag": "W/\"81550512\"",
            "name": "Adventure Works (sample)",
            "_ownerid_value@Microsoft.Dynamics.CRM.associatednavigationproperty": "ownerid",
            "_ownerid_value@Microsoft.Dynamics.CRM.lookuplogicalname": "team",
            "_ownerid_value": "39e0dbe4-131b-e111-ba7e-78e7d1620f5e",
            "accountid": "1adef0b8-54d3-ed11-a7c7-000d3a993550"
        },
        {
            "@odata.etag": "W/\"81359849\"",
            "name": "Litware, Inc. (sample)",
            "_ownerid_value@Microsoft.Dynamics.CRM.associatednavigationproperty": "ownerid",
            "_ownerid_value@Microsoft.Dynamics.CRM.lookuplogicalname": "systemuser",
            "_ownerid_value": "4026be43-6b69-e111-8f65-78e7d1620f5e",
            "accountid": "78914942-34cb-ed11-b596-0022481d68cd"
        }
    ]
}
  • <lookup property name>@Microsoft.Dynamics.CRM.lookuplogicalname es el nombre lógico de la tabla relacionada.
  • <lookup property name>@Microsoft.Dynamics.CRM.associatednavigationproperty es el nombre de la propiedad de navegación correspondiente de valor único. Puede utilizar este valor con $expand en otra solicitud para obtener más datos del registro relacionado.

Alias de columna

Para la API web, use fetchxml para especificar alias personalizados para las columnas.

Actualmente, no se pueden especificar alias de columna mediante la API web de Dataverse con OData. OData 4.0 no incluye la opción de consulta del sistema $compute introducida en OData 4.01 necesaria para proporcionar esta funcionalidad.

Pasos siguientes

Obtenga información sobre cómo combinar tablas.

Unir tablas

  • Last updated on