Tulis permintaan HTTP dan kendalikan ralat untuk portal API Web

Nota

Berkuat kuasa pada 12 Oktober 2022, portal Power Apps ialah Power Pages. Maklumat lanjut: Microsoft Power Pages kini tersedia secara umum (blog)
Kami akan memindahkan dan menggabungkan dokumentasi portal Power Apps dengan dokumentasi Power Pages tidak lama lagi.

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	Description
Protokol	https://
URL Asas	<portal URL>
Laluan API Web	_api
Sumber	Nama logik jadual yang anda ingin gunakan

Contohnya, gunakan format ini apabila merujuk kes:

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

Semua sumber API Web akan mengikut keizinan jadual portal 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	Digunakan semasa mencipta rekod.
Patch	Gunakan apabila mengemas kini jadual atau lakukan operasi upsert.
Delete	Digunakan apabila memadamkan rekod atau nilai medan individu 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	Description	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

Gambaran keseluruhan API Web portal
Portal menulis, mengemas kini dan memadam operasi menggunakan API Web
Operasi baca portal menggunakan API Web