Partilhar via

Consultar dados usando a API da Web

  • Artigo

 

Publicado: janeiro de 2017

Aplicável a: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Se você quiser recuperar dados para um conjunto de entidades, use uma solicitação GET. Para recuperar dados, você poderá aplicar opções de consulta para definir critérios para os dados desejados e as propriedades de entidade que devem ser retornadas.

Neste tópico

Exemplo de consulta básica

Limita o número de entidades retornadas

Especifique o número de entidades a serem retornadas em uma página

Aplique as opções de consulta do sistema

Solicitar propriedades específicas

Filtrar resultados

Ordenar resultados

Use os aliases de parâmetro com as opções de consulta do sistema

Limitar resultados

Recuperar uma contagem de entidades

Incluir valores formatados

Recuperar dados sobre as propriedades de pesquisa

Filtrar registros com base na propriedade de navegação de valor único

Recuperar entidades relacionadas expandindo as propriedades de navegação

Exemplo de consulta básica

Este exemplo consulta o conjunto de entidades accounts e utiliza as opções de consulta de sistema $select e $top para retornar a propriedades name para as primeiras três contas:

  • Solicitação

    GET cc_WebAPI_ServiceURI/accounts?$select=name&$top=3 HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

  • Response

    HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0

{
 "@odata.context": "cc_WebAPI_ServiceURI/$metadata#accounts(name)",
 "value": [
  {
   "@odata.etag": "W/\"501097\"",
   "name": "Fourth Coffee (sample)",
   "accountid": "89390c24-9c72-e511-80d4-00155d2a68d1"
  },
  {
   "@odata.etag": "W/\"501098\"",
   "name": "Litware, Inc. (sample)",
   "accountid": "8b390c24-9c72-e511-80d4-00155d2a68d1"
  },
  {
   "@odata.etag": "W/\"501099\"",
   "name": "Adventure Works (sample)",
   "accountid": "8d390c24-9c72-e511-80d4-00155d2a68d1"
  }
 ]
}

Limita o número de entidades retornadas

A menos que você especifique um tamanho de página menor, um máximo de 5000 entidades será retornado para cada solicitação. Se houver mais entidades que correspondam aos critérios de filtragem de consulta, uma propriedade de @odata.nextLink será retornada com os resultados. Use o valor da propriedade de @odata.nextLink com uma nova solicitação GET para retornar para a próxima página de dados.

Observação

As consultas em entidades de modelo não são limitadas ou paginadas.Para obter mais informações:Consultar metadados usando a API da Web

Especifique o número de entidades a serem retornadas em uma página

Use o valor de preferência odata.maxpagesize para solicitar o número de entidades retornadas na resposta.

Observação

Você não pode usar um valor de preferência de odata.maxpagesize superior a 5.000.

O exemplo a seguir consulta o conjunto de entidades accounts e retorna a propriedade de name para as primeiras três contas.

  • Solicitação

    GET cc_WebAPI_ServiceURI/accounts?$select=name HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
Prefer: odata.maxpagesize=3

  • Resposta

    HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
Content-Length: 402
Preference-Applied: odata.maxpagesize=3

{
  "@odata.context": "cc_WebAPI_ServiceURI/$metadata#accounts(name)",
  "value": [
    {
      "@odata.etag": "W/\"437194\"",
      "name": "Fourth Coffee (sample)",
      "accountid": "7d51925c-cde2-e411-80db-00155d2a68cb"
    },
    {
      "@odata.etag": "W/\"437195\"",
      "name": "Litware, Inc. (sample)",
      "accountid": "7f51925c-cde2-e411-80db-00155d2a68cb"
    },
    {
      "@odata.etag": "W/\"468026\"",
      "name": "Adventure Works (sample)",
      "accountid": "8151925c-cde2-e411-80db-00155d2a68cb"
    }
  ],
  "@odata.nextLink": "cc_WebAPI_ServiceURI/accounts?$select=name&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%253e%253caccountid%2520last%253d%2522%257b8151925C-CDE2-E411-80DB-00155D2A68CB%257d%2522%2520first%253d%2522%257b7D51925C-CDE2-E411-80DB-00155D2A68CB%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20/%3E"
}

