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.
Item |
Descrição |
|---|---|
Protocolo |
O protocolo apropriado, https:// ou http://. |
URL base |
Trata-se da URL normalmente usada para abrir o aplicativo Web.
|
Caminho da API da Web |
O caminho para a API da Web é /api/data/. |
Versão |
A versão é expressa desta forma: v[Major_version].[Minor_version][PatchVersion]/. As versões válidas desta versão são:
O valor específico que você usa não é importante nesta versão, desde que você tenha aplicado as atualizações ou os service packs correspondentes. Mais Informações: Compatibilidade da versão. |
Recurso |
O nome da entidade, função ou ação que você deseja usar. |
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.
Observação
A próxima versão principal (v9) introduz recursos que só ficam disponíveis usando essa versão. Versões subsequentes primárias podem fornecer os recursos adicionais que não serão transferidos de volta para as versões secundárias anteriores. Seu código gravado para a v8.x continuará funcionando na v9.x quando você fizer referência à v8.2 na URL que você usa.
Para a versão v8.x, use a versão mais recente que puder e saiba que as atualizações ou service packs nesta versão principal não introduzirão alterações importantes. Porém, isso será diferente em versões futuras, onde você precisará prestar mais atenção na versão do serviço que você utiliza.
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.
Método |
Uso |
|---|---|
GET |
Use para recuperar dados, incluindo funções de chamada. O Código de Status esperado para uma recuperação bem-sucedida é 200 OK. |
POST |
Use ao criar entidades ou ações de chamada. |
PATCH |
Use quando atualizar entidades ou realizar operações upsert. |
DELETE |
Use quando excluir entidades ou propriedades individuais de entidades. |
PUT |
Use em situações limitadas para atualizar propriedades individuais de entidades. Este método não é recomendado quando atualizar a maioria das entidades. Você o usará para atualizar entidades modelo. |
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.
Código |
Descrição |
Tipo |
|---|---|---|
200 OK |
Aguarde isso quando sua operação retornará dados no corpo da resposta. |
Sucesso |
201 Created |
Espere esse comportamento quando a operação POST da sua entidade obtiver êxito e se você tiver especificado a preferência return-representation em sua solicitação. Observação Esse recurso foi adicionado no Atualização de dezembro de 2016 para Dynamics 365 (online e local). |
Sucesso |
204 No Content |
Aguarde isso quando sua operação for bem-sucedida mas não retornar dados no corpo da resposta. |
Êxito |
304 Not Modified |
Aguarde isso quando testar se uma entidade foi modificada desde sua última recuperação.Para obter mais informações:Recuperações condicionais |
Redirecionamento |
403 Forbidden |
Aguarde isso para os seguintes tipos de erro:
|
Erro de cliente |
401 Unauthorized |
Aguarde isso para os seguintes tipos de erro:
|
Erro de cliente |
413 Payload Too Large |
Aguarde isso quando a duração da solicitação for muito grande. |
Erro de cliente |
400 BadRequest |
Aguarde isso quando um argumento for inválido. |
Erro de cliente |
404 Not Found |
Aguarde isso quando o recurso não existir. |
Erro de cliente |
405 Method Not Allowed |
Esse erro ocorre com combinações de método incorretas e recursos. Por exemplo, você não pode usar DELETE ou PATCH em uma coleção de entidades. Aguarde isso para os seguintes tipos de erro:
|
Erro de cliente |
412 Precondition Failed |
Aguarde isso para os seguintes tipos de erro:
|
Erro de cliente |
500 Internal Server Error |
Aguarde isso quando uma solicitação POST para criar uma entidade habilita a detecção de duplicidades e a entidade para criar é uma duplicação.Para obter mais informações:244259ca-2fbc-4fd4-9a74-6166e6683355#bkmk_SuppressDuplicateDetection |
Erro do Servidor |
501 Not Implemented |
Aguarde isso quando algumas operações solicitadas não forem implementadas. |
Erro do servidor |
503 Service Unavailable |
Aguarde isso quando o serviço da API não estiver disponível. |
Erro do servidor |
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