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

Artigo
02/15/2023

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