Use o valor da propriedade de @odata.nextLink para solicitar o próximo conjunto de registros. Não altere ou acrescente nenhuma opção de consulta adicional de sistema ao valor. Para cada solicitação subsequente para páginas adicionais, você deve usar o mesmo valor de preferência odata.maxpagesize usado na solicitação original. Além disso, armazene em cache os resultados retornados ou o valor da propriedade de @odata.nextLink para que as páginas recuperadas anteriormente possam ser retornadas.

Observação

O valor da propriedade de @odata.nextLink é URI codificado. Se você URI codificar o valor antes de enviá-lo, as informações de cookie do XML no URL causarão um erro.

Aplique as opções de consulta do sistema

Cada uma das opções de consulta do sistema que você acrescentar ao URL para o conjunto de entidades será adicionado usando a sintaxe para cadeias de caracteres de consulta. O primeiro é acrescentado após [?] e as opções de consulta subsequentes são separadas usando [&]. As opções de consulta diferenciam maiúsculas e minúsculas conforme mostrado no exemplo a seguir.

GET cc_WebAPI_ServiceURI/accounts?$select=name,revenue&$top=3&$filter=revenue gt 100000

Solicitar propriedades específicas

Use a opção de consulta $select do sistema para limitar as propriedades retornadas conforme mostrado no exemplo a seguir.

GET cc_WebAPI_ServiceURI/accounts?$select=name,revenue

Importante

Esta é uma prática recomendada de desempenho. Se a propriedades não forem especificadas usando $select, todas as propriedades serão retornadas.

Quando você solicita determinados tipos das propriedades, poderá esperar que propriedades somente leitura adicionais sejam retornadas automaticamente.

Se você solicitar um valor monetário, a propriedade de pesquisa _transactioncurrencyid_value será retornada. Esta propriedade contém apenas o valor GUID da moeda de transação para que você possa usar esse valor para recuperar informações sobre a moeda usando o transactioncurrency EntityType. Como alternativa, ao solicitar anotações você também poderá acessar dados adicionais na mesma solicitação.Para obter mais informações:Recuperar dados sobre as propriedades de pesquisa

Se você solicitar uma propriedade que faça parte de um atributo composto para um endereço, receberá a propriedade composta também. Por exemplo, se a consulta solicitar da propriedade address1_line1 um contato, a propriedade address1_composite também será retornada.Para obter mais informações:5bc03503-649d-42b5-a21f-e642c9923453#BKMK_CompositeAttributes.

Filtrar resultados

Use a opção de consulta $filter do sistema para definir os critérios para os quais as entidades serão retornadas.

Operadores de filtro padrão

A API da Web suporta os operadores de filtro OData padrão listadas na tabela a seguir.

Operador

Descrição

Exemplo

Operadores de comparação

eq

Igual a

$filter=revenue eq 100000

ne

Diferente

$filter=revenue ne 100000

gt

Maior que

$filter=revenue gt 100000

ge

Maior ou igual a

$filter=revenue ge 100000

lt

Menor que

$filter=revenue lt 100000

le

Menor ou igual a

$filter=revenue le 100000

Operadores lógicos

and

Lógico e

$filter=revenue lt 100000 and revenue gt 2000

or

Lógico ou

$filter=contains(name,'(sample)') or contains(name,'test')

not

Negação lógica

$filter=not contains(name,'sample')

Operadores de agrupamento

( )

Agrupamento de prioridade

(contains(name,'sample') or contains(name,'test')) and revenue gt 5000

Observação

Este é um subconjunto de Operações de Filtragem Integradas 11.2.5.1.1. Os operadores aritméticos e o operador de comparação não são suportados na API da Web.

Funções de consulta padrão

A API da Web oferece suporte a essas funções de consulta de cadeia de caracteres OData padrão.

Função

Exemplo

contains

$filter=contains(name,'(sample)')

endswith

$filter=endswith(name,'Inc.')

startswith

$filter=startswith(name,'a')

Observação

Este é um subconjunto de Funções de Consulta Integradas 11.2.5.1.2.Date, Math, Type, Geo e outras funções da cadeia de caracteres não têm suporte na API.

Funções de consulta da API de Web do Microsoft Dynamics 365

O Microsoft Dynamics 365 fornece um número de funções especiais que aceitam parâmetros, valores Boolianos de retorno, e pode ser usado como critério de filtragem em uma consulta. Consulte Web API Query Function Reference para uma lista dessas funções. A seguir temos um exemplo de pesquisa de Between Function por contas com um número de funcionários entre 5 e 2.000.

