Recuperar uma entidade usando a API Web

Artigo
10/31/2017

Publicado: janeiro de 2017

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

Use uma solicitação GET para recuperar dados para uma entidade especificada como o recurso com um identificador exclusivo. Para recuperar uma entidade, você também pode solicitar propriedades específicas e expandir as propriedades de navegação para retornar propriedades das entidades relacionadas.

Observação

Para obter mais informações sobre a recuperação de metadados de entidade, consulte Consultar metadados usando a API da Web.

Neste tópico

Exemplo de recuperação básica

Recuperar propriedades específicas

Recuperar usando uma chave alternativa

Recuperar um único valor de propriedade

Recuperar valores de propriedades de navegação

Recuperar entidades relacionadas para uma entidade expandindo as propriedades de navegação

Opções para aplicar a entidades expandidas

Detectar se uma entidade foi alterada desde sua recuperação

Recuperar valores formatados

Exemplo de recuperação básica

Este exemplo retorna dados para uma instância de entidade conta com o valor da chave primária igual a 00000000-0000-0000-0000-000000000001.

GET cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001)

Para recuperar mais de uma entidade de cada vez, confira Exemplo de consulta básica, no tópico Consultar dados usando a API da Web.

Cuidado

O exemplo acima retornará todas as propriedades do registro da conta, o que é contrário às práticas recomendadas de desempenho para recuperação de dados. Esse exemplo foi apenas para ilustrar como se pode fazer uma recuperação básica de uma instância de entidade no Dynamics 365. Como todas as propriedades foram retornadas, não incluímos informações de resposta para a solicitação deste exemplo.

Como prática recomendada de desempenho, você sempre deve usar a opção de consulta $select do sistema para limitar as propriedades retornadas ao recuperar dados. Confira a seção a seguir, Recuperar propriedades específicas, para obter informações a respeito.

Recuperar propriedades específicas

Use a opção de consulta $select do sistema para limitar as propriedades retornadas incluindo uma lista de nomes de propriedades separados por vírgulas. Essa é uma prática recomendada importante de desempenho. Se a propriedades não forem especificadas usando $select, todas as propriedades serão retornadas.

O exemplo a seguir recupera as propriedades name e revenue da entidade da conta com o valor de chave primária igual a 00000000-0000-0000-0000-000000000001

Solicitação

GET cc_WebAPI_ServiceURI/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

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

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.

Recuperar usando uma chave alternativa

Se uma entidade tiver uma chave alternativa definida, você também poderá usar a chave alternativa para recuperar a entidade em vez do identificador exclusivo da entidade. Por exemplo, se a entidade Contact tiver uma definição de chave alternativa que inclua as propriedades firstname e emailaddress1, você poderá recuperar o contato usando uma consulta com os dados fornecidos nas chaves conforme mostrado aqui.

GET cc_WebAPI_ServiceURI/contacts(firstname='Joe',emailaddress1='abc@example.com')

Sempre que precisar identificar uma entidade exclusivamente para recuperar, atualizar ou excluir, você poderá usar as chaves alternativas configuradas para a entidade. Por padrão, não há nenhuma chave alternativa configurada para entidades. As chaves alternativas só estarão disponíveis se a organização adicioná-las.

Recuperar um único valor de propriedade

Quando você precisa recuperar apenas o valor de uma única propriedade de uma entidade, você pode acrescentar o nome da propriedade ao URI de uma entidade para retornar apenas o valor daquela propriedade. Essa é uma prática recomendável de desempenho porque menos dados precisam ser retornados na resposta.

Este exemplo retorna apenas o valor da propriedade name de uma entidade conta.

Solicitação

GET cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001)/name 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(00000000-0000-0000-0000-000000000001)/name",
"value":"Adventure Works (sample)"
}

Recuperar valores de propriedades de navegação

Da mesma forma como você pode recuperar valores de propriedades individuais, também é possível acessar os valores de propriedades de navegação (campos de pesquisa) acrescentando o nome da propriedade de navegação ao URI fazendo referência a uma entidade individual.

O exemplo a seguir retorna o nome completo do contato principal de uma conta usando a propriedade de navegação com valor único primarycontactid.

Solicitação

