Compartilhar via


Compor solicitações HTTP e lidar com erros da API Web de portais

Observação

Desde o dia 12 de outubro de 2022, os portais do Power Apps passaram a ser Power Pages. Mais Informações: O Microsoft Power Pages já está disponível para todos (blog)
Em breve, migraremos e mesclaremos a documentação dos portais do Power Apps com a documentação do Power Pages.

A interação com a API Web inclui compor solicitações HTTP com cabeçalhos necessários e manipular respostas HTTP, incluindo erros.

Importante

  • Sua versão do portal deve ser 9.3.3.x ou posterior para que este recurso funcione.

URL e controle de versão da API Web

Construa a URL da API Web usando o formato na tabela a seguir.

Parte Description
Protocolo https://
URL Base <portal URL>
Caminho da API Web _api
Recurso Nome lógico da tabela que deseja usar

Por exemplo, use este formato ao referenciar um caso:

https://contoso.powerappsportals.com/_api/case

Todos os recursos de API Web seguirão as respectivas permissões da tabela do portal no contexto com funções Web.

Métodos HTTp

Solicitações HTTP podem usar diferentes tipos de métodos. No entanto, a API Web de portais só é compatível com os métodos na seguinte tabela:

Method Uso
Get Use ao recuperar dados de tabelas.
Post Use ao criar registros.
Correção Use ao atualizar tabelas ou fazer operações upsert.
Delete Use ao excluir registros ou valores de campos individuais dos registros.
Put Use em situações limitadas para atualizar campos individuais dos registros.

Cabeçalhos HTTP

A API Web oferece suporte apenas a JSON. Cada cabeçalho HTTP deve incluir:

  • Um valor do cabeçalho Accept de application/json, mesmo quando nenhum corpo de resposta é esperado.
  • Se a solicitação incluir dados JSON no corpo da solicitação, você deverá incluir um cabeçalho Content-Type com um valor application/json.

A versão atual do OData é a 4.0, mas versões futuras poderão permitir novas funcionalidades. Use a seguinte sintaxe para garantir que não haja ambiguidade sobre a versão OData que será aplicada ao seu código no futuro:

Sintaxe

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

Exemplo: função Wrapper AJAX para o token CSRF

    (function(webapi, $){
        function safeAjax(ajaxOptions) {
            var deferredAjax = $.Deferred();
    
            shell.getTokenDeferred().done(function (token) {
                // add headers for ajax
                if (!ajaxOptions.headers) {
                    $.extend(ajaxOptions, {
                        headers: {
                            "__RequestVerificationToken": token
                        }
                    }); 
                } else {
                    ajaxOptions.headers["__RequestVerificationToken"] = token;
                }
                $.ajax(ajaxOptions)
                    .done(function(data, textStatus, jqXHR) {
                        validateLoginSession(data, textStatus, jqXHR, deferredAjax.resolve);
                    }).fail(deferredAjax.reject); //ajax
            }).fail(function () {
                deferredAjax.rejectWith(this, arguments); // on token failure, pass the token ajax and args
            });
    
            return deferredAjax.promise();  
        }
        webapi.safeAjax = safeAjax;
})(window.webapi = window.webapi || {}, jQuery)

Exemplo: recuperar dados da tabela

    webapi.safeAjax({
                type: "GET",
                url: "/_api/contacts?$select=firstname,lastname",
                contentType: "application/json",
                success: function (res) {
                        console.log(res);
                }
    });

Exemplo: criar dados de tabela

    webapi.safeAjax({
        type: "POST",
        url: "/_api/accounts",
        contentType: "application/json",
        data: JSON.stringify({
            "name": "Sample Account"
        }),
        success: function (res, status, xhr) {
            console.log("entityID: "+ xhr.getResponseHeader("entityid"))
        }
    });

Exemplo: atualizar dados de tabela

        webapi.safeAjax({
        type: "PATCH",
        url: "/_api/accounts(00000000-0000-0000-0000-000000000001)",
        contentType: "application/json",
        data: JSON.stringify({
            "name": "Sample Account - Updated"
        }),
        success: function (res) {
            console.log(res);
        }
    });

Exemplo: excluir dados de tabela

        webapi.safeAjax({
        type: "DELETE",
        url: "/_api/accounts(00000000-0000-0000-0000-000000000001)",
        contentType: "application/json",
        success: function (res) {
            console.log(res);
        }
    });