GET cc_WebAPI_ServiceURI/accounts?$select=name,numberofemployees&$filter=Microsoft.Dynamics.CRM.Between(PropertyName='numberofemployees',PropertyValues=["5","2000"])

Para obter mais informações:Redija uma consulta com funções.

Ordenar resultados

Especifique a ordem em que os itens são retornados usando a opção de consulta $orderby do sistema. Use o sufixo asc ou desc para especificar a ordem crescente ou decrescente, respectivamente. O padrão é crescente se o sufixo não estiver aplicado. O exemplo a seguir mostra a recuperação do nome e das propriedades de receita das contas ordenadas por receita crescente e por nome decrescente.

GET cc_WebAPI_ServiceURI/accounts?$select=name,revenue,&$orderby=revenue asc,name desc&$filter=revenue ne null

Use os aliases de parâmetro com as opções de consulta do sistema

Você pode usar os aliases de parâmetro para as opções de consulta $filter e $orderby do sistema. Os aliases de parâmetro permitem que o mesmo valor seja usado diversas vezes em uma solicitação. Se o alias não receber um valor, seu valor será nulo.

Sem aliases de parâmetro

 
GET cc_WebAPI_ServiceURI/accounts?$select=name,revenue,&$orderby=revenue asc,name desc&$filter=revenue ne null

Com aliases de parâmetro

 
GET cc_WebAPI_ServiceURI/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 utilizar funções.Para obter mais informações:Usar funções da API Web

Limitar resultados

Você pode limitar o número de resultados retornados usando a opção de consulta $top do sistema. O exemplo a seguir retornará apenas as primeiras três entidades de conta.

GET cc_WebAPI_ServiceURI/accounts?$select=name,revenue&$top=3

Observação

Limitar os resultados usando $top impedirá que a preferência odata.maxpagesize seja aplicada. Você pode usar a preferência odata.maxpagesize ou $top, mas não ambas ao mesmo tempo. Para obter mais informações sobre o odata.maxpagesize, consulte Especifique o número de entidades a serem retornadas em uma página.

Você também não deve usar $top com $count.

Recuperar uma contagem de entidades

Use a opção de consulta $count do sistema com um valor de true para incluir uma contagem de entidades que correspondem aos critérios de filtragem até 5.000.

Observação

O valor de contagem não representa o número total de entidades do sistema. Ele é limitado pelo número máximo de entidades que podem ser retornadas.Para obter mais informações:Limita o número de entidades retornadas

A propriedade @odata.count de resposta contém o número de entidades que correspondem aos critérios de filtragem independentemente de uma limitação de preferência odata.maxpagesize.

Observação

Você não deve usar $top com $count.

O exemplo a seguir mostra que há dez contas que correspondam aos critérios onde o nome contém "exemplo", mas somente as três primeiras contas são retornadas.

  • Solicitação

    GET cc_WebAPI_ServiceURI/accounts?$select=name&$filter=contains(name,'sample')&$count=true HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
Prefer: odata.maxpagesize=3

  • Resposta

    HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
Preference-Applied: odata.maxpagesize=3

{
  "@odata.context":"cc_WebAPI_ServiceURI/$metadata#accounts(name)",
"@odata.count":10,
"value":[
    {
      "@odata.etag":"W/\"502482\"","name":"Fourth Coffee (sample)","accountid":"655eaf89-f083-e511-80d3-00155d2a68d3"
    },{
      "@odata.etag":"W/\"502483\"","name":"Litware, Inc. (sample)","accountid":"675eaf89-f083-e511-80d3-00155d2a68d3"
    },{
      "@odata.etag":"W/\"502484\"","name":"Adventure Works (sample)","accountid":"695eaf89-f083-e511-80d3-00155d2a68d3"
    }
  ],"@odata.nextLink":"cc_WebAPI_ServiceURI/accounts?$select=name&$filter=contains(name,'sample')&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%253e%253caccountid%2520last%253d%2522%257b695EAF89-F083-E511-80D3-00155D2A68D3%257d%2522%2520first%253d%2522%257b655EAF89-F083-E511-80D3-00155D2A68D3%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E"
}

Se não desejar retornar nenhum dado com exceção da contagem, você poderá aplicar $count a qualquer conjunto para obter apenas o valor.

  • Solicitação

    GET cc_WebAPI_ServiceURI/accounts/$count HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

  • Resposta

    HTTP/1.1 200 OK
