Compartir a través de

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

  • Artículo

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 <URL del portal>
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 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