Redactar solicitudes HTTP e manexar erros da API web dos portais
Nota
A partir do 12 de outubro de 2022, Portais de Power Apps é Power Pages. Máis información: Microsoft Power Pages xa está dispoñible de forma xeral (blog)
Proximamente migraremos e uniremos a documentación de Portais de Power Apps coa documentación de Power Pages.
A interacción coa API web inclúe escribir solicitudes HTTP coas cabeceiras necesarias e manexar respostas HTTP, incluídos os erros.
Importante
- A súa versión do portal debe ser 9.3.3.x ou posterior para que esta función 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 | <portal URL> |
Ruta da API web | _api |
Recurso | Nome lóxico da táboa que quere usar |
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 do portal 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 | Use 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 | Use en situacións limitadas para actualizar campos individuais dos 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 de
application/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:
|
Erro do cliente |
401 Non autorizado | Espere esta resposta para os seguintes tipos de erros:
|
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:
|
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
Visión xeral da API web dos portais
Operacións de escritura, actualización e eliminación de portais mediante a API web
Operacións de lectura de portais mediante a API web
Nota
Pode indicarnos as súas preferencias para o idioma da documentación? Realice unha enquisa breve. (teña en conta que esa enquisa está en inglés)
Esta enquisa durará sete minutos aproximadamente. Non se recompilarán datos persoais (declaración de privacidade).
Comentarios
https://aka.ms/ContentUserFeedback.
Proximamente: Ao longo de 2024, retiraremos gradualmente GitHub Issues como mecanismo de comentarios sobre o contido e substituirémolo por un novo sistema de comentarios. Para obter máis información, consulte:Enviar e ver os comentarios