Compor solicitações HTTP e lidar com erros da API Web de portais
A interação com a API Web inclui compor solicitações HTTP com cabeçalhos necessários e manipular respostas HTTP, incluindo erros.
Importante
- Sua versão do portal deve ser 9.3.3.x ou posterior para que este recurso funcione.
URL e controle de versão da API Web
Construa a URL da API Web usando o formato na tabela a seguir.
| Parte | Descrição |
|---|---|
| Protocolo | https:// |
| URL Base | <URL do portal> |
| Caminho da API Web | _api |
| Recurso | Nome lógico da tabela que deseja usar |
Por exemplo, use este formato ao referenciar um caso:
https://contoso.powerappsportals.com/_api/case
Todos os recursos de API Web seguirão as respectivas permissões da tabela no contexto com funções Web.
Métodos HTTp
Solicitações HTTP podem usar diferentes tipos de métodos. No entanto, a API Web de portais só é compatível com os métodos na seguinte tabela:
| método | Uso |
|---|---|
| Get | Use ao recuperar dados de tabelas. |
| Post | Use ao criar registros. |
| Correção | Use ao atualizar tabelas ou fazer operações upsert. |
| Delete | Use ao excluir registros ou valores de campos individuais dos registros. |
| Put | Use em situações limitadas para atualizar campos individuais dos registros. |
Cabeçalhos HTTP
A API Web oferece suporte apenas a JSON. Cada cabeçalho HTTP deve incluir:
- Um valor do cabeçalho Accept de application/json, mesmo quando nenhum corpo de resposta é esperado.
- Se a solicitação incluir dados JSON no corpo da solicitação, você deverá incluir um cabeçalho Content-Type com um valor
application/json.
A versão atual do OData é a 4.0, mas versões futuras poderão permitir novas funcionalidades. Use a seguinte sintaxe para garantir que não haja ambiguidade sobre a versão 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 da 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: excluir 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 status
Cada resposta de solicitação HTTP inclui um código de status. Os códigos de status retornados pela API Web de portais incluem o seguinte:
| Code | Description | Type |
|---|---|---|
| 200 OK | Espere essa resposta quando sua operação retornar dados no corpo da resposta. | Êxito |
| 204 Nenhum Conteúdo | Espere essa resposta quando sua operação for bem-sucedida mas não retornar dados no corpo da resposta. | Êxito |
| 403 Proibido | Espere esta resposta para os seguintes tipos de erro:
|
Erro de cliente |
| 401 Não Autorizado | Espere essa resposta para os seguintes tipos de erro:
|
Erro de cliente |
| 413 Conteúdo Muito Grande | Espere essa resposta quando a duração da solicitação for muito grande. | Erro de cliente |
| 400 BadRequest | Espere essa resposta quando um argumento for inválido. InvalidAttribute |
Erro de cliente |
| 404 Não Encontrado | Espere essa resposta quando o recurso não existir. A tabela não está exposta para a API Web. |
Erro de cliente |
| 405 Método Não Permitido | Esse erro ocorre com combinações de método incorretas e recursos. Por exemplo, você não pode usar DELETE ou PATCH em uma coleção de tabelas. Essa situação pode acontecer para os seguintes tipos de erro:
|
Erro de cliente |
| 501 Não Implementado | Espere essa resposta quando algumas operações solicitadas não forem implementadas. | Erro do servidor |
| 503 Serviço Indisponível | Espere essa resposta quando o serviço API Web não estiver disponível. | Erro do servidor |
Erros parciais 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ódigo de erro
Os códigos de erro são exibidos no formato hexadecimal para todos os cenários manipulados. A tabela a seguir lista cada código de erro com o respectivo nome e mensagem.
| Código de erro | Nome do erro | Mensagem de erro |
|---|---|---|
| 900400FF | NoAttributesForTableCreate | Nenhum atributo para a ação Criar Tabela. |
| 90040100 | InvalidAttribute | Não é possível encontrar o atributo {0} da tabela {1}. |
| 90040101 | AttributePermissionIsMissing | O atributo {0} na tabela {1} não está habilitado para a API Web. |
| 90040102 | TablePermissionWriteIsMissingDuringUpdate | Você não tem permissão para atualizar a entidade {0}. |
| 90040103 | TablePermissionCreateIsMissing | Você não tem permissão para criar a entidade {0}. |
| 90040104 | TablePermissionDeleteIsMissing | Você não tem permissão para excluir a entidade {0). |
| 90040105 | TablePermissionAppendIsMissngDuringAssociationChange | Você não tem permissão para associar ou desassociar a tabela {0} com {1}. |
| 90040106 | TablePermissionAppendToIsMissingDuringAssociationChange | Você não tem permissão para associar ou desassociar a tabela {1} a {0} |
| 90040107 | HttpAntiForgeryException | O token de cookie antifalsificação e o token do campo de formulário não correspondem. |
| 90040109 | MissingPortalSessionCookie | Um token de sessão inválido foi passado para o método de lançamento. |
| 9004010C | ResourceDoesNotExists | Recurso não encontrado para o segmento '{0}'. |
| 9004010D | CDSError | Erro de CDS. |
A resposta para erros não tratados com o código de status HTTP 500 retornará o erro "Ocorreu um erro inesperado ao processar a solicitação".