Compartilhar via

Recuperar uma linha de tabela usando a API Web

Use uma solicitação GET para recuperar dados de um registro especificado como o recurso com um identificador exclusivo. Ao recuperar uma linha de tabela (registro de entidade), você também pode solicitar propriedades específicas e expandir as propriedades de navegação para retornar propriedades de registros relacionados em tabelas diferentes.

Observação

Para obter informações sobre como recuperar definições de tabela, consulte definições de tabela de consulta usando a API Web.

Recuperação básica

O exemplo a seguir retorna dados para um registro de entidade de conta com o valor da chave primária igual a 00000000-0000-0000-0000-000000000001:

GET [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001)

Este exemplo retorna todas as propriedades do registro da conta, o que não é uma prática recomendada de desempenho. Sempre use a opção de consulta do $select sistema para limitar as propriedades retornadas durante a recuperação de dados. Essa prática é especialmente importante quando você recupera várias linhas de dados. Para obter mais informações, consulte Consultar dados usando a API Web.

Recuperar propriedades específicas

Para limitar as propriedades retornadas quando você recuperar dados com uma solicitação GET, use a opção de consulta do $select sistema com uma lista separada por vírgulas de nomes de propriedades. Solicite apenas as propriedades necessárias para melhorar o desempenho. Se você não especificar propriedades a serem retornadas, a solicitação retornará todas as propriedades.

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

Solicitação:

GET [Organization URI]/api/data/v9.2/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": "[Organization URI]/api/data/v9.2/$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"  
}

Ao solicitar determinados tipos de propriedades, você verá mais propriedades somente leitura retornadas automaticamente.

Se você solicitar um valor monetário, a _transactioncurrencyid_valuepropriedade de pesquisa será retornada. Essa propriedade contém apenas o valor GUID da moeda de transação, para que você possa usá-la para recuperar informações sobre a moeda usando o EntityType transactioncurrency. Como alternativa, você pode obter mais dados na mesma solicitação solicitando anotações.

Se você solicitar uma propriedade que faça parte de um atributo composto para um endereço, você também obterá a propriedade composta. Por exemplo, se a consulta solicitar a address1_line1 propriedade para um contato, a address1_composite propriedade também será retornada.

Recuperar registro usando uma chave alternativa

Se uma entidade tiver uma chave alternativa definida, você poderá usá-la em vez do identificador exclusivo para recuperar, atualizar ou excluir a entidade. Por padrão, nenhuma chave alternativa é configurada para entidades. Chaves alternativas só estarão disponíveis se sua organização ou uma solução as tiverem adicionadas.

Valores de chave alternativos com os seguintes caracteres /,<,>,*,%,&,:,\\,?+ não têm suporte no momento.

Por exemplo, se a Contact entidade 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 para essas chaves.

GET [Organization URI]/api/data/v9.2/contacts(firstname='Joe',emailaddress1='abc@example.com')

Se a definição de chave alternativa contiver um campo de tipo de pesquisa (por exemplo, a primarycontactid propriedade para a account entidade), você poderá recuperar o account usando as propriedades de pesquisa, como no exemplo a seguir:

GET [Organization URI]/api/data/v9.2/accounts(_primarycontactid_value=00000000-0000-0000-0000-000000000001)

Recuperar registros em partições de armazenamento

Ao recuperar um registro em uma tabela elástica armazenada em uma partição, especifique a chave de partição.

Recuperar um único valor de propriedade

Quando você precisar recuperar apenas o valor de uma única propriedade, acrescente o nome da propriedade ao URI da entidade. Reduzir a quantidade de dados retornados é uma prática recomendada de desempenho.

O exemplo a seguir retorna apenas o valor da name propriedade para uma account entidade:

Solicitação:

GET [Organization URI]/api/data/v9.2/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":"[Organization URI]/api/data/v9.2/$metadata#accounts(00000000-0000-0000-0000-000000000001)/name",
"value":"Adventure Works (sample)"
}

Recuperar o valor bruto de uma propriedade

Para recuperar o valor bruto de uma propriedade primitiva em vez de JSON, acrescente /$value à URL. Por exemplo:

Solicitação:

GET [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001)/name/$value 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

Adventure Works (sample)

O uso do valor bruto não é comum, a menos que você esteja trabalhando com dados de arquivo ou imagem. Para obter mais informações, consulte Baixar um arquivo em uma única solicitação usando a API Web.

Recuperar valores de propriedade de navegação

Você pode acessar os valores das propriedades de navegação, ou campos de pesquisa, acrescentando o nome da propriedade de navegação ao URI de uma entidade individual.

O exemplo a seguir retorna o fullname do contact primário de um account usando a propriedade de navegação com valor único primarycontactid.

Solicitação:

GET [Organization URI]/api/data/v9.2/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": "[Organization URI]/api/data/v9.2/$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ê pode solicitar o retorno apenas de referências para as entidades relacionadas ou apenas uma contagem das entidades relacionadas.

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

Solicitação:

GET [Organization URI]/api/data/v9.2/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": "[Organization URI]/api/data/v9.2/$metadata#Collection($ref)",
    "value":
  [
    { "@odata.id": "[Organization URI]/api/data/v9.2/tasks(6b5941dd-d175-e511-80d4-00155d2a68d1)" },
    { "@odata.id": "[Organization URI]/api/data/v9.2/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 de valor de coleção Account_Tasks com /$count acrescentado:

Solicitação:

GET [Organization URI]/api/data/v9.2/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 indica que esse valor é um documento UTF-8.

Use a opção de consulta do $expand sistema para controlar quais dados de entidades relacionadas são retornados. Para obter mais informações, consulte Tabelas de Junção.

Detectar se um registro foi alterado desde que foi recuperado

Como prática recomendada de desempenho, solicite apenas os dados necessários. Se você recuperou anteriormente um registro de entidade, use a ETag associada a esse registro para executar recuperações condicionais. Para obter mais informações, consulte Recuperações condicionais.

Recuperar valores formatados

Solicite valores formatados para recuperações de registros individuais da mesma forma que você consulta conjuntos de entidades.

Consulte também

Executar operações usando a API Web
Redigir solicitações HTTP e manipular erros
Consultar dados usando a API Web

  • Last updated on