Rédiger des requêtes HTTP et gérer les erreurs pour l’API Web des portails

L’interaction avec l’API Web comprend la composition de requêtes HTTP avec les en-têtes requis et la gestion des réponses HTTP, y compris les erreurs.

URL et versions d’API Web

Construisez l’URL de l’API web en utilisant le format du tableau suivant.

Par exemple, utilisez ce format lorsque vous référez un cas :

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

Toutes les ressources de l’API Web suivront les autorisations de table dans le contexte des rôles Web.

Méthodes HTTP

Les requêtes HTTP peuvent utiliser différents types de méthodes. Cependant, l’API web des portails ne prend en charge que les méthodes du tableau suivant :

En-têtes HTTP

L’API web prend uniquement en charge JSON. Chaque en-tête HTTP doit inclure :

• Une valeur d’en-tête Accept deapplication/json, même lorsqu’aucun corps de réponse n’est prévu.
• Si le corps de la demande inclut des données JSON, vous devez inclure un en-tête Content-Type contenant une valeurapplication/json.

La version OData actuelle est la 4.0, mais les futures versions pourraient autoriser de nouvelles fonctionnalités. Utilisez la syntaxe suivante pour vous assurer qu’il n’y a aucune ambiguïté sur la version OData qui sera appliquée à votre code à l’avenir :

Syntaxe

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

Exemple : fonction Wrapper AJAX pour le jeton 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 : récupérer les données d’un tableau

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

Exemple : Créer des données de table

	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 : mettre à jour des données de table

		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 : Supprimer des données de table

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

Identifier les codes de statut

Chaque réponse de requête HTTP comprend un code de statut. Les codes de statut sont renvoyés par l’API Web des portails avec ce qui suit :

Analyse des erreurs relatives à la réponse

Considérez l’exemple de réponse HTTP suivant qui inclut toujours l’erreur interne :

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

Codes d’erreur

Les codes d’erreur sont affichés au format hexadécimal pour tous les scénarios traités. Le tableau suivant répertorie chaque code d’erreur avec son nom et son message respectifs.

La réponse aux erreurs non traitées avec le code d’état HTTP 500 renvoie l’erreur suivante : « Une erreur inattendue s’est produite lors du traitement de la demande ».

Voir aussi

• Vue d’ensemble de l’API Web
• Opérations d’écriture, de mise à jour et de suppression à l’aide de l’API Web
• Les portails lisent les opérations à l’aide de l’API Web