Redacció de sol·licituds HTTP i gestió d'errors per a l'API web del portals
Nota
Des del 12 d'octubre de 2022, els portals del Power Apps són Power Pages. Més informació: Microsoft Power Pages ara està disponible de manera general (bloc)
Ben aviat migrarem i combinarem la documentació dels portals del Power Apps amb la documentació del Power Pages.
La interacció amb l'API web inclou la composició de sol·licituds HTTP amb les capçaleres necessàries i la gestió de respostes HTTP, incloent-hi els errors.
Important
- La versió del portal ha de ser 9.3.3.x o posterior per poder treballar amb aquesta característica.
URL i versions de l'API web
La construcció de l'adreça URL de l'API web mitjançant el format a la taula següent.
| Part | Descripció |
|---|---|
| Protocol | https:// |
| Adreça URL base | <portal URL> |
| Camí de l'API web | _api |
| Recurs | Nom lògic de la taula que voleu utilitzar |
Per exemple, utilitzeu aquest format en fer referència a un cas:
https://contoso.powerappsportals.com/_api/case
Tots els recursos de l'API web seguiran els permisos de taula del portal respectius en el context amb funcions web.
Mètodes HTTP
Les sol·licituds HTTP poden utilitzar mètodes de diversos tipus. No obstant, l'API web dels portals només admet els mètodes de la taula següent:
| Mètode | Ús |
|---|---|
| Obtén el Yammer | Utilitzeu-ho en recuperar dades de les taules. |
| Post | Utilitzeu-lo quan creeu registres. |
| Patch | Utilitzeu-ho quan actualitzeu taules o feu operacions upsert. |
| Delete | Utilitzeu-lo quan suprimiu registres o valors de camp individuals dels registres. |
| Put | Utilitzeu-lo en situacions limitades per actualitzar camps de registres individuals. |
Capçaleres HTTP
L'API web només admet JSON. Cada capçalera HTTP ha d'incloure:
- Un valor de capçalera d'Acceptació d' aplicació/JSON, encara que no es tingui previst cap òrgan de resposta.
- Si la sol·licitud inclou dades JSON al cos de la sol·licitud, heu d'incloure una capçalera Content-Type amb un valor
application/json.
La versió actual d'OData és la 4.0, però les futures versions podrien permetre noves capacitats. Utilitzeu la sintaxi següent per assegurar-vos que no hi hagi cap ambigüitat sobre la versió OData que s'aplicarà al codi en el futur:
Sintaxi
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
Exemple: funció Wrapper AJAX per al testimoni 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)
Exemple: recuperar dades de taula
webapi.safeAjax({
type: "GET",
url: "/_api/contacts?$select=firstname,lastname",
contentType: "application/json",
success: function (res) {
console.log(res);
}
});
Exemple: crear dades de taula
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"))
}
});
Exemple: actualitzar dades de taula
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);
}
});
Exemple: suprimir dades de taula
webapi.safeAjax({
type: "DELETE",
url: "/_api/accounts(00000000-0000-0000-0000-000000000001)",
contentType: "application/json",
success: function (res) {
console.log(res);
}
});
Identificar els codis d'estat
Cada sol·licitud HTTP a la resposta inclou un codi d'estat. Els codis d'estat retornats per l'API web dels portals són els següents:
| Codi | Descripció | Type |
|---|---|---|
| 200 OK | Espereu aquesta resposta si l'operació retornarà dades al cos de resposta. | Correctes |
| 204 No Content | Espereu aquesta resposta si l'operació és correcta però no retornarà dades al cos de resposta. | Correctes |
| 403 Prohibit | Espereu aquesta resposta per als tipus d'errors següents:
|
Error del client |
| 401 No autoritzat | Espereu aquesta resposta per als tipus d'errors següents:
|
Error del client |
| 413 Payload Too Large | Espereu aquesta resposta quan la longitud de la sol·licitud és massa gran. | Error del client |
| 400 BadRequest | Espereu aquesta resposta quan un argument no és vàlid. InvalidAttribute |
Error del client |
| 404 Not Found | Espereu aquesta resposta quan el recurs no existeixi. La taula no està exposada a l'API web. |
Error del client |
| 405 Method Not Allowed | Aquest error es produeix per a combinacions incorrectes de mètodes i recursos. Per exemple, no podeu utilitzar DELETE o PATCH en una col·lecció de taules. Aquest situació pot ocórrer per als tipus d'errors següents:
|
Error del client |
| 501 Not Implemented | Espereu aquesta resposta quan algunes operacions sol·licitades no estan implementades. | Error del servidor |
| 503 Servei no disponible | Espereu aquesta resposta quan el servei de l'API web no estigui disponible. | Error del servidor |
Analitzar els errors de la resposta
Tingueu en compte la següent resposta d'HTTP d'exemple, la qual encara inclou l'error intern:
{
"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.."
}
}
}
Codis d'error
Els codis d'error es mostren en format hexadecimal per a tots els escenaris gestionats. A la taula següent s'enumera cada codi d'error amb el seu nom i el seu missatge respectiu.
| Codi d'error | Nom de l'error | Missatge d'error |
|---|---|---|
| 900400FF | NoAttributesForTableCreate | No hi ha atributs per l’acció de creació de taula. |
| 90040100 | InvalidAttribute | No s’ha trobat l’atribut {0} per a la taula {1}. |
| 90040101 | AttributePermissionIsMissing | L’atribut {0} de la taula {1} no està habilitat per a l’API web. |
| 90040102 | TablePermissionWriteIsMissingDuringUpdate | No teniu permís per actualitzar l'entitat {0}. |
| 90040103 | TablePermissionCreateIsMissing | No teniu permís per crear l'entitat {0}. |
| 90040104 | TablePermissionDeleteIsMissing | No teniu permís per suprimir l'entitat {0). |
| 90040105 | TablePermissionAppendIsMissngDuringAssociationChange | No teniu permís per associar o dissociar la taula {0} amb {1}. |
| 90040106 | TablePermissionAppendToIsMissingDuringAssociationChange | No teniu permís per associar o dissociar la taula {1} a {0}. |
| 90040107 | HttpAntiForgeryException | El testimoni de la galeta antifalsificació i el testimoni del camp de formulari no coincideixen. |
| 90040109 | MissingPortalSessionCookie | S'ha passat un testimoni de sessió no vàlid al mètode de llançament. |
| 9004010C | ResourceDoesNotExists | No s'ha trobat el recurs per al segment "{0}". |
| 9004010D | CDSError | S'ha produït un error de CDS. |
La resposta dels errors no gestionats amb el codi d'estat HTTP 500 retornarà l'error: "S'ha produït un error inesperat mentre es processava la sol·licitud".
Consulteu també
Informació general sobre l'API web de portals
Operacions d'escriptura, actualització i supressió al Portals amb l'API web
Operacions de lectura en portals mitjançant l'API web
Nota
Ens podeu dir quines són les vostres preferències d'idioma per a la documentació? Responeu una breu enquesta. (tingueu en compte que l'idioma de l'enquesta és l'anglès)
Trigareu uns set minuts a completar l'enquesta. No es recopilen dades personals (declaració de privadesa).