Κοινή χρήση μέσω

Σύνταξη αιτήσεων HTTP και χειρισμός σφαλμάτων για το API Web πυλών

  • Άρθρο

Η αλληλεπίδραση με το Web API περιλαμβάνει τη σύνθεση αιτήσεων HTTP με απαιτούμενες κεφαλίδες και χειρισμό αποκρίσεων HTTP, συμπεριλαμβανομένων τυχόν σφαλμάτων.

Σημαντικό

  • Η έκδοση της πύλης σας πρέπει να είναι 9.3.3.x ή μεταγενέστερη προκειμένου να λειτουργεί αυτή η δυνατότητα

Διεύθυνση URL και τήρηση ιστορικού εκδόσεων Web API

Δημιουργήστε τη διεύθυνση URL του Web API χρησιμοποιώντας τη μορφή στον πίνακα που ακολουθεί.

Μέρος Description
Πρωτόκολλο https://
Διεύθυνση URL βάσης <διεύθυνση URL πύλης>
Διαδρομή Web API _api
Πόρο Λογικό όνομα του πίνακα που θέλετε να χρησιμοποιήσετε

Για παράδειγμα, χρησιμοποιήστε αυτήν τη μορφή όταν αναφέρεστε σε ένα κρούσμα:

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

Όλοι οι πόροι API Web θα ακολουθήσουν τα αντίστοιχα δικαιώματα του πίνακα στο περιβάλλον με τους ρόλους Web.

Μέθοδοι HTTP

Οι αιτήσεις HTTP μπορούν να χρησιμοποιήσουν διαφορετικούς τύπους μεθόδων. Ωστόσο, το Web API πυλών υποστηρίζει μόνο τις μεθόδους που περιλαμβάνονται στον ακόλουθο πίνακα:

Μέθοδος Χρήση
Λήψη Χρήση κατά την ανάκτηση δεδομένων από πίνακες.
Δημοσίευση Χρήση κατά τη δημιουργία καρτελών.
Ενημέρωση κώδικα Χρήση κατά την ενημέρωση πινάκων ή κατά την εκτέλεση λειτουργιών upsert.
Delete Χρήση κατά τη διαγραφή καρτελών ή μεμονωμένων τιμών πεδίων καρτελών.
Put Χρήση σε περιορισμένες περιπτώσεις για την ενημέρωση μεμονωμένων πεδίων καρτελών.

Κεφαλίδες HTTP

Το Web API υποστηρίζει μόνο JSON. Κάθε κεφαλίδα HTTP πρέπει να περιλαμβάνει τα εξής:

  • Μια τιμή κεφαλίδας Αποδοχή της εφαρμογής/JSON, ακόμα και όταν δεν αναμένεται σώμα απόκρισης.
  • Εάν η αίτηση περιλαμβάνει δεδομένα JSON στο σώμα της αίτησης, θα πρέπει να συμπεριλάβετε μια κεφαλίδα Τύπου περιεχομένου με την τιμήapplication/json.

Η τρέχουσα έκδοση OData είναι 4,0, αλλά οι μελλοντικές εκδόσεις μπορεί να επιτρέπουν νέες δυνατότητες. Χρησιμοποιήστε την παρακάτω σύνταξη για να εξασφαλίσετε ότι δεν υπάρχουν αμφιβολίες σχετικά με την έκδοση OData που θα εφαρμοστεί στον κώδικά σας στο μέλλον:

Σύνταξη

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

Παράδειγμα: Πρόγραμμα περιτύλιξης συνάρτησης AJAX για το διακριτικό 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)

Παράδειγμα: Ανάκτηση δεδομένων πίνακα

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

Παράδειγμα: Δημιουργία δεδομένων πίνακα

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

Παράδειγμα: Ενημέρωση δεδομένων πίνακα

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

Παράδειγμα: Διαγραφή δεδομένων πίνακα

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

Προσδιορισμός κωδικών κατάστασης

Κάθε απόκριση αίτησης HTTP περιλαμβάνει έναν κωδικό κατάστασης. Οι κωδικοί κατάστασης που επιστρέφονται από το Web API πυλών περιλαμβάνουν τα εξής:

Κωδικός Description Type
200 OK Αναμείνετε αυτήν την απόκριση όταν η λειτουργία σας θα επιστρέψει δεδομένα στο σώμα απόκρισης. Επιτυχία
204 Χωρίς περιεχόμενο Αναμείνετε αυτήν την απόκριση όταν η λειτουργία σας πετυχαίνει αλλά δεν επιστρέφει δεδομένα στο σώμα απόκρισης. Επιτυχία
403 Απαγορεύεται Αναμείνετε αυτήν την απόκριση για τους ακόλουθους τύπους σφαλμάτων:
  • AccessDenied
  • AttributePermissionIsMissing
  • TablePermissionWriteIsMissingDuringUpdate
  • TablePermissionCreateIsMissing
  • TablePermissionDeleteIsMissing
  • TablePermissionAppendIsMissngDuringAssociationChange
  • TablePermissionAppendToIsMissingDuringAssociateChange
 Σφάλμα πελάτη
