Del via

Oprette HTTP-forespørgsler og håndtere fejl i portalweb-API'en

  • Artikel

Interaktion med Web-API omfatter oprettelse af HTTP-anmodninger med påkrævede headere og håndtering af HTTP-svar, herunder eventuelle fejl.

Vigtigt

  • Din portalversion skal være 9.3.3.x eller nyere, for at denne funktion kan fungere.

URL-adressen til Web-API og versioner

Opret web-API'ens URL-adresse ved hjælp af formatet i følgende tabel.

Del Description
Protokol https://
Basiswebadresse <portal URL>
Sti til Web-API _api
Ressource Logisk navn på den tabel, du vil bruge

Du kan f.eks. bruge dette format, når du refererer til en sag:

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

Alle web-API-ressourcer følger de respektive tabeltilladelser i forbindelse med webroller.

HTTP-metoder

HTTP-anmodninger kan bruge forskellige typer metoder. Web-API'en til portaler understøtter dog kun metoderne i følgende tabel:

Method Brug
Hent Brug den, når du henter data fra tabeller.
Slå op Brug under oprettelse af poster.
Programrettelse Bruges, når du opdaterer tabeller eller udfører upsert-handlinger.
Delete Bruges, når du sletter poster eller individuelle feltværdier for poster.
Put Bruges i få situationer til opdatering af individuelle postfelter.

HTTP-overskrifter

Web-API'en understøtter kun JSON. De enkelte HTTP-headere skal indeholde:

  • Værdien application/json for en header af typen Accept, også selvom der ikke forventes et svar.
  • Hvis anmodningen omfatter JSON-data i anmodningsteksten, skal du inkludere en Content-Type-header med en application/json-værdi.

Den aktuelle OData-version er 4.0, men fremtidige versioner kan indeholde ny funktionalitet. Brug følgende syntaks for at sikre, at der ikke er nogen tvivl om den OData-version, der vil blive anvendt på din kode i fremtiden:

Syntaks

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

Eksempel: Wrapper AJAX-funktion for CSRF-tokenet

	(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)

Eksempel: Hent tabeldata

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

Eksempel: Opret tabeldata

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

Eksempel: Opdater tabeldata

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

Eksempel: Slet tabeldata

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

Identificere statuskoder

Hvert HTTP-anmodningssvar inkluderer en statuskode. Statuskoder, som returneres af portalers Web-API, omfatter følgende:

Kode Description Skriv
200 OK Forvent dette svar, når din handling returnerer data i svarteksten. Fuldført
204 Intet indhold Forvent dette svar, når din handling lykkes, men ikke returnerer data i svarteksten. Fuldført
403 Ikke tilladt Forvent dette svar for følgende typer af fejl:
  • AccessDenied
  • AttributePermissionIsMissing
  • TablePermissionWriteIsMissingDuringUpdate
  • TablePermissionCreateIsMissing
  • TablePermissionDeleteIsMissing
  • TablePermissionAppendIsMissngDuringAssociationChange
  • TablePermissionAppendToIsMissingDuringAssociateChange
 Klientfejl
401 Uautoriseret Forvent dette svar for følgende typer af fejl:
  • MissingPortalRequestVerificationToken
  • MissingPortalSessionCookie
 Klientfejl
413 Nyttedata er for store Forvent dette svar, når længden på anmodningen er for stor. Klientfejl
400 BadRequest Forvent dette svar, når et argument er ugyldigt.
InvalidAttribute		 Klientfejl
404 Blev ikke fundet Forvent denne ressource, når ressourcen ikke findes.
Tabellen vises ikke for web-API'en.		 Klientfejl
405 Metoden er ikke tilladt Denne fejl opstår ved forkerte metode- og ressourcekombinationer. For eksempel kan du ikke bruge DELETE eller PATCH på en samling af tabeller. Denne situation kan opstå for følgende typer af fejl:
  • InvalidOperation
  • NotSupported
 Klientfejl
501 Ikke implementeret Forvent dette svar, når der er anmodet om en handling, som ikke er blevet implementeret. Serverfejl
503 Service er ikke tilgængelig Forvent dette svar, når web-API-tjenesten ikke er tilgængelig. Serverfejl

Fejlmeddelelse fra svaret under opdeling af tekst

Overvej følgende HTTP-eksempelsvar, der stadig inkluderer den indre fejl:

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

Fejlkoder

Fejlkoder vises i hexadecimalt format for alle håndterede scenarier. I følgende tabel vises de enkelte fejlkoder med de respektive navne og meddelelser.

Fejlkode Fejlnavn Fejlmeddelelse
900400FF NoAttributesForTableCreate Der er ingen attributter for handlingen Opret tabel.
90040100 InvalidAttribute Attributten {0} blev ikke fundet for tabellen {1}.
90040101 AttributePermissionIsMissing Attributten {0} i tabellen {1} er ikke aktiveret til Web-API.
90040102 TablePermissionWriteIsMissingDuringUpdate Du har ikke tilladelse til at opdatere objektet {0}.
90040103 TablePermissionCreateIsMissing Du har ikke tilladelse til at oprette objektet {0}.
90040104 TablePermissionDeleteIsMissing Du har ikke tilladelse til at slette objektet {0).
90040105 TablePermissionAppendIsMissngDuringAssociationChange Du har ikke tilladelse til at tilknytte eller fjerne tilknytningen af tabellen {0} med {1}.
90040106 TablePermissionAppendToIsMissingDuringAssociationChange Du har ikke tilladelse til at tilknytte eller fjerne tilknytningen af tabellen {1} med {0}.
90040107 HttpAntiForgeryException Cookie-tokenet til anti-svindel og formularfeltets token matcher ikke.
90040109 MissingPortalSessionCookie Der blev overført et ugyldigt sessionstoken til den kaldende metode.
9004010C ResourceDoesNotExists Ressourcen blev ikke fundet for segmentet '{0}'.
9004010D CDSError Der opstod CDS-fejl.

Svar på ikke-håndterede fejl med HTTP-statuskode 500 returnerer fejlen "Der opstod en uventet fejl under behandling af anmodningen".

Se også