Compor solicitações HTTP e tratar erros

Você interage com a API Web redigindo e enviando solicitações HTTP. Você precisa saber como definir os cabeçalhos HTTP apropriados e lidar com os erros incluídos na resposta.

URL e versões da API Web

Para localizar a URL da API Web para seu ambiente:

1. Entre no Power Apps e selecione seu ambiente no canto superior direito.

2. Selecione o botão Configurações no canto superior direito e selecione Recursos do Desenvolvedor.

   

   A partir daqui, você pode copiar o valor para o endpoint da API Web. Para obter mais informações, consulte Exibir recursos do desenvolvedor.

A tabela a seguir descreve as partes da URL:

A URL que você usa é composta por estas partes:

Protocolo + Nome do ambiente + Região + URL base + Caminho da API Web + Versão + Recurso.

Tamanho máximo da URL

O comprimento máximo da URL aceita por é de 32 KB (32.768 caracteres). Esse comprimento é adequado para a maioria dos tipos de solicitações, exceto determinadas GET operações que exigem parâmetros de consulta de cadeia de caracteres muito longos, como consultas usando FetchXml. Se você enviar solicitações dentro do corpo de uma solicitação $batch , poderá enviar solicitações com URLs de até 64 KB (65.536 caracteres). Saiba mais sobre como enviar FetchXml em uma solicitação $batch.

Comprimento máximo do segmento OData

O comprimento máximo de qualquer segmento individual em uma solicitação OData é de 260 caracteres. Se um único segmento da solicitação OData tiver mais de 260 caracteres de comprimento, a solicitação retornará 400 Bad Request - Invalid URL. O segmento é a parte 'Resource' da URL e inclui todos os caracteres necessários para descrever o ponto de extremidade e todos os parâmetros embutidos.

Por exemplo, se a solicitação for api/data/v9.2/MyApi(MyParameter='longvalue'), MyApi(MyParameter='longvalue') será o segmento que não pode exceder 260 caracteres. Sempre use aliases de parâmetro com funções OData. Por exemplo, redigir sua função como /api/data/v9.2/MyApi(MyParameter=@alias)?@alias='longvalue' reduz o segmento para apenas MyApi(MyParameter=@alias). Saiba mais sobre como usar aliases de parâmetro com funções de API Web.

Compatibilidade entre versões

Esta versão apresenta recursos que as versões anteriores não dão suporte. As versões secundárias subsequentes podem fornecer mais recursos que as versões secundárias anteriores não dão suporte. Seu código escrito para v9.0 continua funcionando em versões futuras quando você faz referência à v9.0 em sua URL.

À medida que novos recursos são introduzidos, eles podem entrar em conflito com versões anteriores. Essas alterações significativas são necessárias para melhorar o serviço. Na maioria das vezes, os recursos permanecem os mesmos entre as versões, mas não assuma que isso seja garantido.

Métodos HTTP

A tabela a seguir lista os métodos HTTP que você pode usar com a API Web do Dataverse.

Cabeçalhos HTTP

Todas as solicitações HTTP devem incluir pelo menos os cabeçalhos a seguir.

Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0
If-None-Match: null

Embora o protocolo OData permita o formato JSON e ATOM, a API Web dá suporte apenas ao JSON. Cada solicitação deve incluir o valor do cabeçalho application/json, mesmo quando nenhum corpo de resposta é esperado. A API Web retorna qualquer erro na resposta como JSON. Embora seu código deva funcionar mesmo se esse cabeçalho não estiver incluído, inclua-o como uma prática recomendada.

A versão atual do OData é 4.0, mas versões futuras podem introduzir novos recursos. Para garantir que não haja ambiguidade sobre a versão OData que se aplique ao código, inclua sempre uma instrução explícita da versão atual do OData e a versão máxima. Use ambos os cabeçalhos OData-Version e OData-MaxVersion definidos para um valor de 4.0.

Consultas que expandem propriedades de navegação com valor de coleção podem retornar dados armazenados em cache para essas propriedades que não refletem alterações recentes. Inclua o cabeçalho If-None-Match: null no corpo da solicitação para substituir o cache do navegador da solicitação de API Web. Para obter mais informações, consulte Protocolo de Transferência de Hipertexto (HTTP/1.1): Solicitações condicionais 3.2: If-None-Match.

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

Content-Type: application/json  

Você pode usar outros cabeçalhos para habilitar recursos específicos.

Preferir cabeçalhos

Use o cabeçalho Prefer com os valores a seguir para especificar preferências.

Solicitar anotações

Você pode solicitar dados de anotação OData diferentes para serem retornados com os resultados usando o cabeçalho da solicitação Prefer: odata.include-annotations . Você pode optar por retornar todas as anotações ou especificar anotações específicas. A tabela a seguir descreve as anotações que a API Web do Dataverse dá suporte:

Para solicitar anotações específicas, inclua-as como valores separados por vírgulas. Você também pode usar o caractere '*' como curinga. Por exemplo, o cabeçalho de solicitação a seguir Prefer inclui apenas os valores formatados e quaisquer anotações adicionais de detalhes de erro:

Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue,Microsoft.PowerApps.CDS.ErrorDetails*"

