Redacció de sol·licituds HTTP i gestió d'errors per a l'API web del portals
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 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 la taula del portal respectius en context amb les funcions web.
Mètodes HTTP
Les sol·licituds HTTP poden utilitzar mètodes de diversos tipus. No obstant això, l'API web dels portals només admet els mètodes de la taula següent:
| Mètode | Ús |
|---|---|
| Obtén el Yammer | S'utilitza en recuperar dades de taules. |
| Post | Utilitzeu-lo en crear taules i cridar accions. |
| Patch | Utilitzeu-ho quan actualitzeu taules o feu operacions upsert. |
| Delete | Utilitzeu-ho per suprimir taules o propietats individuals de les taules. |
| Put | Utilitzeu-ho en situacions limitades per actualitzar les propietats individuals de taules. |
Capçaleres HTTP
L'API web només admet JSON. Cada capçalera HTTP ha d'incloure:
- Un valor de capçalera per a Accept application/json, encara que no s'esperi cap cos 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 ha ambigüitat sobre la versió OData que s'aplicarà al vostre 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: recupera les dades de la 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 inclouen el següent:
| 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
Considerem el següent exemple de resposta HTTP que 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 portalsEls portals escriuen, actualitzen i suprimeixen operacions mitjançant l'API webPortals llegeixen operacions utilitzant l'API web