Componer solicitudes HTTP y administrar errores para la API web de los portales

Artículo
02/15/2023

Nota

A partir del 12 de octubre de 2022, los portales de Power Apps son Power Pages. Más información: Microsoft Power Pages ya está disponible para el público en general (blog)
Pronto migraremos y fusionaremos la documentación de los portales de Power Apps con la documentación de Power Pages.

Interactuar con la API web incluye componer solicitudes HTTP con encabezados necesarios y manejar respuestas HTTP, incluidos los errores.

Importante

La versión de su portal debe ser 9.3.3.x o posterior para que esta función funcione.

Dirección URL y versiones de API web

Construya la URL de la API web utilizando el formato de la siguiente tabla.

Parte	Description
Protocolo	https://
URL base	<portal URL>
Ruta de la API web	_api
Recurso	Nombre lógico de la tabla que quiere usar

Por ejemplo, use este formato al referir un caso:

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

Todos los recursos de la API web seguirán las respectivos permisos de la tabla del portal en contexto con los roles web.

Métodos HTTP

Las solicitudes HTTP pueden usar diferentes tipos de métodos. Sin embargo, la API web de los portales solo admite los métodos de la siguiente tabla:

Method	Uso
Obtener	Se usa al recuperar datos de tablas.
Post	Utilícelo al crear registros.
Ruta	Se usa para actualizar tablas o realizar operaciones de upsert.
Delete	Úselo cuando elimine registros o valores de campos individuales de registros.
Put	Utilícelo en situaciones limitadas para actualizar campos individuales de los registros.

Encabezados HTTP

La API web solo admite JSON. Cada encabezado HTTP debe incluir:

Un valor de encabezado Aceptar de application/json, incluso cuando no se espera un cuerpo de respuesta.
Si la solicitud que incluya datos de JSON en el cuerpo de la solicitud, debe incluir un encabezado Content-Type con un valor de application/json.

La versión de OData actual es la 4.0, pero las versiones futuras podrían permitir nuevas funciones. Utilice la siguiente sintaxis para asegurarse de que no haya ambigüedad sobre la versión de OData que se aplicará a su código en el futuro:

Sintaxis

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

Ejemplo: función Wrapper AJAX para el 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)

Ejemplo: recuperar datos de la tabla

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

Ejemplo: Crear datos de tabla

    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"))
        }
    });

Ejemplo: Actualizar datos de tabla

        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);
        }
    });

Ejemplo: Eliminar datos de tabla

        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 respuesta de solicitud HTTP incluye un código de estado. Los códigos de estado devueltos por los portales API web incluyen lo siguiente:

Código	Description	Type
200 OK	Espere esta respuesta cuando la operación devuelva datos en el cuerpo de la respuesta.	Correcto
204 Sin contenido	Espere esta respuesta cuando la operación sea correcta, pero no devuelva datos en el cuerpo de la respuesta.	Correcto
403 Prohibida	Espere esta respuesta para los siguientes tipos de errores: AccessDenied AttributePermissionIsMissing TablePermissionWriteIsMissingDuringUpdate TablePermissionCreateIsMissing TablePermissionDeleteIsMissing TablePermissionAppendIsMissngDuringAssociationChange TablePermissionAppendToIsMissingDuringAssociateChange	Error del cliente
401 No autorizada	Espere esta respuesta para los siguientes tipos de errores: MissingPortalRequestVerificationToken MissingPortalSessionCookie	Error del cliente
413 La carga es demasiado grande	Espere esta respuesta cuando la longitud de la solicitud sea demasiado grande.	Error del cliente
400 BadRequest	Espere esta respuesta cuando un argumento no sea válido. InvalidAttribute	Error del cliente
404 No encontrado	Espere esta respuesta cuando no exista el recurso. La tabla no está expuesta para la API web.	Error de cliente
405 Método no permitido	Este error se produce porque el método y las combinaciones de recursos no son correctas. Por ejemplo, no puede utilizar DELETE o PATCH en una colección de tablas. Esta situación puede darse para los siguientes tipos de errores: InvalidOperation NotSupported	Error del cliente
501 No implementado	Espere esta respuesta cuando alguna operación solicitada no se implementa.	Error de servidor
503 Servicio no disponible	Espere esta respuesta cuando el servicio de la API web no está disponible.	Error de servidor

Errores de análisis de la respuesta

Considere la siguiente respuesta HTTP de ejemplo que todavía incluye el error 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 error

Los códigos de error se muestran en formato hexadecimal para todos los escenarios manejados. La siguiente tabla enumera cada código de error con su respectivo nombre y mensaje.

Código de error	Nombre del error	Mensaje de error
900400FF	NoAttributesForTableCreate	No hay atributos para la acción Crear tabla.
90040100	InvalidAttribute	No se puede encontrar el atributo {0} para la tabla {1}.
90040101	AttributePermissionIsMissing	El atributo {0} de la tabla {1} no está habilitado para la API web.
90040102	TablePermissionWriteIsMissingDuringUpdate	No tiene permiso para actualizar la entidad {0}.
90040103	TablePermissionCreateIsMissing	No tiene permiso para crear la entidad {0}.
90040104	TablePermissionDeleteIsMissing	No tiene permiso para eliminar la entidad {0}.
90040105	TablePermissionAppendIsMissngDuringAssociationChange	No tiene permiso para asociar o desasociar la tabla {0} con {1}.
90040106	TablePermissionAppendToIsMissingDuringAssociationChange	No tiene permiso para asociar o desasociar la tabla {1} para {0}.
90040107	HttpAntiForgeryException	El token de cookie antifalsificación y el token de campo de formulario no coinciden.
90040109	MissingPortalSessionCookie	Un token de sesión no válido se pasó al método de lanzamiento.
9004010C	ResourceDoesNotExists	No se encuentra ningún recurso para el segmento "{0}".
9004010D	CDSError	Error de CDS.

La respuesta a errores no controlados con el código de estado HTTP 500 devolverá el error: "Se produjo un error inesperado al procesar la solicitud".

Consulte también

Información general de API web de portales
Operaciones de escritura, actualización y eliminación de portales con la API web
Los portales leen operaciones utilizando la API web