Outros cabeçalhos

Ao executar operações em lote, você deve aplicar muitos cabeçalhos diferentes na solicitação e com cada parte enviada no corpo. Mais informações: executar operações em lote usando a API Web.

Identificar códigos de status

Se uma solicitação HTTP for bem-sucedida ou falhar, a resposta inclui um código de status. A tabela a seguir descreve os códigos de status retornados pela API Web do Microsoft Dataverse.

Analisar erros da resposta

A resposta inclui detalhes sobre erros como JSON no formato a seguir.

{  
 "error":{  
  "code": "<This code is not related to the http status code and is frequently empty>",  
  "message": "<A message describing the error>"  
 }  
}  

Incluir mais detalhes relacionados aos erros

Alguns erros incluem mais detalhes por meio de anotações. Quando uma solicitação inclui o Prefer: odata.include-annotations="*" cabeçalho, a resposta inclui todas as anotações que contêm mais detalhes sobre erros e uma URL que pode direcionar você para diretrizes específicas para o erro.

Os desenvolvedores que gravam plug-ins podem definir alguns desses detalhes. Por exemplo, suponha que você tenha um plug-in que gera um erro usando o construtor InvalidPluginExecutionException(OperationStatus, Int32, String ). Esse construtor aceita um OperationStatus valor, um código de erro inteiro personalizado e uma mensagem de erro.

Um plug-in simples pode ter esta aparência:

namespace MyNamespace
{
    public class MyClass : IPlugin
    {
        public void Execute(IServiceProvider serviceProvider)
        {

            // Obtain the tracing service
            ITracingService tracingService =
            (ITracingService)serviceProvider.GetService(typeof(ITracingService));

            tracingService.Trace("Entering MyClass plug-in.");

             try
            {
                throw new InvalidPluginExecutionException(OperationStatus.Canceled, 12345, "Example Error Message.");
            }
            catch (InvalidPluginExecutionException ex)
            {
                tracingService.Trace("StackTrace:");
                tracingService.Trace(ex.StackTrace);
                throw ex;
            }
        }
    }
}

Quando você registra esse plug-in na mensagem Criar de uma entidade de conta e a solicitação para criar uma conta inclui a odata.include-annotations="*" preferência, a solicitação e a resposta se parecem com o exemplo a seguir:

Solicitação:

POST https://yourorg.api.crm.dynamics.com/api/data/v9.2/accounts HTTP/1.1
Content-Type: application/json;
Prefer: odata.include-annotations="*"
{
    "name":"Example Account"
}

Resposta:

HTTP/1.1 400 Bad Request
Content-Type: application/json; odata.metadata=minimal
{
    "error": {
        "code": "0x80040265",
        "message": "Example Error Message.",
        "@Microsoft.PowerApps.CDS.ErrorDetails.OperationStatus": "1",
        "@Microsoft.PowerApps.CDS.ErrorDetails.SubErrorCode": "12345",
        "@Microsoft.PowerApps.CDS.HelpLink": "http://go.microsoft.com/fwlink/?LinkID=398563&error=Microsoft.Crm.CrmException%3a80040265&client=platform",
        "@Microsoft.PowerApps.CDS.TraceText": "\r\n[MyNamespace: MyNamespace.MyClass ]\r\n[52e2dbb9-85d3-ea11-a812-000d3a122b89: MyNamespace.MyClass : Create of account] \r\n\r\n Entering MyClass plug-in.\r\nStackTrace:\r\n   at MyNamespace.MyClass.Execute(IServiceProvider serviceProvider)\r\n\r\n"
        "@Microsoft.PowerApps.CDS.InnerError.Message": "Example Error Message."
    }
}

A tabela a seguir descreve a anotação na resposta.

Se você não quiser receber todas as anotações na resposta, poderá especificar quais anotações deseja retornar. Em vez de usar Prefer: odata.include-annotations="*", use o seguinte valor para receber apenas valores formatados para operações que recuperam dados e o link de ajuda se ocorrer um erro: Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue,Microsoft.PowerApps.CDS.HelpLink".

Mais informações: Solicitar anotações

Adicionar uma variável compartilhada da API Web

Você pode definir um valor de cadeia de caracteres disponível para plug-ins na ExecutionContextSharedVariables coleção. Para obter mais informações, consulte:

• Adicionar uma variável compartilhada ao contexto de execução do plug-in
• Variáveis compartilhadas

Consulte também

Executar operações usando a API Web
Consultar dados usando a API Web
Criar uma linha de tabela usando a API Web
Recuperar uma linha de tabela usando a API Web
Atualizar e excluir linhas de tabela usando a API Web
Associar e desassociar linhas de tabela usando a API Web
Usar funções de API Web
Use ações API da Web
Executar operações em lote usando a API Web
Representar outro usuário usando a API Web
Execute operações condicionais usando a API Web.