Usar o OData para consultar dados

Cada consulta começa com uma coleção de entidades. As coleções de entidades incluem:

• Recursos do EntitySet: uma das coleções de API EntitySet Web.
• Coleções filtradas: um conjunto de entidades retornadas por uma propriedade de navegação com valor de coleção para um registro específico.
• Uma propriedade de navegação com valor de coleção expandida.
• Uma coleção retornada por uma função.

EntitySet Recursos

Para localizar todos os EntitySet recursos disponíveis em seu ambiente, envie uma GET solicitação para o documento do serviço de API Web:

Pedir:

GET [Organization URI]/api/data/v9.2/
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",
    "value": [
        {
            "name": "aadusers",
            "kind": "EntitySet",
            "url": "aadusers"
        },
        {
            "name": "accountleadscollection",
            "kind": "EntitySet",
            "url": "accountleadscollection"
        },
        {
            "name": "accounts",
            "kind": "EntitySet",
            "url": "accounts"
        },
      ... <Truncated for brevity>
   [
}

Por exemplo, comece com o accounts recurso EntitySet para recuperar dados do tipo de entidade de conta.

GET [Organization URI]/api/data/v9.2/accounts

Coleções filtradas

Você pode consultar qualquer coleção de entidades que uma propriedade de navegação com valor de coleção representa para um registro especificado. Por exemplo, se você quiser recuperar dados do tipo de entidade de conta em que um usuário específico é o OwningUser, use a user_accounts propriedade de navegação com valor de coleção do registro do systemuser especificado.

GET [Organization URI]/api/data/v9.2/systemusers(<systemuserid value>)/user_accounts?$select=name

Para localizar o nome da propriedade de navegação com valor de coleção:

• Para quaisquer tabelas e relações do Dataverse, verifique o Web API Entity Type Reference.
• Para quaisquer tabelas ou relações personalizadas, procure as propriedades de navegação com valor de coleção no documento de serviço $metadata.

Obter dados

Para recuperar dados de uma coleção, envie uma GET solicitação para o recurso de coleta. O exemplo a seguir mostra a recuperação de dados do tipo de entidade de conta.

Este exemplo também demonstra:

• Limitando as colunas retornadas usando $select. Saiba mais sobre como selecionar colunas.
• Ordenando resultados usando $orderby. Saiba mais sobre como ordenar colunas.
• Limitando as linhas retornadas usando $top. Saiba mais sobre como limitar o número de linhas.
• Mostrando valores formatados usando o cabeçalho da solicitação: Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue". Saiba mais sobre valores formatados.

Pedir:

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

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,statecode,statuscode)",
   "value": [
      {
         "@odata.etag": "W/\"112430907\"",
         "name": "A. Datum Corporation (sample)",
         "statecode@OData.Community.Display.V1.FormattedValue": "Active",
         "statecode": 0,
         "statuscode@OData.Community.Display.V1.FormattedValue": "Active",
         "statuscode": 1,
         "accountid": "4b757ff7-9c85-ee11-8179-000d3a9933c9"
      }
   ]
}

Refinar sua consulta

Depois de selecionar a tabela para iniciar a consulta, refina a consulta para obter os dados necessários. Os artigos a seguir explicam como concluir sua consulta.

Opções de consulta OData

Use essas opções para alterar os resultados retornados de uma coleção. A tabela a seguir descreve as opções de consulta OData compatíveis com a API Web do Dataverse.

Para aplicar várias opções, separe as opções de consulta do caminho do recurso com um ponto de interrogação (?). Separe cada opção após a primeira com uma escarpa (&). Nomes de opção diferenciam letras maiúsculas de minúsculas.

Usar aliases de parâmetro com opções de consulta

Você pode usar aliases de parâmetro para $filter e $orderby opções de consulta, mas não dentro da opção $expand . Os aliases de parâmetro permitem que você use o mesmo valor várias vezes em uma solicitação. Se o alias não tiver um valor atribuído, ele será nulo.

Sem aliases de parâmetro:

GET [Organization URI]/api/data/v9.2/accounts?$select=name,revenue
&$orderby=revenue asc,name desc
&$filter=revenue ne null

Com apelidos de parâmetro:

GET [Organization URI]/api/data/v9.2/accounts?$select=name,revenue
&$orderby=@p1 asc,@p2 desc
&$filter=@p1 ne @p3&@p1=revenue&@p2=name

Você também pode usar aliases de parâmetro ao usar funções. Saiba como usar funções de API Web

Opções de consulta OData sem suporte

A API Web do Dataverse não dá suporte às seguintes opções de consulta OData: $skip, $searche $format.

Limitações de comprimento de URL

O comprimento de uma URL em uma GET solicitação é limitado a 32 KB (32.768 caracteres). Incluir muitas opções de consulta OData complexas como um parâmetro na URL pode atingir o limite. Você pode executar uma $batch operação usando uma POST solicitação como um método para transferir as opções de consulta OData da URL para o corpo da solicitação, onde o limite é duas vezes mais longo. Ao enviar uma GET solicitação em um $batch, você pode usar URLs de até 64 KB (65.536 caracteres) de comprimento. Saiba mais sobre operações em lote usando a API Web.

Limitar o número de linhas

Para limitar o número de linhas retornadas, use a opção $top de consulta OData. Sem esse limite, o Dataverse retorna até 5.000 linhas de tabela padrão e 500 linhas de tabela elástica.

Como alternativa, especifique vários registros a serem retornados usando paginação. Não use $top quando você solicitar páginas de dados. Saiba como solicitar os resultados paginados.

Limitações

Há algumas coisas que você pode fazer usando FetchXml que o OData não dá suporte.

• Você não pode unir tabelas sem qualquer relação. O OData só permite usar a opção $expand de consulta para unir tabelas usando propriedades de navegação que fazem parte das relações no modelo de dados.

• Você não pode usar $expand aninhado com relações N:N.

• As limitações de agregação listam as seguintes limitações para agregações usando o OData:

  • Obter um número distinto com CountColumn
  • Fuso horário ao agrupar por data
  • Agregação de linha
  • Por limite de consulta

• Execute comparações entre colunas de tabela. O OData dá suporte à filtragem em valores de coluna na mesma linha, mas eles devem estar na mesma tabela.

• Você não precisa substituir a ordem de classificação padrão para colunas de escolha. O comportamento padrão ao classificar colunas de escolha é usar os valores inteiros em vez do valor do rótulo localizado.

• Você não pode usar a otimização de desempenho da consulta de materialização tardia.

Ferramentas da comunidade

O Construtor REST do Dataverse é um projeto de software livre que fornece uma interface do usuário que ajuda você a fazer muitas coisas usando a API Web do Dataverse, incluindo a composição de consultas.

O XrmToolBoxFetchXMLBuilder é uma ferramenta gratuita para redigir e testar solicitações FetchXml, mas também gera código para consultas OData usando a mesma experiência de designer.

Recursos do OData versão 4.0

A API Web do Dataverse é um serviço OData versão 4.0. Estas seções da especificação OData 4.0 descrevem como recuperar dados:

• OData versão 4.0. Parte 1: Protocol Plus Errata 03 11.2 Requisição de Dados
• OData versão 4.0. Parte 2: Convenções de URL e Errata 03: 5 Opções de Consulta

Este artigo e os outros artigos desta seção descrevem as partes da especificação OData 4.0 que a API Web do Dataverse implementa e como você pode usá-la para recuperar dados de negócios do Dataverse.

Próximas etapas

Saiba como selecionar colunas.