Redactar solicitudes HTTP e manexar erros da API web dos portais

Artigo
02/14/2023

Nota

A partir do 12 de outubro de 2022, Portais de Power Apps é Power Pages. Máis información: Microsoft Power Pages xa está dispoñible de forma xeral (blog)
Proximamente migraremos e uniremos a documentación de Portais de Power Apps coa documentación de Power Pages.

A interacción coa API web inclúe escribir solicitudes HTTP coas cabeceiras necesarias e manexar respostas HTTP, incluídos os erros.

Importante

A súa versión do portal debe ser 9.3.3.x ou posterior para que esta función funcione.

URL e versión da API web

Constrúa o URL da API web empregando o formato da seguinte táboa.

Parte	Descripción
Protocolo	https://
URL base	<portal URL>
Ruta da API web	_api
Recurso	Nome lóxico da táboa que quere usar

Por exemplo, use este formato ao referir un caso:

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

Todos os recursos da API web seguirán os respectivos permisos da táboa do portal en contexto con funcións web.

Métodos HTTP

As solicitudes HTTP poden usar diferentes tipos de métodos. Non obstante, a API web dos portais só admite os métodos da seguinte táboa:

Método	Uso
Obter	Utilízase ao recuperar datos de táboas.
Post	Use ao crear rexistros.
Patch	Úsase cando se actualizan táboas ou se realizan operacións de upsert.
SUPR	Utilízase ao eliminar rexistros ou valores de campo individuais dos rexistros.
Put	Use en situacións limitadas para actualizar campos individuais dos rexistros.

Cabeceiras HTTP

A API web só admite JSON. Cada cabeceira HTTP debe incluír:

Espérase un valor de cabeceira Aceptar de aplicación/json, mesmo cando non se espere ningún corpo de resposta.
Se a solicitude inclúe datos JSON no corpo da solicitude, deberá incluír unha cabeceira de tipo de contido cun valor de application/json.

A versión actual de OData é 4.0, pero as futuras versións poden permitir novas capacidades. Use a seguinte sintaxe para asegurarse de que non haxa ambigüidade sobre a versión de OData que se aplicará ao seu código no futuro:

Sintaxe

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

Exemplo: función AJAX Wrapper 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 datos de táboas

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

Exemplo: Crear datos de táboas

    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: Actualizar datos de táboas

        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: Eliminar datos de táboas

        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 estado

Cada resposta de solicitude HTTP inclúe un código de estado. Os códigos de estado devoltos pola API web dos portais inclúen o seguinte:

Código	Descripción	Tipo
200 OK	Espere esta resposta cando a súa operación devolva datos no corpo da resposta.	Correcto
204 Sen contido	Espere esta resposta cando a súa operación se realice correctamente, pero non devolva datos no corpo da resposta.	Correcto
403 Non permitido	Espere esta resposta para os seguintes tipos de erros: AccessDenied AttributePermissionIsMissing TablePermissionWriteIsMissingDuringUpdate TablePermissionCreateIsMissing TablePermissionDeleteIsMissing TablePermissionAppendIsMissngDuringAssociationChange TablePermissionAppendToIsMissingDuringAssociateChange	Erro do cliente
401 Non autorizado	Espere esta resposta para os seguintes tipos de erros: MissingPortalRequestVerificationToken MissingPortalSessionCookie	Erro do cliente
413 Carga demasiado grande	Espere esta resposta cando a lonxitude da solicitude sexa demasiado grande.	Erro do cliente
400 BadRequest	Espere esta resposta cando un argumento non é válido. InvalidAttribute	Erro do cliente
404 Non se atopou	Espere esta resposta cando o recurso non exista. A táboa non está exposta para a API web.	Erro do cliente
405 Método non permitido	Este erro prodúcese en combinacións de recursos e métodos incorrectos. Por exemplo, non pode usar DELETE ou PATCH nunha colección de táboas. Esta situación pode ocorrer para os seguintes tipos de erros: InvalidOperation NotSupported	Erro do cliente
501 Non implementado	Espere esta resposta cando non se implemente algunha operación solicitada.	Erro de servidor
503 Servizo non dispoñible	Agarde esta resposta cando o servizo da API web non estea dispoñible.	Erro de servidor

Analizar os erros da resposta

Considere o seguinte exemplo de resposta HTTP que aínda inclúe 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ódigos de erro

Os códigos de erro móstranse en formato hexadecimal para todos os escenarios manexados. A seguinte táboa enumera cada código de erro co seu nome e mensaxe respectivos.

Código de erro	Nome do erro	Mensaxe de erro
900400FF	NoAttributesForTableCreate	Non hai atributos para a acción Crear táboa.
90040100	InvalidAttribute	Non se atopou o atributo {0} para a táboa {1}.
90040101	AttributePermissionIsMissing	O atributo {0} da táboa {1} non está activado para a API web.
90040102	TablePermissionWriteIsMissingDuringUpdate	Non ten permiso para actualizar a entidade {0}.
90040103	TablePermissionCreateIsMissing	Non ten permiso para crear a entidade {0}.
90040104	TablePermissionDeleteIsMissing	Non ten permiso para eliminar a entidade {0}.
90040105	TablePermissionAppendIsMissngDuringAssociationChange	Non ten permiso para asociar ou desvincular a táboa {0} con {1}.
90040106	TablePermissionAppendToIsMissingDuringAssociationChange	Non ten permiso para asociar ou desvincular a táboa {1} a {0}
90040107	HttpAntiForgeryException	O token de cookies antifalsificación e o token de campo de formulario non coinciden.
90040109	MissingPortalSessionCookie	Un token de sesión non válido pasouse ao método de lanzamento.
9004010C	ResourceDoesNotExists	Non se atopou o recurso para o segmento "{0}".
9004010D	CDSError	Ocorreu un erro de CDS.

A resposta por erros non administrados co código de estado do HTTP 500 devolverá o erro: "Produciuse un erro inesperado ao procesar a solicitude".

Consulte tamén

Visión xeral da API web dos portais
Operacións de escritura, actualización e eliminación de portais mediante a API web
Operacións de lectura de portais mediante a API web