Partajați prin

Compuneți cereri HTTP și gestionați erorile pentru portalurile web API

  • Articol

Interacțiunea cu API-ul web include compunerea de cereri HTTP cu anteturile necesare și gestionarea răspunsurilor HTTP, inclusiv eventualele erori.

Important

  • Versiunea portalului dvs. trebuie să fie 9.3.3.x sau mai recentă pentru ca această caracteristică să funcționeze.

URL API web și gestionare versiune

Construiți URL-ul API-ului Web utilizând formatul din tabelul următor.

Parte Descriere
Protocol https://
URL de bază <URL portal>
Calea API-ului web _api
Resursă Nume logic al tabelului pe care doriți să-l utilizați

De exemplu, utilizați acest format când faceți referire la un caz:

https://contoso.powerappsportals.com/_api/case

Toate resursele API web vor urma respectivele permisiuni ale tabelului în context cu rolurile web.

Metode HTTP

Cererile HTTP pot utiliza diferite tipuri de metode. Cu toate acestea, portalurile Web API acceptă doar metodele din tabelul următor:

Metodă Utilizare
Obțineți Utilizați la preluarea datelor din tabele.
Postați Utilizați când creați înregistrări.
Patch Se folosește la actualizarea tabelelor sau la efectuarea operațiunilor de upsert.
Delete Utilizați atunci când ștergeți înregistrări sau valorile câmpurilor individuale ale înregistrărilor.
Put Utilizați în situații limitate pentru a actualiza câmpurile individuale ale înregistrărilor.

Anteturi HTTP

API-ul Web acceptă numai JSON. Fiecare antet HTTP trebuie să includă:

  • O valoare de antet Accept pentru application/json, chiar și atunci când nu se așteaptă un organism de răspuns.
  • Dacă solicitarea include date JSON în corpul de solicitare, trebuie să includeți un antet Tip de conținut cu o valoareapplication/json.

Versiunea actuală OData este 4.0, dar versiunile viitoare ar putea permite noi capabilități. Utilizați următoarea sintaxă pentru a vă asigura că nu există nicio ambiguitate cu privire la versiunea OData care va fi aplicată codului dvs. în viitor.

Sintaxă

Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

Exemplu: Funcția Wrapper AJAX pentru tokenul 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)

Exemplu: Extrageți date de tabel

	webapi.safeAjax({
				type: "GET",
				url: "/_api/contacts?$select=firstname,lastname",
				contentType: "application/json",
				success: function (res) {
						console.log(res);
				}
	});

Exemplu: Creați date de tabel

	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"))
		}
	});

Exemplu: Actualizați date de tabel

		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);
		}
	});

Exemplu: Ștergeți date de tabel

		webapi.safeAjax({
		type: "DELETE",
		url: "/_api/accounts(00000000-0000-0000-0000-000000000001)",
		contentType: "application/json",
		success: function (res) {
			console.log(res);
		}
	});

Identificați codurile de stare

Fiecare răspuns de solicitare HTTP include un cod de stare. Codurile de stare returnate de portalurile API web includ următoarele:

Cod Descriere Tipul
200 OK Așteptați-vă la acest răspuns atunci când operațiunea dvs. va returna date în corpul de răspuns. Succes
204 Niciun conținut Așteptați-vă la acest răspuns atunci când operațiunea dvs. reușește, dar nu va returna date în corpul de răspuns. Succes
403 Interzis Așteptați acest răspuns pentru următoarele tipuri de erori:
  • AccessDenied
  • AttributePermissionIsMissing
  • TablePermissionWriteIsMissingDuringUpdate
  • TablePermissionCreateIsMissing
  • TablePermissionDeleteIsMissing
  • TablePermissionAppendIsMissngDuringAssociationChange
  • TablePermissionAppendToIsMissingDuringAssociateChange
 Eroare client
401 Neautorizat Așteptați acest răspuns pentru următoarele tipuri de erori:
  • MissingPortalRequestVerificationToken
  • MissingPortalSessionCookie
 Eroare client
413 Sarcină prea mare Așteptați acest răspuns atunci când lungimea cererii este prea mare. Eroare client
400 BadRequest Așteptați acest răspuns atunci când un argument este nevalid.
InvalidAttribute		 Eroare client
404 Nu a fost găsit Așteptați-vă la acest răspuns atunci când resursa nu există.
Tabelul nu este expus pentru API-ul web.		 Eroare client
405 Comandă nepermisă Această eroare apare pentru combinații de metode și resurse incorecte. De exemplu, nu puteți utiliza DELETE sau PATCH pe o colecție de tabele. Această situație poată apărea pentru următoarele tipuri de erori:
  • InvalidOperation
  • NotSupported
 Eroare client
500 Neimplementat Așteptați-vă la acest răspuns când unele operațiuni solicitate nu sunt implementate. Eroare de server
503 Serviciu indisponibil Așteptați-vă la acest răspuns atunci când serviciul API Web nu este disponibil. Eroare de server

Analizați erorile din răspuns

Luați în considerare următorul exemplu de răspuns HTTP care include încă eroarea 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.."
      }
    }
  }

Coduri de eroare

Codurile de eroare sunt afișate în format hexazecimal pentru toate scenariile gestionate. Următorul tabel listează fiecare cod de eroare cu numele și mesajul respectiv.

Cod de eroare Nume eroare Mesaj de eroare
900400FF NoAttributesForTableCreate Nu există atribute pentru acțiunea Creare tabel.
90040100 InvalidAttribute Nu s-a găsit atributul {0} pentru tabelul {1}.
90040101 AttributePermissionIsMissing Atributul {0} din tabelul {1} nu este activat pentru API-ul web.
90040102 TablePermissionWriteIsMissingDuringUpdate Nu aveți permisiunea de a actualiza entitatea {0}.
90040103 TablePermissionCreateIsMissing Nu aveți permisiunea de a crea entitatea {0}.
90040104 TablePermissionDeleteIsMissing Nu aveți permisiunea de a șterge entitatea {0).
90040105 TablePermissionAppendIsMissngDuringAssociationChange Nu aveți permisiunea de a asocia sau de a anula asocierea tabelului {0} cu {1}.
90040106 TablePermissionAppendToIsMissingDuringAssociationChange Nu aveți permisiunea de a asocia sau de a anula asocierea tabelului {1} la {0}
90040107 HttpAntiForgeryException Tokenul cookie anti-falsificare și tokenul câmp de formular nu se potrivesc.
90040109 MissingPortalSessionCookie Un token de sesiune nevalid a fost trecut în metoda de lansare.
9004010C ResourceDoesNotExists Resursă negăsită pentru segmentul „{0}”.
9004010D CDSError A avut loc o eroare CDS.

Răspunsul pentru erorile negestionate cu codul de stare HTTP 500 va returna eroarea „A apărut o eroare neașteptată în timpul procesării cererii.”

Consultați și