แชร์ผ่าน

เขียนคำขอ HTTP และจัดการข้อผิดพลาดสำหรับพอร์ทัล API สำหรับเว็บ

  • บทความ

หมายเหตุ

พอร์ทัล Power Apps คือ Power Pages โดยมีผลในวันที่ 12 ตุลาคม 2022 ข้อมูลเพิ่มเติม: Microsoft Power Pages มีให้ใช้งานทั่วไป (บล็อก)
ในไม่ช้าเราจะย้ายและรวมคู่มือพอร์ทัล Power Apps เข้ากับ คู่มือ Power Pages

การโต้ตอบกับ Web API รวมถึงการเขียนคำขอ HTTP ที่มีส่วนหัวที่จำเป็นและการจัดการการตอบสนอง HTTP ซึ่งรวมถึงข้อผิดพลาดใด ๆ

ข้อสำคัญ

  • รุ่นพอร์ทัลของคุณต้องเป็น 9.3.3.x หรือใหม่กว่าเพื่อให้คุณลักษณะนี้ทำงานได้

URL ของ Web API และการกำหนดเวอร์ชัน

สร้าง URL ของ Web API โดยใช้รูปแบบในตารางต่อไปนี้

ส่วน รายละเอียด
โปรโตคอล https://
URL ฐาน <portal URL>
เส้นทาง Web API _api
ทรัพยากร ชื่อตรรกะของตารางที่คุณต้องการใช้

ตัวอย่างเช่น ใช้รูปแบบนี้เมื่ออ้างถึงกรณี:

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

ทรัพยากร Web API ทั้งหมดจะเป็นไปตาม สิทธิ์ตารางพอร์ทัล ที่เกี่ยวข้องในบริบทที่มีบทบาทเว็บ

วิธีการ HTTP

คำขอ HTTP สามารถใช้ชนิดของวิธีการที่แตกต่างกัน อย่างไรก็ตาม Web API ของพอร์ทัลสนับสนุนเฉพาะวิธีในตารางต่อไปนี้:

Method การใช้
ดาวน์โหลด ใช้เมื่อดึงข้อมูลจากตาราง
Post ใช้เมื่อกำลังสร้างเรกคอร์ด
โปรแกรมแก้ไข ใช้เมื่ออัปเดตตารางหรือดำเนินการ 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

ตัวอย่าง: ฟังก์ชัน Wrapper 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 ตกลง คาดหวังการตอบสนองนี้ เมื่อการดำเนินการของคุณจะส่งคืนข้อมูลในเนื้อหาคำตอบ ความสำเร็จ
204 ไม่มีเนื้อหา คาดหวังการตอบสนองนี้ เมื่อการดำเนินการของคุณสำเร็จ แต่จะไม่ส่งคืนข้อมูลในเนื้อหาคำตอบ ความสำเร็จ
403 ไม่อนุญาต คาดหวังการตอบสนองนี้สำหรับชนิดของข้อผิดพลาดต่อไปนี้:
  • AccessDenied
  • AttributePermissionIsMissing
  • TablePermissionWriteIsMissingDuringUpdate
  • TablePermissionCreateIsMissing
  • TablePermissionDeleteIsMissing
  • TablePermissionAppendIsMissngDuringAssociationChange
  • TablePermissionAppendToIsMissingDuringAssociateChange
 ข้อผิดพลาดของไคลเอ็นต์
401 ไม่ได้รับอนุญาต คาดหวังการตอบสนองนี้สำหรับชนิดของข้อผิดพลาดต่อไปนี้:
  • MissingPortalRequestVerificationToken
  • MissingPortalSessionCookie
 ข้อผิดพลาดของไคลเอ็นต์
413 ส่วนข้อมูลใหญ่เกินไป คาดหวังการตอบสนองนี้ เมื่อความยาวคำขอมีขนาดใหญ่เกินไป ข้อผิดพลาดของไคลเอ็นต์
400 BadRequest คาดหวังการตอบสนองนี้ เมื่ออาร์กิวเมนต์ไม่ถูกต้อง
InvalidAttribute		 ข้อผิดพลาดของไคลเอ็นต์
404 ไม่พบ คาดหวังการตอบสนองนี้ เมื่อไม่มีทรัพยากรอยู่
ตารางจะไม่ถูกเปิดเผยสำหรับ API สำหรับเว็บ		 ข้อผิดพลาดของไคลเอ็นต์
405 ไม่อนุญาตให้ใช้วิธีการ ข้อผิดพลาดนี้เกิดขึ้นสำหรับวิธีการที่ไม่ถูกต้องและการรวมทรัพยากร ตัวอย่างเช่น คุณไม่สามารถใช้ DELETE หรือ PATCH ในคอลเลกชันของตาราง สถานการณ์นี้สามารถเกิดขึ้นได้สำหรับชนิดของข้อผิดพลาดต่อไปนี้:
  • 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} ไม่ได้เปิดใช้งานสำหรับ API เว็บ
90040102 TablePermissionWriteIsMissingDuringUpdate คุณไม่มีสิทธิ์ในการปรับปรุงเอนทิตี {0}
90040103 TablePermissionCreateIsMissing คุณไม่มีสิทธิ์ในการสร้างเอนทิตี {0}
90040104 TablePermissionDeleteIsMissing คุณไม่มีสิทธิ์ในการลบเอนทิตี {0)
90040105 TablePermissionAppendIsMissngDuringAssociationChange คุณไม่มีสิทธิ์ในการเชื่อมโยงหรือยกเลิกการเชื่อมโยงตาราง {0} ด้วย {1}
90040106 TablePermissionAppendToIsMissingDuringAssociationChange คุณไม่มีสิทธิ์ในการเชื่อมโยงหรือยกเลิกการเชื่อมโยงตาราง {1} กับ {0}
90040107 HttpAntiForgeryException โทเค็นคุกกี้การป้องกันการปลอมแปลงและโทเค็นฟิลด์ฟอร์มไม่ตรงกัน
90040109 MissingPortalSessionCookie โทเค็นเซสชันที่ไม่ถูกต้องถูกส่งผ่านไปยังวิธีการแสดง
9004010C ResourceDoesNotExists ไม่พบทรัพยากรสำหรับเซ็กเมนต์ '{0}'
9004010D CDSError เกิดข้อผิดพลาดของ CDS

การตอบสนองสำหรับข้อผิดพลาดที่ไม่ได้จัดการกับรหัสสถานะ HTTP 500 จะส่งคืนข้อผิดพลาด "เกิดข้อผิดพลาดที่ไม่คาดคิดขณะประมวลผลคำขอ"

ดูเพิ่มเติม

ภาพรวมของ API เว็บของพอร์ทัล
พอร์ทัลเขียน, ปรับปรุง, และลบการดำเนินงานโดยใช้ Web API
พอร์ทัลอ่านการดำเนินการโดยใช้ Web API

หมายเหตุ

บอกให้เราทราบเกี่ยวกับภาษาที่คุณต้องการในคู่มือ ทำแบบสำรวจสั้นๆ (โปรดทราบว่าแบบสำรวจนี้เป็นภาษาอังกฤษ)

แบบสำรวจนี้ใช้เวลาทำประมาณเจ็ดนาที ไม่มีการเก็บข้อมูลส่วนบุคคล (คำชี้แจงสิทธิ์ส่วนบุคคล)