Content-Type: text/plain
OData-Version: 4.0

10

Incluir valores formatados

Quando desejar receber valores formatados para as propriedades com os resultados, use a preferência odata.include-annotations com o valor de OData.Community.Display.V1.FormattedValue. A resposta incluirá esses valores com as propriedades que correspondem à seguinte convenção de nomenclatura:

<propertyname>@OData.Community.Display.V1.FormattedValue

O exemplo a seguir consulta o conjunto de entidades de contas e retorna o primeiro registro, incluindo as propriedades que suportam valores formatados.

  • Solicitação

    GET cc_WebAPI_ServiceURI/accounts?$select=name,donotpostalmail,accountratingcode,numberofemployees,revenue&$top=1 HTTP/1.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": "cc_WebAPI_ServiceURI/$metadata#accounts(name,donotpostalmail,accountratingcode,numberofemployees,revenue)",
 "value": [
 {
  "@odata.etag": "W/"502170"",
  "name": "Fourth Coffee (sample)",
  "donotpostalmail@OData.Community.Display.V1.FormattedValue": "Allow",
  "donotpostalmail": false,
  "accountratingcode@OData.Community.Display.V1.FormattedValue": "Default Value",
  "accountratingcode": 1,
  "numberofemployees@OData.Community.Display.V1.FormattedValue": "9,500",
  "numberofemployees": 9500,
  "revenue@OData.Community.Display.V1.FormattedValue": "$100,000.00",
  "revenue": 100000,
  "accountid": "89390c24-9c72-e511-80d4-00155d2a68d1",
  "transactioncurrencyid_value": "50b6dd7b-f16d-e511-80d0-00155db07cb1" } ]
}

Recuperar dados sobre as propriedades de pesquisa

Se a consulta incluir propriedades de pesquisa, você pode solicitar anotações que fornecerão mais informações sobre os dados dessas propriedades. Na maioria das vezes, os mesmos dados podem ser derivados com o conhecimento das propriedades únicas avaliadas de navegação e dos dados inclusos nas entidades relacionadas. Entretanto, nos casos em que a propriedade representa um atributo de pesquisa que pode se referir a mais de um tipo de entidade, essas informações poderão informar o tipo de entidade que é referenciado pela propriedade de pesquisa.Para obter mais informações:d80cfb87-d4f1-4c75-bcc8-4f54d1351e26#bkmk_lookupProperties

Há dois tipos de anotações adicionais disponíveis para essas propriedades,

Anotação

Descrição

Microsoft.Dynamics.CRM.associatednavigationproperty

O nome da propriedade única avaliada de navegação que inclui uma referência à entidade.

Microsoft.Dynamics.CRM.lookuplogicalname

O nome lógico da entidade referenciada pela pesquisa.

Essas propriedades também podem incluir valores formatados conforme descrito em Incluir valores formatados. Assim como os valores formatados, você pode retornar as outras anotações usando o conjunto de preferências odata.include-annotations para o tipo específico de anotação desejado, ou definir o valor para "*" e retornar todas as três. O exemplo a seguir mostra a solicitação e a resposta para recuperar informações sobre a propriedade de pesquisa _customerid_value da entidade incident com as anotações inclusas.

  • Solicitação

    GET cc_WebAPI_ServiceURI/incidents(39dd0b31-ed8b-e511-80d2-00155d2a68d4)?$select=title,customerid_value&$expand=customerid_contact($select=fullname) HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Prefer: odata.include-annotations="*"

  • Resposta

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

{
   "@odata.context":"cc_WebAPI_ServiceURI/$metadata#incidents(title,_customerid_value,customerid_contact(fullname))/$entity",
   "@odata.etag":"W/\"504696\"",
   "_customerid_value@Microsoft.Dynamics.CRM.associatednavigationproperty":"customerid_contact",
   "_customerid_value@Microsoft.Dynamics.CRM.lookuplogicalname":"contact",
   "_customerid_value@OData.Community.Display.V1.FormattedValue":"Susanna Stubberod (sample)",
   "_customerid_value":"7ddd0b31-ed8b-e511-80d2-00155d2a68d4",
   "incidentid":"39dd0b31-ed8b-e511-80d2-00155d2a68d4",
   "customerid_contact":{
      "@odata.etag":"W/\"503587\"",
      "fullname":"Susanna Stubberod (sample)",
      "contactid":"7ddd0b31-ed8b-e511-80d2-00155d2a68d4"
   }
}

