Compartir por


Redactar solicitudes HTTP e manexar erros da API web dos portais

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

Nota

Pode indicarnos as súas preferencias para o idioma da documentación? Realice unha enquisa breve. (teña en conta que esa enquisa está en inglés)

Esta enquisa durará sete minutos aproximadamente. Non se recompilarán datos persoais (declaración de privacidade).