Identificar códigos de status

Cada resposta de solicitação HTTP inclui um código de status. Os códigos de status retornados pela API Web de portais incluem o seguinte:

Code Description Type
200 OK Espere essa resposta quando sua operação retornar dados no corpo da resposta. Êxito
204 Nenhum Conteúdo Espere essa resposta quando sua operação for bem-sucedida mas não retornar dados no corpo da resposta. Êxito
403 Proibido Espere essa resposta para os seguintes tipos de erro:
  • AccessDenied
  • AttributePermissionIsMissing
  • TablePermissionWriteIsMissingDuringUpdate
  • TablePermissionCreateIsMissing
  • TablePermissionDeleteIsMissing
  • TablePermissionAppendIsMissngDuringAssociationChange
  • TablePermissionAppendToIsMissingDuringAssociateChange
Erro de cliente
401 Não Autorizado Espere essa resposta para os seguintes tipos de erro:
  • MissingPortalRequestVerificationToken
  • MissingPortalSessionCookie
Erro de cliente
413 Conteúdo Muito Grande Espere essa resposta quando a duração da solicitação for muito grande. Erro de cliente
400 BadRequest Espere essa resposta quando um argumento for inválido.
InvalidAttribute
Erro de cliente
404 Não Encontrado Espere essa resposta quando o recurso não existir.
A tabela não está exposta para a API Web.
Erro de cliente
405 Método Não Permitido 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 tabelas. Essa situação pode acontecer para os seguintes tipos de erro:
  • InvalidOperation
  • NotSupported
Erro de cliente
501 Não Implementado Espere essa resposta quando algumas operações solicitadas não forem implementadas. Erro do servidor
503 Serviço Indisponível Espere essa resposta quando o serviço API Web não estiver disponível. Erro do servidor

Erros parciais da resposta

Considere a seguinte resposta de exemplo HTTP que ainda inclui o erro interno:

{
  "error":{
    "code": "This code is not related to the http status code and is frequently empty",
    "message": "A message describing the error",
    "cdscode": "Dataverse error code",
    "innererror": {
        "code": "800xxxx",
        "message": "A message describing the error. This is frequently the same as the outer message.."
      }
    }
  }

Código de erro

Os códigos de erro são exibidos no formato hexadecimal para todos os cenários manipulados. A tabela a seguir lista cada código de erro com o respectivo nome e mensagem.

Código de erro Nome do erro Mensagem de erro
900400FF NoAttributesForTableCreate Nenhum atributo para a ação Criar Tabela.
90040100 InvalidAttribute Não é possível encontrar o atributo {0} da tabela {1}.
90040101 AttributePermissionIsMissing O atributo {0} na tabela {1} não está habilitado para a API Web.
90040102 TablePermissionWriteIsMissingDuringUpdate Você não tem permissão para atualizar a entidade {0}.
90040103 TablePermissionCreateIsMissing Você não tem permissão para criar a entidade {0}.
90040104 TablePermissionDeleteIsMissing Você não tem permissão para excluir a entidade {0).
90040105 TablePermissionAppendIsMissngDuringAssociationChange Você não tem permissão para associar ou desassociar a tabela {0} com {1}.
90040106 TablePermissionAppendToIsMissingDuringAssociationChange Você não tem permissão para associar ou desassociar a tabela {1} a {0}
90040107 HttpAntiForgeryException O token de cookie antifalsificação e o token do campo de formulário não correspondem.
90040109 MissingPortalSessionCookie Um token de sessão inválido foi passado para o método de lançamento.
9004010C ResourceDoesNotExists Recurso não encontrado para o segmento '{0}'.
9004010D CDSError Erro de CDS.

A resposta para erros não tratados com o código de status HTTP 500 retornará o erro "Ocorreu um erro inesperado ao processar a solicitação".

Confira também

Visão geral da API Web de portais
Operações de gravação, atualização e exclusão de portais usando a API Web
Portais leem operações usando a API Web

Observação

Você pode nos falar mais sobre suas preferências de idioma para documentação? Faça uma pesquisa rápida. (Observe que esta pesquisa está em inglês)

A pesquisa levará cerca de sete minutos. Nenhum dado pessoal é coletado (política de privacidade).