Filtrar registros com base na propriedade de navegação de valor único

As propriedades de navegação permitem a você acessar dados relacionados à entidade atual. As propriedades de navegação de Valor único correspondem aos atributos de pesquisa que suportam os relacionamentos de muitos para um e permitem a configuração de uma referência a outra entidade.Para obter mais informações:d80cfb87-d4f1-4c75-bcc8-4f54d1351e26#bkmk_navprops

Você pode filtrar os registros do conjunto de entidades com base na propriedade de navegação de valor único. Por exemplo, você pode recuperar contas secundárias da conta especificada. Você só pode usar o valor de atributo principal da entidade referenciada pela propriedade de navegação de valor único para filtrar registros. Por exemplo:

  • Recupere todas as contas correspondentes de uma ID de Contato especificada.

    • Solicitação

      GET cc_WebAPI_ServiceURI/accounts?$select=name&$filter=primarycontactid/contactid%20eq%20a0dbf27c-8efb-e511-80d2-00155db07c77 HTTP/1.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":"cc_WebAPI_ServiceURI/$metadata#accounts(name)",
     "value":[
    {
      "@odata.etag":"W/\"513479\"",
      "name":"Adventure Works (sample)",
      "accountid":"3adbf27c-8efb-e511-80d2-00155db07c77"
    },{
      "@odata.etag":"W/\"514057\"",
      "name":"Blue Yonder Airlines (sample)",
      "accountid":"3edbf27c-8efb-e511-80d2-00155db07c77"
    }
  ]
}

  • Como recuperar as contas filho da ID de Conta especificada.

    • Solicitação

      GET cc_WebAPI_ServiceURI/accounts?$select=name&$filter=parentaccountid/accountid%20eq%203adbf27c-8efb-e511-80d2-00155db07c77
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":"cc_WebAPI_ServiceURI/$metadata#accounts(name)",
    "value":[
    {
      "@odata.etag":"W/\"514058\"",
      "name":"Sample Child Account 1",
      "accountid":"915e89f5-29fc-e511-80d2-00155db07c77"
    },{
      "@odata.etag":"W/\"514061\"",
      "name":"Sample Child Account 2",
      "accountid":"03312500-2afc-e511-80d2-00155db07c77"
    }
  ]
}

Recuperar entidades relacionadas expandindo as propriedades de navegação

Use a $expand opção de consulta do sistema nas propriedades de navegação para controlar quais dados de entidades relacionadas são retornados. Há dois tipos de propriedades de navegação:

  • As propriedades de navegação de Valor único correspondem aos atributos de pesquisa que suportam os relacionamentos de muitos para um e permitem a configuração de uma referência a outra entidade.

  • As propriedades de navegação com Valor de coleção correspondem aos relacionamentos de um para muitos ou muitos para muitos.

Se você incluir apenas o nome da propriedade de navegação, você receberá todas as propriedades de registros relacionados. Você pode limitar as propriedades retornadas para registros relacionados usando a opção de consulta $select do sistema entre parênteses depois do nome da propriedade de navegação. Use isso para propriedades de navegação com valor único e com valor de coleção.

Observação

