Catatan
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba masuk atau mengubah direktori.
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba mengubah direktori.
Berinteraksi dengan web API mencakup penyusunan permintaan HTTP dengan header yang diperlukan dan menangani respons HTTP, termasuk kesalahan.
Penting
- Versi portal Anda harus 9.3.3.x atau lebih baru agar fitur ini berfungsi.
URL dan versi web API
Buat URL API web menggunakan format dalam tabel berikut.
| Bagian | Deskripsi |
|---|---|
| Protokol | https:// |
| URL Dasar | <URL portal> |
| Jalur API web | _api |
| Sumber info | Nama logis tabel yang ingin digunakan |
Misalnya, gunakan format ini saat merujuk kasus:
https://contoso.powerappsportals.com/_api/case
Semua sumber daya Web API akan mengikuti izin tabel masing-masing dalam konteks dengan Peran Web.
metode HTTP
Permintaan HTTP dapat menggunakan berbagai jenis metode. Namun, API web portal hanya mendukung metode dalam tabel berikut:
| Metode | Penggunaan |
|---|---|
| Dapatkan | Gunakan saat mengambil data dari tabel. |
| Post | Gunakan ketika membuat rekaman. |
| Patch | Gunakan saat memperbarui tabel atau melakukan operasi upsert. |
| Delete | Gunakan saat menghapus rekaman atau nilai bidang rekaman individual. |
| Put | Gunakan dalam situasi terbatas untuk memperbarui bidang rekaman. |
Header HTTP
Api Web hanya mendukung JSON. Setiap header HTTP harus mencakup:
- Nilai header Terima dari aplikasi/json, meskipun tidak ada isi respons yang diharapkan.
- Jika permintaan menyertakan data JSON dalam badan permintaan, Anda harus menyertakan header Content-Type dengan nilai
application/json.
Versi OData saat ini adalah 4.0, namun versi mendatang mungkin memungkinkan kemampuan baru. Gunakan sintaks berikut untuk memastikan tidak ada ambiguitas tentang versi OData yang akan diterapkan ke kode Anda di masa mendatang:
Sintaks
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
Contoh: fungsi Wrapper AJAX 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: Ambil data tabel
webapi.safeAjax({
type: "GET",
url: "/_api/contacts?$select=firstname,lastname",
contentType: "application/json",
success: function (res) {
console.log(res);
}
});
Contoh: Membuat data tabel
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: Memperbarui data tabel
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: Menghapus data tabel
webapi.safeAjax({
type: "DELETE",
url: "/_api/accounts(00000000-0000-0000-0000-000000000001)",
contentType: "application/json",
success: function (res) {
console.log(res);
}
});
Mengidentifikasi kode status
Setiap respons permintaan HTTP mencakup kode status. Kode status yang dikembalikan oleh API web portal mencakup yang berikut:
| Kode | Deskripsi | Tipe |
|---|---|---|
| 200 OK | Tunggu respons ini saat operasi Anda akan mengembalikan data di badan respons. | Sukses |
| 204 No Content | Tunggu respons ini saat operasi Anda akan sukses, tetapi tidak mengembalikan data di badan respons. | Sukses |
| 403 Forbidden | Tunggu respons ini untuk jenis kesalahan berikut:
|
Kesalahan klien |
| 401 Tidak Sah | Tunggu respons ini untuk jenis kesalahan berikut:
|
Kesalahan klien |
| 413 Payload Too Large | Tunggu respons ini bila panjang permintaan terlalu besar. | Kesalahan klien |
| 400 BadRequest | Tunggu respons ini bila argumen tidak valid. InvalidAttribute |
Kesalahan klien |
| 404 Not Found | Tunggu respons ini saat sumber daya tidak ada. Tabel tidak diekspos untuk Web API. |
Kesalahan klien |
| 405 Method Not Allowed | Kesalahan ini terjadi karena metode dan kombinasi sumber daya yang salah. Misalnya, Anda tidak dapat menggunakan DELETE atau PATCH pada kumpulan tabel. Situasi ini dapat terjadi untuk jenis kesalahan berikut:
|
Kesalahan klien |
| 501 Not Implemented | Tunggu respons ini saat beberapa operasi yang diminta tidak diterapkan. | Kesalahan server |
| 503 Layanan Tidak Tersedia | Tunggu respons ini bila layanan API web tidak tersedia. | Kesalahan server |
Kesalahan penguraian dari respons
Pertimbangkan contoh respons HTTP berikut ini yang masih mencakup kesalahan dalam:
{
"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.."
}
}
}
Kode kesalahan
Kode kesalahan ditampilkan dalam format heksadesimal untuk semua skenario yang ditangani. Tabel berikut mencantumkan setiap kode kesalahan dengan nama dan pesannya masing-masing.
| Kode kesalahan | Nama kesalahan | Pesan kesalahan |
|---|---|---|
| 900400FF | NoAttributesForTableCreate | Tidak ada atribut untuk tindakan Buat Tabel. |
| 90040100 | InvalidAttribute | Atribut {0} tidak dapat ditemukan untuk tabel {1}. |
| 90040101 | AttributePermissionIsMissing | Atribut {0} di tabel {1} tidak diaktifkan untuk API Web. |
| 90040102 | TabelPermissionWriteIsMissingDuringUpdate | Anda tidak memiliki izin untuk memperbarui entitas {0}. |
| 90040103 | TablePermissionCreateIsMissing | Anda tidak memiliki izin untuk membuat entitas {0}. |
| 90040104 | TablePermissionDeleteIsMissing | Anda tidak memiliki izin untuk menghapus entitas {0). |
| 90040105 | TablePermissionAppendIsMissngDuringAssociationChange | Anda tidak memiliki izin untuk mengaitkan atau membatalkan kaitan tabel {0} dengan {1}. |
| 90040106 | TablePermissionAppendToIsMissingDuringAssociationChange | Anda tidak memiliki izin untuk mengaitkan atau membatalkan kaitan tabel {1} ke {0} |
| 90040107 | HttpAntiForgeryException | Token cookie anti-pemalsuan dan token bidang formulir tidak cocok. |
| 90040109 | MissingPortalSessionCookie | Token sesi tidak valid diteruskan ke metode lemparan. |
| 9004010C | ResourceDoesNotExists | Tidak ditemukan sumber daya untuk segmen '{0}'. |
| 9004010D | CDSError | Terjadi kesalahan CDS. |
Respons terhadap kesalahan yang tidak ditangani dengan kode status HTTP 500 akan menghasilkan kesalahan "kesalahan yang tidak terduga terjadi saat memproses permintaan".