Selecionar colunas usando o OData

Ao selecionar colunas usando o OData em consultas da API Web do Dataverse, use a $selectopção de consulta para escolher quais colunas retornar. No OData, cada coluna é representada como uma propriedade. Se você não incluir uma $select opção de consulta, a consulta retornará todas as propriedades, o que pode reduzir o desempenho.

O exemplo a seguir solicita as propriedades name e revenue da primeira linha do recurso accounts EntitySet.

Solicitação:

GET [Organization URI]/api/data/v9.2/accounts?$select=name,revenue&$top=1
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0  

Resposta:

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"
        }
    ]
}

O atributo de chave primária é sempre retornado, portanto, não há necessidade de incluí-lo em sua $select. Neste exemplo, accountid é a chave primária.

Você pode ver outros valores de propriedade incluídos na resposta. Nesse caso, a _transactioncurrencyid_valuepropriedade de pesquisa da referência de entidade/tabela de Moeda (TransactionCurrency) relacionada é incluída porque revenue é uma propriedade de moeda.

Quais propriedades estão disponíveis?

Você pode encontrar todas as propriedades disponíveis para uma entidade no documento de serviço $metadata. Para obter mais informações, consulte Propriedades da API Web.

Descreve Web API Entity Type Reference os tipos de entidade incluídos no Dataverse.

Valores formatados

O servidor gera valores formatados como valores de cadeia de caracteres que você pode usar em seu aplicativo. Os valores formatados incluem:

• Os rótulos localizados para escolha, opções, sim/não, status e colunas de motivo de status
• O valor principal do nome para propriedades de consulta e proprietário
• Valores monetários com símbolos de moeda
• Valores de data formatados no fuso horário do usuário

Para incluir valores formatados em seus resultados, use o cabeçalho de solicitação Prefer para enviar a preferência odata.include-annotations.

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

Valores formatados são uma das várias anotações que você pode solicitar. Use Prefer: odata.include-annotations="*" para incluir todas as anotações. Para obter mais informações, consulte As anotações de solicitação.

O valor formatado é retornado com o registro usando uma anotação que segue esta convenção:

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

Por exemplo:

Solicitação:

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"

A tabela a seguir descreve os valores e valores formatados retornados para as propriedades solicitadas.

Resposta:

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"
        }
    ]
}

Consultar dados da propriedade

Quando uma propriedade de pesquisa representa uma tabela múltipla (ou relação polimórfica), você precisa solicitar anotações específicas para determinar qual tabela contém os dados relacionados.

Por exemplo, muitas tabelas têm registros que os usuários ou as equipes possuem. O sistema armazena dados de propriedade em uma coluna de pesquisa chamada ownerid. Esta coluna é uma propriedade de navegação com valor único no OData. Você pode usar $expand para criar uma junção para obter esse valor, mas não pode usar $select. No entanto, você pode usar $select para obter a propriedade de pesquisa correspondente _ownerid_value .

Quando você inclui a propriedade de consulta _ownerid_value com o seu $select, ela retorna um valor GUID. Esse valor não informa se o proprietário do registro é um usuário ou uma equipe. Você precisa solicitar anotações para obter esses dados.

Para incluir essas anotações em seus resultados, use o cabeçalho de solicitação Prefer para enviar a opção odata.include-annotations com estas configurações:

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

Solicitação:

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"

A resposta a seguir retorna dois registros de conta diferentes. A _ownerid_value@Microsoft.Dynamics.CRM.lookuplogicalname anotação diz que um team possui o primeiro, e um systemuser possui o segundo.

Resposta:

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 é o nome lógico da tabela relacionada.
• <lookup property name>@Microsoft.Dynamics.CRM.associatednavigationproperty é o nome da propriedade de navegação de valor único correspondente. Você pode usar $expand usando esse valor em outra solicitação para obter mais dados do registro relacionado.

Apelidos de coluna

Para a API Web, use fetchxml para especificar aliases personalizados para colunas.

Atualmente, você não pode especificar aliases de coluna usando a API Web do Dataverse com o OData. O OData 4.0 não inclui a opção de consulta do sistema $compute introduzida no OData 4.01 que é necessária para fornecer essa funcionalidade.

Próximas Etapas 

Saiba como unir tabelas.