Partilhar via


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.

  • Para Microsoft Dynamics 365 (online): use <tenant name>.crm.dynamics.com.

  • Para Implantação para a Internet (IFD): use a URL apropriada de sua instância. Será: <organization name>.<domain name>.

  • Para Dynamics 365 (local): use <server name>/<organization name>.

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:

  • v8.0/ Para Atualização 0.1 do Microsoft Dynamics CRM Online 2016 e Atualização 0.1 do Microsoft Dynamics CRM 2016

  • v8.1/ Para Atualização 1 do Microsoft Dynamics CRM Online 2016 e Microsoft Dynamics CRM 2016 Service Pack 1

  • v8.2/ para Atualização de dezembro de 2016 para Dynamics 365 (online e local)

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:

  • AccessDenied

  • AttributePermissionReadIsMissing

  • AttributePermissionUpdateIsMissingDuringUpdate

  • AttributePrivilegeCreateIsMissing

  • CannotActOnBehalfOfAnotherUser

  • CannotAddOrActonBehalfAnotherUserPrivilege

  • CrmSecurityError

  • InvalidAccessRights

  • PrincipalPrivilegeDenied

  • PrivilegeCreateIsDisabledForOrganization

  • PrivilegeDenied

  • unManagedinvalidprincipal

  • unManagedinvalidprivilegeedepth

Erro de cliente

401 Unauthorized

Aguarde isso para os seguintes tipos de erro:

  • BadAuthTicket

  • ExpiredAuthTicket

  • InsufficientAuthTicket

  • InvalidAuthTicket

  • InvalidUserAuth

  • MissingCrmAuthenticationToken

  • MissingCrmAuthenticationTokenOrganizationName

  • RequestIsNotAuthenticated

  • TamperedAuthTicket

  • UnauthorizedAccess

  • UnManagedInvalidSecurityPrincipal

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:

  • CannotDeleteDueToAssociation

  • InvalidOperation

  • NotSupported

Erro de cliente

412 Precondition Failed

Aguarde isso para os seguintes tipos de erro:

  • ConcurrencyVersionMismatch

  • DuplicateRecord

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