Compor solicitações de HTTP e lidar com erros

Publicado: janeiro de 2017

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

Você interage com o API da Web compondo e enviando solicitações HTTP. Você precisa saber como definir o cabeçalho HTTP apropriado e lidar com quaisquer erros incluindo a resposta.

Neste tópico

URL e versões de API da Web

Métodos HTTp

Cabeçalhos HTTP

Identificar códigos de status

Erros parciais da resposta

URL e versões de API da Web

Para acessar a API da Web é necessário compor um URL usando os componentes da seguinte tabela.

A URL que você usa será composta destas partes: Protocol + URL Base + caminho da API da Web + Versão + Recurso.

Compatibilidade da versão.

Nesta versão aplicamos várias alterações complementares a cada atualização ou service pack. Quando essas atualizações são aplicadas elas adicionam os mesmos recursos às versões secundárias subsequentes. Por isso, se você usar a versão 8.2, então as versões 8.1 e 8.0 terão os mesmos recursos. Isso ocorre porque todas as alterações foram complementos ou correções de bug que tratam os itens listados no Limitações de API Web do Microsoft Dynamics 365. Nenhuma alteração importante foi introduzida.

Métodos HTTp

Solicitações HTTP podem ser aplicadas a uma variedade de métodos diferentes. Ao usar a API da Web você usará apenas métodos listados na tabela a seguir.

Cabeçalhos HTTP

Embora o protocolo OData permita ambos os formatos JSON e ATOM, a API da Web suporta apenas JSON. Portanto, os cabeçalhos a seguir podem ser aplicados.

Cada solicitação deve incluir o valor do cabeçalho Accept de application/json, mesmo quando nenhum corpo de resposta é esperado. Qualquer erro retornado na resposta será devolvido como JSON. Enquanto seu código deve funcionar mesmo se o cabeçalho não estiver incluído, recomendamos incluí-lo como uma melhor prática.

A versão atual de OData é 4.0, mas versões futuras podem permitir novas funcionalidades. Para garantir que não há nenhuma ambiguidade na versão de OData que será aplicada a seu código em algum momento no futuro, você sempre deve incluir uma declaração explícita da versão atual de OData e da versão Maximum a ser aplicada em seu código. Use os dois cabeçalhos OData-Version e OData-MaxVersion definidos como um valor de 4.0.

Todos cabeçalhos HTTP devem incluir pelo menos os cabeçalhos a seguir.

Accept: application/json OData-MaxVersion: 4.0 OData-Version: 4.0

Cada solicitação que inclui dados JSON no corpo da solicitação deve incluir um cabeçalho Content-Type com um valor de application/json.

Content-Type: application/json

Você pode usar cabeçalhos adicionais para habilitar funcionalidades específicas.

• Para retornar dados nas operações create (POST) ou update (PATCH) para entidades, inclua a preferência return=representation. Quando essa preferência é aplicada a uma solicitação POST, uma resposta bem-sucedida terá o status 201 (Created). Para uma solicitação PATCH, uma resposta bem-sucedida terá um status 200 (OK). Sem essa preferência aplicada, ambas as operações retornarão o status 204 (No Content) para refletir que, por padrão, nenhum dado será retornado no corpo da resposta.

  Observação

  Esse recurso foi adicionado no Atualização de dezembro de 2016 para Dynamics 365 (online e local).

• Para voltar aos valores formatados com uma consulta, inclua a preferência odata.include-annotationsdefinida no Microsoft.Dynamics.CRM.formattedvalueusando o cabeçalho de Preferência.Para obter mais informações:Incluir valores formatados

• Você também usa o cabeçalho Prefer com a opção odata.maxpagesize para especificar quantas páginas você deseja devolver.Para obter mais informações:Especifique o número de entidades a serem retornadas em uma página

• Para representar outro usuário quando o autor de chamada tem os privilégios para fazê-lo, adicione o cabeçalho MSCRMCallerID com o valor systemuserid do usuário a ser representado.Para obter mais informações:Representar outro usuário usando API da Web.

• Para aplicar a simultaneidade otimista, você pode aplicar o cabeçalho If-Matchcom um valor Etag.Para obter mais informações:Aplicar simultaneidade otimista.

• Para habilitar a detecção de duplicidades para uma solicitação POST, você pode usar o cabeçalho MSCRM.SuppressDuplicateDetection: false.Para obter mais informações:244259ca-2fbc-4fd4-9a74-6166e6683355#bkmk_SuppressDuplicateDetection

• Para controlar se uma operação upsert deve criar e atualizar uma entidade, você também pode usar os cabeçalhos If-Matche If-None-Match.Para obter mais informações:Upsert de uma entidade.

• Quando você executar operações em lote, você deve aplicar um número de cabeçalhos diferente na solicitação e com cada parte enviada no corpo.Para obter mais informações:Executar operações em lote usando a API da WEB.

Identificar códigos de status

Se uma solicitação http for bem-sucedida ou falhar, a resposta incluirá o código de status. Os códigos de status devolvidos ao API da Web Microsoft Dynamics 365 incluem o seguinte.

Erros parciais da resposta

Os detalhes sobre erros são incluídos como JSON na resposta. Os erros estarão neste formato.

    { "error":{ "code": "
            <This code is not related to the http status code and is frequently empty>", "message": "
            <A message describing the error>", "innererror": { "message": "
            <A message describing the error, this is frequently the same as the outer message>", "type": "Microsoft.Crm.CrmHttpException", "stacktrace": "
            <Details from the server about where the error occurred>" } } }

Confira Também

Executar operações usando A API
Consultar dados usando a API da Web
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