401 Χωρίς εξουσιοδότηση Αναμείνετε αυτήν την απόκριση για τους ακόλουθους τύπους σφαλμάτων:
  • MissingPortalRequestVerificationToken
  • MissingPortalSessionCookie
 Σφάλμα πελάτη
413 Το ωφέλιμο φορτίο είναι υπερβολικά μεγάλο Αναμείνετε αυτήν την απόκριση όταν το μήκος της αίτησης είναι πολύ μεγάλο. Σφάλμα πελάτη
400 BadRequest Αναμείνετε αυτήν την απόκριση όταν ένα όρισμα δεν είναι έγκυρο.
InvalidAttribute		 Σφάλμα πελάτη
404 Δεν βρέθηκε Αναμείνετε αυτήν την απόκριση όταν ο πόρος δεν υπάρχει.
Ο πίνακας δεν εκτίθεται για το API Web.		 Σφάλμα πελάτη
405 Η μέθοδος δεν επιτρέπεται Αυτό το σφάλμα προκύπτει για εσφαλμένους συνδυασμούς μεθόδου και πόρων. Για παράδειγμα, δεν μπορείτε να χρησιμοποιήσετε ΔΙΑΓΡΑΦΗ ή ΕΠΙΘΕΜΑ σε μια συλλογή πινάκων. Αυτή η κατάσταση μπορεί να συμβεί για τους ακόλουθους τύπους σφαλμάτων:
  • InvalidOperation
  • NotSupported
 Σφάλμα πελάτη
501 Δεν υλοποιήθηκε Αναμείνετε αυτήν την απόκριση όταν δεν έχει υλοποιηθεί κάποια ζητούμενη λειτουργία. Σφάλμα διακομιστή
503 Μη διαθέσιμη υπηρεσία Αναμείνετε αυτήν την απόκριση όταν η υπηρεσία Web API δεν είναι διαθέσιμη. Σφάλμα διακομιστή

Ανάλυση σφαλμάτων από την απόκριση

Λάβετε υπόψη σας την ακόλουθη απόκριση παράδειγμα HTTP, η οποία εξακολουθεί να περιλαμβάνει το εσωτερικό σφάλμα:

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

Κωδικοί σφαλμάτων

Οι κωδικοί σφάλματος εμφανίζονται σε δεκαεξαδική μορφή για όλα τα σενάρια χειρισμού. Στον παρακάτω πίνακα παρατίθενται κάθε κωδικός σφάλματος με το αντίστοιχο όνομα και μήνυμα.

Κωδικός σφάλματος Όνομα σφάλματος Μήνυμα σφάλματος
900400FF NoAttributesForTableCreate Δεν υπάρχουν χαρακτηριστικά για ενέργεια δημιουργίας πίνακα.
90040100 InvalidAttribute Δεν βρέθηκε {0} χαρακτηριστικού για τον πίνακα {1}.
90040101 AttributePermissionIsMissing Το χαρακτηριστικό {0} στον πίνακα {1} δεν είναι ενεργοποιημένο για το Web Api.
90040102 TablePermissionWriteIsMissingDuringUpdate Δεν έχετε δικαίωμα ενημέρωσης οντότητας {0}.
90040103 TablePermissionCreateIsMissing Δεν έχετε δικαίωμα δημιουργίας οντότητας {0}.
90040104 TablePermissionDeleteIsMissing Δεν έχετε δικαίωμα διαγραφής οντότητας {0).
90040105 TablePermissionAppendIsMissngDuringAssociationChange Δεν έχετε δικαίωμα συσχέτισης ή μη συσχέτισης του πίνακα {0} με το {1}.
90040106 TablePermissionAppendToIsMissingDuringAssociationChange Δεν έχετε δικαίωμα συσχέτισης ή μη συσχέτισης του πίνακα {1} σε {0}
90040107 HttpAntiForgeryException Το διακριτικό cookie κατά της πλαστογράφησης και το διακριτικό πεδίου φόρμας δεν συμφωνούν.
90040109 MissingPortalSessionCookie Διαβιβάστηκε ένα διακριτικό περιόδου λειτουργίας που δεν είναι έγκυρο στη μέθοδο ρίψης.
9004010C ResourceDoesNotExists Ο πόρος δεν βρέθηκε για το τμήμα "{0}".
9004010D CDSError Παρουσιάστηκε σφάλμα CDS.

Η απόκριση για ανεπίλυτα σφάλματα με κωδικό κατάστασης HTTP 500 θα επιστρέψει το σφάλμα - Παρουσιάστηκε ένα μη αναμενόμενο σφάλμα κατά την επεξεργασία της αίτησης.

Δείτε επίσης