Componha pedidos HTTP e processe erros para a API Web de portais

Interagir com a API Web inclui a composição de pedidos HTTP com cabeçalhos necessários e manipulação de respostas HTTP, incluindo quaisquer erros.

URL Web API e controlo de versões

Construa o URL da API Web utilizando o formato na tabela seguinte.

Por exemplo, utilize este formato ao remeter um caso:

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

Todos os recursos da API Web seguirão as respetivas permissões de tabela em contexto com funções da Web.

Métodos HTTP

Os pedidos HTTP podem utilizar diferentes tipos de métodos. No entanto, os portais API Web apenas suportam os métodos na tabela seguinte:

Cabeçalhos de HTTP

A API Web suporta apenas JSON. Cada cabeçalho HTTP tem de incluir:

• Um valor de cabeçalho Aceitar de aplicação/json, mesmo quando não é esperado nenhum organismo de resposta.
• Se o pedido incluir dados JSON no corpo do pedido, tem de incluir um cabeçalho Content-Type com um valor de application/json.

A versão atual do OData é 4.0, mas futuras versões poderão permitir novas capacidades. Utilize a seguinte sintaxe para assegurar que não há ambiguidade quanto à versão do OData que será aplicada ao seu código no futuro:

Sintaxe

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

Exemplo: Função Wrapper AJAX 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 dados de tabela

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

Exemplo: Criar dados de tabela

	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: Atualizar dados de tabela

		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 dados de tabela

		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 a pedidos HTTP inclui um código de estado. Os códigos de estado devolvidos pela API Web de portais incluem o seguinte:

Erros de análise da resposta

Considere a seguinte resposta de exemplo HTTP que ainda inclui 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 são apresentados em formato hexadecimal para todos os cenários processados. A tabela que se segue lista cada código de erro com o respetivo nome e mensagem.

Resposta a erros não processados com o código de estado HTTP 500 irá devolver o erro "Ocorreu um erro inesperado durante o processamento do pedido."

Consulte também

• Descrição geral da API Web
• Operações de escrita, atualização e eliminação utilizando a API Web
• Operações de leitura que utilizam a API Web