Partilhar via

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

  • Artigo

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.

Importante

  • A versão do seu portal tem ser a 9.3.3.x ou posterior para que esta funcionalidade funcione.

URL Web API e controlo de versões

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

Parte Description
Protocolo https://
URL Base <URL do portal>
Caminho da API Web _api
recurso Nome lógico da tabela que pretende utilizar

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:

Method Utilização
Obter Utilize ao obter os dados a partir de tabelas.
Post Utilize ao criar registos.
Patch Utilize ao atualizar tabelas ou a fazer operações upsert.
Delete Utilize o ao eliminar registos ou valores de campo individuais de recursos.
Put Utilizar em situações limitadas para atualizar campos de registos individuais.

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:

Código Description Type
200 OK Espere esta resposta quando a sua operação devolver dados no corpo de resposta. Êxito
204 Sem Conteúdo Espere esta resposta quando a sua operação tiver êxito, mas não devolver dados no corpo de resposta. Êxito
403 Proibido Espere esta resposta para os seguintes tipos de erros:
  • AccessDenied
  • AttributePermissionIsMissing
  • TablePermissionWriteIsMissingDuringUpdate
  • TablePermissionCreateIsMissing
  • TablePermissionDeleteIsMissing
  • TablePermissionAppendIsMissngDuringAssociationChange
  • TablePermissionAppendToIsMissingDuringAssociateChange
 Erro do cliente
401 Não Autorizado Espere esta resposta para os seguintes tipos de erros:
  • MissingPortalRequestVerificationToken
  • MissingPortalSessionCookie
 Erro do cliente
413 Payload Demasiado Grande Espere esta resposta quando o comprimento do pedido for demasiado grande. Erro do cliente
400 BadRequest Espere esta resposta quando um argumento for inválido.
InvalidAttribute		 Erro do cliente
404 Não Encontrado Espere esta resposta quando o recurso não existir.
A tabela não é exposta para a API Web.		 Erro do Cliente
405 Método Não Permitido Este erro ocorre para combinações incorretas de métodos e recursos. Por exemplo, não é possível utilizar DELETE ou PATCH numa coleção de tabelas. Esta situação pode ocorrer para os seguintes tipos de erros:
  • InvalidOperation
  • NotSupported
 Erro do cliente
501 Não Implementado Espere esta resposta quando alguma operação solicitada não for implementada. Erro do servidor
503 Serviço Indisponível Espere esta resposta quando o serviço API Web não estiver disponível. Erro do servidor

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.

Código de erro Nome do erro Mensagem de erro
900400FF NoAttributesForTableCreate Não existem atributos para a ação Criar Tabela.
90040100 InvalidAttribute Não foi possível encontrar o atributo {0} para a tabela {1}.
90040101 AttributePermissionIsMissing O atributo {0} na tabela {1} não está ativado para a API Web.
90040102 TablePermissionWriteIsMissingDuringUpdate Não tem permissão para atualizar a entidade {0}.
90040103 TablePermissionCreateIsMissing Não tem permissão para criar a entidade {0}.
90040104 TablePermissionDeleteIsMissing Não tem permissão para eliminar a entidade {0).
90040105 TablePermissionAppendIsMissngDuringAssociationChange Não tem permissão para associar ou desassociar a tabela {0} com {1}.
90040106 TablePermissionAppendToIsMissingDuringAssociationChange Não tem permissão para associar ou desassociar a tabela {1} com {0}.
90040107 HttpAntiForgeryException O token de cookie anti-falsificação e o símbolo de campo de formulário não correspondem.
90040109 MissingPortalSessionCookie Um token de sessão inválida foi passado para o método de arremesso.
9004010C ResourceDoesNotExists Não foi encontrado o recurso para o segmento "{0}".
9004010D CDSError Ocorreu um erro do CDS.

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