GET cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001)/primarycontactid?$select=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#contacts(fullname)/$entity",
"@odata.etag": "W/\"500128\"",
"fullname": "Rene Valdes (sample)",
"contactid": "ff390c24-9c72-e511-80d4-00155d2a68d1"
}

Para propriedades de navegação com valor de coleção, você tem a opção de solicitar o retorno apenas de referências às entidades relacionadas ou apenas uma contagem das entidades relacionadas.

O exemplo a seguir retornará referências apenas às tarefas relacionadas a uma conta específica adicionando /$ref à solicitação.

Solicitação

GET cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001)/AccountTasks/$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#Collection($ref)",
"value": [
{
"@odata.id": "cc_WebAPI_ServiceURI/tasks(6b5941dd-d175-e511-80d4-00155d2a68d1)"
},
{
"@odata.id": "cc_WebAPI_ServiceURI/tasks(fcbb60ed-d175-e511-80d4-00155d2a68d1)"
}
]
}

O exemplo a seguir retorna o número de tarefas relacionadas a uma conta específica usando a propriedade de navegação com valor de coleção Account_Tasks com /$count acrescentado.

Solicitação

GET cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001)/Account_Tasks/$count HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

Resposta
```
ï»¿2
```

Observação

O valor retornado inclui os caracteres BOM (marca de ordem de byte) UTF-8 (ï»¿) que indicam que este é um documento UTF-8.

Recuperar entidades relacionadas para uma entidade expandindo as propriedades de navegação

Use a opção de consulta $expand do sistema 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 simplesmente 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 conjuntos de entidade, confira Recuperar entidades relacionadas expandindo as propriedades de navegação.

Recupere as entidades relacionadas para uma instância de entidade expandindo as propriedades de navegação com valor único: o exemplo a seguir demonstra como recuperar o contato de uma entidade conta. Para o registro do contato relacionado, estamos recuperando apenas o contactid e o fullname.

Solicitação

GET cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001)?$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))/$entity",
"@odata.etag":"W/\"550616\"",
"name":"Adventure Works (sample)",
"accountid":"00000000-0000-0000-0000-000000000001",
"primarycontactid":{
"@odata.etag":"W/\"550626\"",
"contactid":"c59648c3-68f7-e511-80d3-00155db53318",
"fullname":"Nancy Anderson (sample)"
}
}

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

Solicitação

GET cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001)?$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)/$entity",
"@odata.etag":"W/\"550616\"",
"name":"Adventure Works (sample)",
"accountid":"00000000-0000-0000-0000-000000000001",
"_primarycontactid_value":"c59648c3-68f7-e511-80d3-00155db53318",
"primarycontactid":{
"@odata.id":"cc_WebAPI_ServiceURI/contacts(c59648c3-68f7-e511-80d3-00155db53318)"
}
}

Recupere as entidades relacionadas para uma instância de entidade expandindo as propriedade de navegação com valor de coleção: o exemplo a seguir demonstra como recuperar todas as tarefas atribuídas a um registro da conta.

Solicitação

GET cc_WebAPI_ServiceURI/accounts(915e89f5-29fc-e511-80d2-00155db07c77)?$select=name&$expand=Account_Tasks($select=subject,scheduledstart)
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))/$entity",
"@odata.etag":"W/\"514069\"","name":"Sample Child Account 1","accountid":"915e89f5-29fc-e511-80d2-00155db07c77",
"Account_Tasks":[
{
"@odata.etag":"W/\"514085\"",
"subject":"Sample Task 1",
"scheduledstart":"2016-04-11T15:00:00Z",
"activityid":"a983a612-3ffc-e511-80d2-00155db07c77"
},{
"@odata.etag":"W/\"514082\"",
"subject":"Sample Task 2",
"scheduledstart":"2016-04-13T15:00:00Z",
"activityid":"7bcc572f-3ffc-e511-80d2-00155db07c77"
}
]
}

Observação

Se você expandir sobre parâmetros de navegação com valor de coleção para recuperar entidades relacionadas para conjuntos de entidades, uma propriedade @odata.nextLink será retornada em vez das entidades relacionadas. Você deve usar o valor da propriedade @odata.nextLink com uma nova solicitação GET para retornar os dados necessários.Para obter mais informações:Recuperar entidades relacionadas expandindo as propriedades de navegação

