Sdílet prostřednictvím

Vytvořte požadavky HTTP a zpracujte chyby pro webové rozhraní API portálů

  • Článek

Interakce s webovým rozhraním API zahrnuje vytváření požadavků HTTP s požadovanými záhlavími a zpracovávání odpovědí HTTP, včetně veškerých chyb.

Důležité

  • Aby tato funkce fungovala, musí být vaše verze portálu 9.3.3.x nebo novější.

Adresa URL webového rozhraní API a správa verzí

Vytvořte adresu URL webového rozhraní API pomocí formátu v následující tabulce.

Část Description
Protokol https://
Základní adresa URL <URL portálu>
Cesta webového rozhraní API _api
Resource Logický název tabulky, kterou chcete použít

Například použijte tento formát, když odkazujete na případ:

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

Všechny prostředky webového rozhraní API se budou řídit příslušnými oprávněními tabulky v kontextu s webovými rolemi.

Metody HTTP

Požadavky HTTP mohou používat různé druhy metod. Webová rozhraní API portálů však podporuji pouze metody v následující tabulce:

metoda Využití
Získat Použijte při načítání dat z tabulek.
Zveřejnit Použijte při vytváření záznamů.
Oprava Použijte při aktualizaci tabulek nebo při operacích upsert.
Odstranění Použijte při odstraňování záznamů nebo jednotlivých hodnot polí záznamů.
Put Použijte v omezených situacích k aktualizaci jednotlivých polí záznamů.

Záhlaví HTTP

Webové rozhraní API podporuje pouze JSON. Každé záhlaví HTTP musí obsahovat:

  • Hodnota záhlaví Přijmout typu application/json, i když se neočekává žádné tělo odpovědi.
  • Pokud text požadavku obsahuje data JSON, musíte zahrnout záhlaví Content-Type s hodnotouapplication/json.

Aktuální verze OData je 4.0, ale budoucí verze mohou umožňovat nové funkce. Použijte následující syntaxi, abyste zajistili, že nebudou žádné nejasnosti ohledně verze OData, která bude v budoucnu použita na váš kód:

Syntaxe

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

Příklad: Obálková funkce AJAX pro 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)

Příklad: Načtení dat tabulky

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

Příklad: Vytvoření dat tabulky

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

Příklad: Aktualizace dat tabulky

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

Příklad: Odstranění dat tabulky

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

Vysvětlení stavových kódů

Každá odpověď na požadavek HTTP obsahuje stavový kód. Stavové kódy vrácené webovým rozhraním API portálů zahrnují následující:

Kód Description Type
200 OK Očekávejte tuto odpověď, když vaše operace vrátí data v textu odpovědi. Úspěch
204 Chybí obsah Očekávejte tuto odpověď, když vaše operace uspěje, ale nevrátí data v textu odpovědi. Úspěch
403 Zakázáno Očekávejte tuto odpověď u následujících typů chyb:
  • AccessDenied
  • AttributePermissionIsMissing
  • TablePermissionWriteIsMissingDuringUpdate
  • TablePermissionCreateIsMissing
  • TablePermissionDeleteIsMissing
  • TablePermissionAppendIsMissngDuringAssociationChange
  • TablePermissionAppendToIsMissingDuringAssociateChange
 Chyba klienta
401 Neautorizováno Očekávejte tuto odpověď u následujících typů chyb:
  • MissingPortalRequestVerificationToken
  • MissingPortalSessionCookie
 Chyba klienta
413 Příliš velká datová část Tuto odpověď očekávejte, pokud je délka požadavku příliš velká. Chyba klienta
400 Nepsrávný požadavek Pokud je argument neplatný, očekávejte tuto odpověď.
InvalidAttribute		 Chyba klienta
404 Nenalezeno Pokud zdroj neexistuje, očekávejte tuto odpověď.
Tabulka není vystavena pro webové rozhraní API.		 Chyba klienta
405 Nepovolená metoda K této chybě dochází při nesprávné kombinaci metod a prostředků. Například nemůžete použít DELETE nebo PATCH na kolekci tabulek. Tato situace může nastat u následujících typů chyb:
  • InvalidOperation
  • NotSupported
 Chyba klienta
501 Není implementováno Tuto odpověď očekávejte, pokud není implementována požadovaná operace. Chyba serveru
503 Nedostupná služba Tuto odpověď očekávejte, když služba webového rozhraní API není k dispozici. Chyba serveru

Analýza chyb z odpovědi

Zvažte následující příklad odpovědi HTTP, která stále obsahuje vnitřní chybu:

{
  "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.."
      }
    }
  }

Kódy chyb

Kódy chyb jsou zobrazeny v hexadecimálním formátu pro všechny zpracované scénáře. V následující tabulce je uveden každý chybový kód s příslušným názvem a zprávou.

Kód chyby Název chyby Chybová zpráva
900400FF NoAttributesForTableCreate Žádné atributy pro akci Vytvořit tabulku
90040100 InvalidAttribute Atribut {0} tabulky {1} nelze najít.
90040101 AttributePermissionIsMissing Atribut {0} v tabulce {1} nemá povolené webové rozhraní API.
90040102 TablePermissionWriteIsMissingDuringUpdate Nemáte oprávnění k aktualizaci entity {0}.
90040103 TablePermissionCreateIsMissing Nemáte oprávnění k vytvoření entity {0}.
90040104 TablePermissionDeleteIsMissing Nemáte oprávnění k odstranění entity {0).
90040105 TablePermissionAppendIsMissngDuringAssociationChange Nemáte oprávnění k přidružení nebo zrušení přidružení tabulky {0} s {1}.
90040106 TablePermissionAppendToIsMissingDuringAssociationChange Nemáte oprávnění k přidružení nebo zrušení přidružení tabulky {1} k {0}.
90040107 HttpAntiForgeryException Token souboru cookie proti padělání a token pole formuláře se neshodují.
90040109 MissingPortalSessionCookie Do metody, která vyvolala chybu, byl předán neplatný token relace.
9004010C ResourceDoesNotExists Pro segment {0} nebyl nalezen zdroj.
9004010D CDSError Došlo k chybě CDS.

Odpověď na neošetřené chyby se stavovým kódem HTTP 500 vrátí chybu „Při zpracování požadavku došlo k neočekávané chybě“.

Viz také