Kongsi melalui

Tulis permintaan HTTP dan kendalikan ralat untuk portal API Web

  • Artikel

Berinteraksi dengan API Web termasuk mengarang permintaan HTTP dengan pengepala yang diperlukan dan mengendalikan respons HTTP, termasuk sebarang ralat.

Penting

  • Versi portal anda mesti 9.3.3.x atau kemudian untuk ciri ini berfungsi.

URL API Web dan pemversian

Membina URL API Web dengan menggunakan format dalam jadual berikut.

Sebahagian Penerangan
Protokol https://
URL Asas <URL portal>
Laluan API Web _api
Sumber Nama logik jadual yang mahu anda gunakan

Contohnya, gunakan format ini apabila merujuk kes:

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

Semua sumber API Web akan mengikut keizinan jadual berkenaan, dalam konteks dengan peranan web.

Kaedah HTTP

Permintaan HTTP boleh menggunakan jenis kaedah yang berbeza. Walau bagaimanapun, API Web portal hanya menyokong kaedah dalam jadual berikut:

Kaedah Penggunaan
Dapat Gunakan apabila mendapatkan semula data daripada jadual.
Post Gunakan semasa mencipta rekod.
Patch Gunakan apabila mengemas kini jadual atau lakukan operasi upsert.
Delete Gunakan apabila memadamkan rekod atau nilai medan individu bagi rekod.
Put Gunakan dalam situasi terhad untuk mengemas kini medan rekod individu.

Pengepala HTTP

API Web hanya menyokong JSON. Setiap pengepala HTML mesti mengandungi:

  • Nilai pengepala Terima bagi aplikasi/json, walaupun apabila tiada isi respons dijangkakan.
  • Jika permintaan termasuk data JSON dalam isi permintaan, anda mesti menyertakan pengepala Jenis-Kandungan dengan nilai bagi application/json.

Versi OData semasa ialah 4.0 tetapi versi akan datang mungkin membenarkan keupayaan baharu. Gunakan sintaks berikut untuk memastikan bahawa tidak ada kekaburan tentang versi OData yang akan diguna pakai pada kod anda pada masa akan datang:

Sintaks

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

Contoh: Pembalut AJAX berfungsi untuk 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)

Contoh: Dapatkan semula data jadual

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

Contoh: Cipta data jadual

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

Contoh: Kemas kini data jadual

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

Contoh: Padamkan data jadual

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

Kenal pasti kod status

Setiap respons permintaan HTTP mengandungi kod status. Kod status yang dikembalikan oleh API Web portal termasuk yang berikut:

Kod Penerangan Taip
200 OK Respons ini dijangkakan apabila operasi anda akan mengembalikan data dalam isi respons. Kejayaan
204 Tiada Kandungan Respons ini dijangkakan apabila operasi anda berjaya tetapi tidak mengembalikan data dalam isi respons. Kejayaan
403 Dilarang Respons ini dijangkakan untuk jenis ralat yang berikut:
  • AccessDenied
  • AttributePermissionIsMissing
  • TablePermissionWriteIsMissingDuringUpdate
  • TablePermissionCreateIsMissing
  • TablePermissionDeleteIsMissing
  • TablePermissionAppendIsMissngDuringAssociationChange
  • TablePermissionAppendToIsMissingDuringAssociateChange
 Ralat klien
401 Tidak Dibenarkan Respons ini dijangkakan untuk jenis ralat yang berikut:
  • MissingPortalRequestVerificationToken
  • MissingPortalSessionCookie
 Ralat klien
413 Muat Beban Terlalu Besar Respons ini dijangkakan apabila panjang permintaan terlalu besar. Ralat klien
400 Permintaan Teruk Respons ini dijangkakan apabila argumen adalah tidak sah.
InvalidAttribute		 Ralat klien
404 Tidak Ditemui Respons ini dijangkakan apabila sumber tidak wujud.
Jadual tidak didedahkan untuk API web.		 Ralat Klien
405 Kaedah Tidak Dibenarkan Ralat ini berlaku untuk kaedah dan gabungan sumber yang tidak betul. Contohnya, anda tidak boleh menggunakan PADAM atau TAMPAL pada koleksi jadual. Situasi ini boleh berlaku untuk jenis ralat yang berikut:
  • InvalidOperation
  • NotSupported
 Ralat klien
501 Tidak Dilaksanakan Respons ini dijangkakan apabila beberapa operasi yang diminta tidak dilaksanakan. Ralat pelayan
503 Perkhidmatan Tidak Tersedia Respons ini dijangkakan apabila perkhidmatan API Web tidak tersedia. Ralat pelayan

Huraikan ralat daripada respons

Pertimbangkan respons HTTP contoh berikut yang masih mengandungi ralat dalaman:

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

Kod ralat

Kod ralat dipaparkan dalam format perenambelasan untuk semua senario yang dikendalikan. Jadual berikut menyenaraikan setiap kod ralat dengan nama dan mesej masing-masing.

Kod ralat Nama ralat Mesej ralat
900400FF NoAttributesForTableCreate Tiada atribut untuk tindakan Cipta Jadual.
90040100 InvalidAttribute Atribut {0} tidak ditemui untuk jadual {1}.
90040101 AttributePermissionIsMissing Atribut {0} dalam jadual {1} tidak didayakan untuk Api Web.
90040102 TablePermissionWriteIsMissingDuringUpdate Anda tidak mempunyai keizinan untuk mengemas kini entiti {0}.
90040103 TablePermissionCreateIsMissing Anda tidak mempunyai keizinan untuk mencipta entiti {0} .
90040104 TablePermissionDeleteIsMissing Anda tidak mempunyai keizinan untuk memadamkan entiti {0).
90040105 TablePermissionAppendIsMissngDuringAssociationChange Anda tidak mempunyai keizinan untuk mengaitkan atau menyahkaitkan jadual {0} dengan {1}.
90040106 TablePermissionAppendToIsMissingDuringAssociationChange Anda tidak mempunyai keizinan untuk mengaitkan atau menyahkaitkan jadual {1} kepada {0}
90040107 HttpAntiForgeryException Token kuki antipemalsuan dan token medan borang tidak sepadan.
90040109 MissingPortalSessionCookie Token sesi yang tidak sah telah diserahkan ke dalam kaedah lontaran.
9004010C ResourceDoesNotExists Sumber tidak ditemui untuk segmen '{0}'.
9004010D CDSError Ralat CDS telah berlaku.

Respons untuk ralat yang tidak dikendalikan dengan kod status HTTP 500 akan mengembalikan ralat "Ralat yang tidak dijangkakan telah berlaku ketika memproses permintaan."

Lihat juga