Recupere as entidades relacionadas para uma instância de entidade expandindo as propriedades com valor único e com valor de coleção: O exemplo a seguir demonstra como você pode expandir entidades relacionadas para uma instância de entidade usando propriedades de navegação com valor único e com valores de coleção.

Solicitação

GET cc_WebAPI_ServiceURI/accounts(99390c24-9c72-e511-80d4-00155d2a68d1)?$select=accountid&$expand=parentaccountid($select%20=%20createdon,%20name),Account_Tasks($select%20=%20subject,%20scheduledstart) HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
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(accountid,parentaccountid,Account_Tasks,parentaccountid(createdon,name),Account_Tasks(subject,scheduledstart))/$entity","@odata.etag":"W/\"514069\"","accountid":"915e89f5-29fc-e511-80d2-00155db07c77",
"parentaccountid":{
"@odata.etag":"W/\"514074\"","createdon":"2016-04-06T00:29:04Z",
"name":"Adventure Works (sample)",
"accountid":"3adbf27c-8efb-e511-80d2-00155db07c77"
},"Account_Tasks":[
{
"@odata.etag":"W/\"514085\"",
"subject":"Sample Task 1",
"scheduledstart":"2016-04-11T15:00:00Z",
"activityid":"a983a612-3ffc-e511-80d2-00155db07c77"
},{
"@odata.etag":"W/\"514082\"",
"subject":"Sample Task 2",
"scheduledstart":"2016-04-13T15:00:00Z",
"activityid":"7bcc572f-3ffc-e511-80d2-00155db07c77"
}
]
}

Observação

Não é possível usar os segmentos de caminho /$ref ou /$count para retornar apenas o URI da entidade relacionada ou uma contagem do número de entidades relacionadas

Opções para aplicar a entidades expandidas

Você pode aplicar certas opções de consulta do sistema nas entidades retornadas para uma propriedade de navegação com valor de coleção. Use uma lista de opções de consultas do sistema separada por ponto-e-vírgula entre parênteses depois do nome da propriedade de navegação com valor de coleção. Você pode usar $select, $filter, $orderby e $top.

O exemplo a seguir filtra os resultados das entidades de tarefas relacionadas a uma conta àquelas com um subject que termina com “1".

GET cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001)?$expand=Account_Tasks($filter=endswith(subject,'1');$select=subject)

O exemplo a seguir especifica que as tarefas relacionadas devem ser retornadas em ordem crescente com base na propriedade createdon.

GET cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001)?$expand=Account_Tasks($orderby=createdon asc;$select=subject,createdon)

O exemplo a seguir retorna apenas a primeira tarefa relacionada.

GET cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001)?$expand=Account_Tasks($top=1;$select=subject)

Observação

Este é um subconjunto das opções de consulta do sistema descritas na seção “11.2.4.2.1 Opções de expansão” do OData versão 4.0 parte 1: protocolo mais errata 02. As opções $skip, $count, $search, $expand e $levels não têm suporte para a API Web.

Detectar se uma entidade foi alterada desde sua recuperação

Como prática recomendada de desempenho você deve solicitar apenas os dados necessários. Se você já tiver recuperado anteriormente um registro de entidade, poderá usar a oETag associada a um registro anteriormente recuperado para executar recuperações condicionais nesse registro. Para obter mais informações, consulte Recuperações condicionais.

Recuperar valores formatados

A solicitação de valores formatados para recuperações de registros individuais é feita da mesma maneira como ao consultar conjuntos de entidades.Para obter mais informações:Incluir valores formatados.

Confira Também

Amostra de operações básicas API da Web (C#)
Exemplo de operações básicas da API Web (JavaScript do lado do cliente)
Executar operações usando A API
Compor solicitações de HTTP e lidar com erros
Consultar dados usando a API da Web
Criar uma entidade usando a API da 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

Compartilhar via

Recuperar uma entidade usando a API Web

Neste tópico

Exemplo de recuperação básica

Recuperar propriedades específicas

Recuperar usando uma chave alternativa

Recuperar um único valor de propriedade

Recuperar valores de propriedades de navegação

Recuperar entidades relacionadas para uma entidade expandindo as propriedades de navegação

Opções para aplicar a entidades expandidas

Detectar se uma entidade foi alterada desde sua recuperação

Recuperar valores formatados

Confira Também

Recursos adicionais