Para recuperar entidades relacionadas para uma instância de entidade, consulte Recuperar entidades relacionadas para uma entidade expandindo as propriedades de navegação.

  • Recupere entidades relacionadas expandindo propriedades de navegação de valor único: o exemplo a seguir demonstra como recuperar o contato de todos os registros da conta. Para os registros do contato relacionado, estamos recuperando apenas o contactid e o fullname.

    • Solicitação

      GET cc_WebAPI_ServiceURI/accounts?$select=name&$expand=primarycontactid($select=contactid,fullname) HTTP/1.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":"cc_WebAPI_ServiceURI/$metadata#accounts(name,primarycontactid,primarycontactid(contactid,fullname))","value":[
    {
      "@odata.etag":"W/\"513475\"","name":"Fourth Coffee (sample)","accountid":"36dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "contactid":"9cdbf27c-8efb-e511-80d2-00155db07c77","fullname":"Yvonne McKay (sample)"
      }
    },{
      "@odata.etag":"W/\"513477\"","name":"Litware, Inc. (sample)","accountid":"38dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "contactid":"9edbf27c-8efb-e511-80d2-00155db07c77","fullname":"Susanna Stubberod (sample)"
      }
    },{
      "@odata.etag":"W/\"513479\"","name":"Adventure Works (sample)","accountid":"3adbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "contactid":"a0dbf27c-8efb-e511-80d2-00155db07c77","fullname":"Nancy Anderson (sample)"
      }
    },{
      "@odata.etag":"W/\"513481\"","name":"Fabrikam, Inc. (sample)","accountid":"3cdbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "contactid":"a2dbf27c-8efb-e511-80d2-00155db07c77","fullname":"Maria Campbell (sample)"
      }
    },{
      "@odata.etag":"W/\"514057\"","name":"Blue Yonder Airlines (sample)","accountid":"3edbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "contactid":"a0dbf27c-8efb-e511-80d2-00155db07c77","fullname":"Nancy Anderson (sample)"
      }
    },{
      "@odata.etag":"W/\"513485\"","name":"City Power & Light (sample)","accountid":"40dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "contactid":"a6dbf27c-8efb-e511-80d2-00155db07c77","fullname":"Scott Konersmann (sample)"
      }
    },{
      "@odata.etag":"W/\"513487\"","name":"Contoso Pharmaceuticals (sample)","accountid":"42dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "contactid":"a8dbf27c-8efb-e511-80d2-00155db07c77","fullname":"Robert Lyon (sample)"
      }
    },{
      "@odata.etag":"W/\"513489\"","name":"Alpine Ski House (sample)","accountid":"44dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "contactid":"aadbf27c-8efb-e511-80d2-00155db07c77","fullname":"Paul Cannon (sample)"
      }
    },{
      "@odata.etag":"W/\"513491\"","name":"A. Datum Corporation (sample)","accountid":"46dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "contactid":"acdbf27c-8efb-e511-80d2-00155db07c77","fullname":"Rene Valdes (sample)"
      }
    },{
      "@odata.etag":"W/\"513493\"","name":"Coho Winery (sample)","accountid":"48dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "contactid":"aedbf27c-8efb-e511-80d2-00155db07c77","fullname":"Jim Glynn (sample)"
      }
    }
  ]
}

    Em vez de retornar as entidades relacionadas para os conjuntos de entidade, você pode também retornar referências (links) a entidades relacionadas expandindo a propriedade de navegação de valor único com a $ref opção. O exemplo a seguir retorna links para os registros de contato de todas as contas.

    • Solicitação

      GET cc_WebAPI_ServiceURI/accounts?$select=name&$expand=primarycontactid/$ref HTTP/1.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":"cc_WebAPI_ServiceURI/$metadata#accounts(name,primarycontactid)","value":[
    {
      "@odata.etag":"W/\"513475\"","name":"Fourth Coffee (sample)","_primarycontactid_value":"9cdbf27c-8efb-e511-80d2-00155db07c77","accountid":"36dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "@odata.id":"cc_WebAPI_ServiceURI/contacts(9cdbf27c-8efb-e511-80d2-00155db07c77)"
      }
    },{
      "@odata.etag":"W/\"513477\"","name":"Litware, Inc. (sample)","_primarycontactid_value":"9edbf27c-8efb-e511-80d2-00155db07c77","accountid":"38dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "@odata.id":"cc_WebAPI_ServiceURI/contacts(9edbf27c-8efb-e511-80d2-00155db07c77)"
      }
    },{
      "@odata.etag":"W/\"513479\"","name":"Adventure Works (sample)","_primarycontactid_value":"a0dbf27c-8efb-e511-80d2-00155db07c77","accountid":"3adbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "@odata.id":"cc_WebAPI_ServiceURI/contacts(a0dbf27c-8efb-e511-80d2-00155db07c77)"
      }
    },{
      "@odata.etag":"W/\"513481\"","name":"Fabrikam, Inc. (sample)","_primarycontactid_value":"a2dbf27c-8efb-e511-80d2-00155db07c77","accountid":"3cdbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "@odata.id":"cc_WebAPI_ServiceURI/contacts(a2dbf27c-8efb-e511-80d2-00155db07c77)"
      }
    },{
      "@odata.etag":"W/\"514057\"","name":"Blue Yonder Airlines (sample)","_primarycontactid_value":"a0dbf27c-8efb-e511-80d2-00155db07c77","accountid":"3edbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "@odata.id":"cc_WebAPI_ServiceURI/contacts(a0dbf27c-8efb-e511-80d2-00155db07c77)"
      }
    },{
      "@odata.etag":"W/\"513485\"","name":"City Power & Light (sample)","_primarycontactid_value":"a6dbf27c-8efb-e511-80d2-00155db07c77","accountid":"40dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "@odata.id":"cc_WebAPI_ServiceURI/contacts(a6dbf27c-8efb-e511-80d2-00155db07c77)"
      }
    },{
      "@odata.etag":"W/\"513487\"","name":"Contoso Pharmaceuticals (sample)","_primarycontactid_value":"a8dbf27c-8efb-e511-80d2-00155db07c77","accountid":"42dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "@odata.id":"cc_WebAPI_ServiceURI/contacts(a8dbf27c-8efb-e511-80d2-00155db07c77)"
      }
    },{
      "@odata.etag":"W/\"513489\"","name":"Alpine Ski House (sample)","_primarycontactid_value":"aadbf27c-8efb-e511-80d2-00155db07c77","accountid":"44dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "@odata.id":"cc_WebAPI_ServiceURI/contacts(aadbf27c-8efb-e511-80d2-00155db07c77)"
      }
    },{
      "@odata.etag":"W/\"513491\"","name":"A. Datum Corporation (sample)","_primarycontactid_value":"acdbf27c-8efb-e511-80d2-00155db07c77","accountid":"46dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "@odata.id":"cc_WebAPI_ServiceURI/contacts(acdbf27c-8efb-e511-80d2-00155db07c77)"
      }
    },{
      "@odata.etag":"W/\"513493\"","name":"Coho Winery (sample)","_primarycontactid_value":"aedbf27c-8efb-e511-80d2-00155db07c77","accountid":"48dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "@odata.id":"cc_WebAPI_ServiceURI/contacts(aedbf27c-8efb-e511-80d2-00155db07c77)"
      }
    }
  ]
}

    • Recupere entidades relacionadas expandindo propriedades de navegação de valor de coleção: se você expandir parâmetros de navegação de valor de coleção para recuperar entidades relacionadas de conjuntos de entidades, será retornada uma @odata.nextLink propriedade para as entidades relacionadas. Você deve usar o valor da propriedade @odata.nextLink com uma nova solicitação GET para retornar os dados necessários.

      O exemplo a seguir recupera as tarefas atribuídas aos 5 principais registros de conta.

      • Solicitação

        GET cc_WebAPI_ServiceURI/accounts?$top=5&$select=name&$expand=Account_Tasks($select%20=%20subject,%20scheduledstart) HTTP/1.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":"cc_WebAPI_ServiceURI/$metadata#accounts(name,Account_Tasks,Account_Tasks(subject,scheduledstart))","value":[
    {
      "@odata.etag":"W/\"513475\"","name":"Fourth Coffee (sample)","accountid":"36dbf27c-8efb-e511-80d2-00155db07c77","Account_Tasks":[

      ],"Account_Tasks@odata.nextLink":"cc_WebAPI_ServiceURI/accounts(36dbf27c-8efb-e511-80d2-00155db07c77)/Account_Tasks?$select%20=%20subject,%20scheduledstart"
    },{
      "@odata.etag":"W/\"513477\"","name":"Litware, Inc. (sample)","accountid":"38dbf27c-8efb-e511-80d2-00155db07c77","Account_Tasks":[

      ],"Account_Tasks@odata.nextLink":"cc_WebAPI_ServiceURI/accounts(38dbf27c-8efb-e511-80d2-00155db07c77)/Account_Tasks?$select%20=%20subject,%20scheduledstart"
    },{
      "@odata.etag":"W/\"514074\"","name":"Adventure Works (sample)","accountid":"3adbf27c-8efb-e511-80d2-00155db07c77","Account_Tasks":[

      ],"Account_Tasks@odata.nextLink":"cc_WebAPI_ServiceURI/accounts(3adbf27c-8efb-e511-80d2-00155db07c77)/Account_Tasks?$select%20=%20subject,%20scheduledstart"
    },{
      "@odata.etag":"W/\"513481\"","name":"Fabrikam, Inc. (sample)","accountid":"3cdbf27c-8efb-e511-80d2-00155db07c77","Account_Tasks":[

      ],"Account_Tasks@odata.nextLink":"cc_WebAPI_ServiceURI/accounts(3cdbf27c-8efb-e511-80d2-00155db07c77)/Account_Tasks?$select%20=%20subject,%20scheduledstart"
    },{
      "@odata.etag":"W/\"514057\"","name":"Blue Yonder Airlines (sample)","accountid":"3edbf27c-8efb-e511-80d2-00155db07c77","Account_Tasks":[

      ],"Account_Tasks@odata.nextLink":"cc_WebAPI_ServiceURI/accounts(3edbf27c-8efb-e511-80d2-00155db07c77)/Account_Tasks?$select%20=%20subject,%20scheduledstart"
    }
  ]
}

  • Recupere as entidades relacionadas expandindo as propriedades de navegação de valor único e as de valor de coleção: o exemplo a seguir demonstra como você pode expandir entidades relacionadas de conjuntos de entidade usando propriedades de navegação de valor único e de valor de coleção. Como foi explicado anteriormente, expandir propriedades de navegação de valor de coleção para recuperar entidades relacionadas para conjuntos de entidades retorna uma propriedade @odata.nextLink para as entidades relacionadas. Você deve usar o valor da propriedade @odata.nextLink com uma nova solicitação GET para retornar os dados necessários.

    Neste exemplo, estamos recuperando o contato e as tarefas atribuídos às 3 principais contas.

    • Solicitação

      GET cc_WebAPI_ServiceURI/accounts?$top=3&$select=name&$expand=primarycontactid($select=contactid,fullname),Account_Tasks($select=subject,scheduledstart)  HTTP/1.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":"cc_WebAPI_ServiceURI/$metadata#accounts(name,primarycontactid,Account_Tasks,primarycontactid(contactid,fullname),Account_Tasks(subject,scheduledstart))","value":[
    {
      "@odata.etag":"W/\"550614\"",
          "name":"Fourth Coffee (sample)",
          "accountid":"5b9648c3-68f7-e511-80d3-00155db53318",
          "primarycontactid":{
              "contactid":"c19648c3-68f7-e511-80d3-00155db53318",
              "fullname":"Yvonne McKay (sample)"
      },
      "Account_Tasks":[

       ],"Account_Tasks@odata.nextLink":"cc_WebAPI_ServiceURI/accounts(5b9648c3-68f7-e511-80d3-00155db53318)/Account_Tasks?$select=subject,scheduledstart"
    },{
      "@odata.etag":"W/\"550615\"",
          "name":"Litware, Inc. (sample)",
          "accountid":"5d9648c3-68f7-e511-80d3-00155db53318",
          "primarycontactid":{
              "contactid":"c39648c3-68f7-e511-80d3-00155db53318",
              "fullname":"Susanna Stubberod (sample)"
      },"Account_Tasks":[

      ],"Account_Tasks@odata.nextLink":"cc_WebAPI_ServiceURI/accounts(5d9648c3-68f7-e511-80d3-00155db53318)/Account_Tasks?$select=subject,scheduledstart"
    },{
      "@odata.etag":"W/\"550616\"",
      "name":"Adventure Works (sample)",
      "accountid":"5f9648c3-68f7-e511-80d3-00155db53318",
      "primarycontactid":{
        "contactid":"c59648c3-68f7-e511-80d3-00155db53318",
        "fullname":"Nancy Anderson (sample)"
      },"Account_Tasks":[

      ],"Account_Tasks@odata.nextLink":"cc_WebAPI_ServiceURI/accounts(5f9648c3-68f7-e511-80d3-00155db53318)/Account_Tasks?$select=subject,scheduledstart"
    }
  ]
}

Confira Também

Exemplo de dados de consulta de API da Web (C#)
Exemplo de dados de consulta da API Web (JavaScript do lado do cliente)
Executar operações usando A API
Compor solicitações de HTTP e lidar com erros
Criar uma entidade usando a API da Web
Recuperar uma entidade usando a API Web
Atualizar e excluir entidades que usam a API Web
Associar e desassociar entidades usando a API Web
Usar funções da API Web
Use ações API da Web
Executar operações em lote usando a API da WEB
Representar outro usuário usando API da Web
Executar operações condicionais usando A API

Microsoft Dynamics 365

© 2017 Microsoft. Todos os direitos reservados. Direitos autorais