Compartir vía


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

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

Nota

¿Puede indicarnos sus preferencias de idioma de documentación? Realice una breve encuesta. (tenga en cuenta que esta encuesta está en inglés)

La encuesta durará unos siete minutos. No se recopilan datos personales (declaración de privacidad).