Compartir por

Redactar solicitudes HTTP e manexar erros da API web dos portais

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

Importante

  • A versión do teu portal debe ser a 9.3.3.x ou posterior para que esta funcionalidade 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 <URL do portal>
Ruta da API web _api
Recurso Nome lóxico da táboa que desexa empregar

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 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 Utilízase 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 Utilízase en situacións limitadas para actualizar campos ou 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 deapplication/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

  • Last updated on