ภาพรวม Web API ของพอร์ทัล

API เว็บของพอร์ทัลช่วยให้ประสบการณ์ผู้ใช้ที่สมบูรณ์ยิ่งขึ้นภายในไซต์ Power Pages คุณสามารถใช้ API เว็บเพื่อทำการสร้าง อ่าน ปรับปรุง และลบการดำเนินการในตาราง Microsoft Dataverse ทั้งหมดจากเว็บเพจของคุณ ตัวอย่างเช่น คุณสามารถสร้างบัญชีใหม่หรืออัปเดตผู้ติดต่อโดยไม่ต้องใช้ ฟอร์ม หรือ ฟอร์มหลายขั้นตอน โดยใช้ API เว็บของพอร์ทัล

API เว็บใช้ /_api เส้นทาง (ตัวอย่างเช่น https://yoursite.powerappsportals.com/_api/accounts) และทําตามรูปแบบ RESTful คล้ายกับ API เว็บ Dataverse

สำคัญ

  • Web API ของพอร์ทัลถูกสร้างเพื่อสร้างประสบการณ์ผู้ใช้ที่สมบูรณ์ยิ่งขึ้นภายในหน้าพอร์ทัล ไม่เหมาะสำหรับบริการของบุคคลที่สาม หรือการรวมแอปพลิเคชัน การใช้ portals Web API เพื่อรวมกับไซต์ Power Pages อื่น ๆ ไม่ได้รับการสนับสนุน
  • การดำเนินการ API เว็บของพอร์ทัลจำกัดเฉพาะตารางที่เกี่ยวข้องกับข้อมูล ตัวอย่างเช่น บัญชี ผู้ติดต่อ หรือตารางที่คุณกำหนดเอง การกําหนดค่าข้อมูลเมตาดาต้าของตารางหรือข้อมูลตารางการกำหนดค่าพอร์ทัล—ตัวอย่างเช่น การกําหนดค่าตารางพอร์ทัล เช่น adx_contentsnippet, adx_entityform, หรือ adx_entitylist—ไม่ได้รับการรองรับโดยใช้พอร์ทัล Web API สําหรับรายการทั้งหมด ดู ตารางการกําหนดค่าที่ไม่รองรับ ภายหลังในบทความนี้
  • Web API ของพอร์ทัลได้รับประโยชน์จาก การแคชฝั่งเซิร์ฟเวอร์ ดังนั้น การเรียกไปยัง Web API ในภายหลังจึงเร็วกว่าการเรียกครั้งแรก การล้างแคชฝั่งเซิร์ฟเวอร์ของพอร์ทัลจะทำให้ประสิทธิภาพลดลงชั่วคราว
  • การดำเนินการ Web API ของพอร์ทัลต้องการสิทธิ์การใช้งาน Power Pages ตัวอย่างเช่น การเรียกใช้ API เว็บโดยผู้ใช้ที่ไม่ระบุชื่อจะนับรวมในความจุผู้ใช้แบบไม่ระบุชื่อ การเรียก API สำหรับเว็บที่ทำโดยผู้ใช้ที่ได้รับการรับรองความถูกต้อง (ภายในหรือภายนอก) ไม่นับรวมในการดูเพจ แต่ต้องมีสิทธิการใช้งานความจุของผู้ใช้ที่ได้รับการรับรองความถูกต้องที่เกี่ยวข้อง สําหรับข้อมูลเพิ่มเติม โปรดดูที่ คําถามที่พบบ่อยเกี่ยวกับสิทธิ์การใช้งาน Power Pages
  • ไม่รองรับ การเรียกใช้การดําเนินการ และ ฟังก์ชัน โดยใช้พอร์ทัล Web API

การดำเนินการของ Web API

Web API ของพอร์ทัลมีความสามารถย่อยสำหรับการดำเนินการ Dataverse ที่คุณสามารถทำได้โดยใช้ API ของ Dataverse รูปแบบ API จะคล้ายกันมากที่สุดเพื่อให้เรียนรู้ได้ง่ายขึ้น

หมายเหตุ

การดำเนินการของ API เว็บคำนึงตัวพิมพ์ใหญ่-เล็ก

การดำเนินการของ Web API พร้อมใช้งานใน Power Pages

การตั้งค่าไซต์สำหรับ Web API

สำคัญ

การรองรับค่าสัญลักษณ์ตัวแทน (*) ในการตั้งค่าไซต์ Webapi/<table-name>/fields ถูกเลิกใช้แล้ว

แทนที่ * ด้วยรายการคอลัมน์ที่คั่นด้วยเครื่องหมายจุลภาคที่ไซต์ของคุณต้องการ Power Pages คำขอ Web API สำหรับตารางที่กำหนดค่าด้วย * จะล้มเหลวจนกว่าคุณจะกำหนดค่าชื่อคอลัมน์อย่างชัดเจน

เมื่อต้องการเปิดใช้งาน API เว็บของพอร์ทัลสําหรับไซต์ของคุณ ให้กําหนดค่าการตั้งค่าไซต์สําหรับแต่ละตารางที่คุณต้องการเปิดเผยผ่าน API คุณสามารถกําหนดคอลัมน์ที่พร้อมใช้งานสําหรับ API เว็บโดยการแสดงรายการไว้ในการตั้งค่าไซต์ โดยใช้มุมมองระบบ Dataverse หรือโดยการรวมทั้งสองวิธี

หมายเหตุ

ใช้ตาราง ชื่อตรรกะ สำหรับการตั้งค่าเหล่านี้ (เช่น ลูกค้าองค์กร)

ชื่อการตั้งค่าไซต์ รายละเอียด
Webapi/<table-name>/enabled เปิดหรือปิดใช้งาน Web API สำหรับ<ชื่อตาราง>
ค่าเริ่มต้น:False
ค่าที่ถูกต้อง:True, False
Webapi/<table-name>/fields กําหนดรายการที่คั่นด้วยจุลภาคของชื่อตรรกะของคอลัมน์ที่พร้อมใช้งานผ่าน API เว็บ ตัวอย่างเช่น: name,accountnumber,telephone1 การตั้งค่านี้จําเป็นต้องมีเว้นแต่ Webapi/<table-name>/UseFieldsFromView จะถูกตั้งค่าเป็น True และมุมมองระบบที่กําหนดค่าไว้ประกอบด้วยคอลัมน์ที่มีสิทธิ์อย่างน้อยหนึ่งคอลัมน์ ค่าสัญลักษณ์ตัวแทน (*) เลิกใช้แล้ว
Webapi/<table-name>/UseFieldsFromView เมื่อตั้งค่าเป็น True จะทําให้คอลัมน์จากมุมมองระบบ Dataverse ที่ชื่อ Power Pages Web API Columns พร้อมใช้งานผ่าน Web API ค่าเริ่มต้น:False. ค่าที่ถูกต้อง:True, False หากมี Webapi/<table-name>/fields การกําหนดค่าไว้ด้วย คอลัมน์จากทั้งสองแหล่งที่มาจะถูกรวมเข้าด้วยกัน
Webapi/error/innererror เปิดใช้งานหรือปิดใช้งาน InnerError
ค่าเริ่มต้น:False
ค่าที่ถูกต้อง:True, False

ตัวอย่างเช่น เมื่อต้องการเปิดเผย API เว็บสําหรับตาราง Case ที่ผู้ใช้ที่ได้รับการรับรองความถูกต้องสามารถสร้าง อัปเดต และลบระเบียนสําหรับเอนทิตีนี้ ให้ใช้การตั้งค่าไซต์ที่แสดงในตารางต่อไปนี้

ชื่อการตั้งค่าไซต์ ค่าการตั้งค่าไซต์
Webapi/เหตุการณ์/เปิดใช้งาน จริง
Webapi/เหตุการณ์/ฟิลด์ attr1, attr2, attr3

กําหนดค่าคอลัมน์ API เว็บโดยใช้มุมมองระบบ

ด้วยการใช้มุมมองระบบ ผู้สร้างสามารถจัดการคอลัมน์ที่พร้อมใช้งานผ่าน API เว็บของพอร์ทัลโดยไม่ต้องเก็บรายการที่ใช้จุลภาคเป็นตัวคั่นในการตั้งค่าไซต์

  1. ใน Power Pages design studio ให้เปิด พื้นที่ทํางานข้อมูล
  2. เลือกตาราง เลือกแท็บ มุมมอง จากนั้นสร้างหรือแก้ไขมุมมองระบบสาธารณะ
  3. ตั้งชื่อมุมมอง Power Pages Web API Columns
  4. เพิ่มคอลัมน์ที่ไซต์ของคุณจําเป็นต้องใช้ลงในมุมมอง จากนั้นบันทึกและเผยแพร่มุมมอง
  5. ในแอปการจัดการพอร์ทัล ให้Webapi/<table-name>/UseFieldsFromViewสร้างการตั้งค่าไซต์สําหรับเว็บไซต์ และตั้งค่าเป็นTrue
  6. ยืนยันว่า Webapi/<table-name>/enabled ถูกตั้งค่าเป็น True.

หมายเหตุ

  • รวมเฉพาะคอลัมน์จากตารางหลักที่แสดงในมุมมองเท่านั้น ไม่รวมคอลัมน์จากตารางที่เกี่ยวข้อง คอลัมน์ที่ใช้สําหรับการกรองหรือการเรียงลําดับเท่านั้นจะไม่รวมไว้ เว้นแต่ว่าคอลัมน์เหล่านั้นจะแสดงอยู่ในมุมมองด้วย
  • สําหรับคอลัมน์ลุคอัป ใช้คุณสมบัติการค้นหา OData ที่สอดคล้องกันในคําขอ Web API ชื่อคุณสมบัติใช้รูปแบบ_<column-logical-name>_value ตัวอย่างเช่น primarycontactid คอลัมน์การค้นหาจะแสดงเป็น_primarycontactid_value
  • การเปลี่ยนแปลงในมุมมองระบบอาจใช้เวลาถึงห้านาทีจึงจะพร้อมใช้งานสำหรับ Web API

ถ้ามีการกําหนดค่าทั้ง Webapi/<table-name>/fields และ Webapi/<table-name>/UseFieldsFromView API ของเว็บจะรวมคอลัมน์ที่แสดงใน Webapi/<table-name>/fields เข้ากับคอลัมน์ที่เข้าเกณฑ์จากมุมมองระบบ Power Pages Web API Columns สําหรับตารางนั้น

สำคัญ

  • การตั้งค่าWebapi/<table-name>/UseFieldsFromViewไซต์จะพร้อมใช้งานใน Power Pages ไซต์เวอร์ชัน 9.8.8.x และใหม่กว่า
  • การรองรับค่าสัญลักษณ์ตัวแทน (*) ใน Webapi/<table-name>/fields เลิกใช้แล้ว ใช้ชื่อคอลัมน์อย่างชัดเจน มุมมองระบบของ Power Pages Web API Columns หรือทั้งสองอย่าง

ความปลอดภัยด้วยพอร์ทัล Web API

คุณสามารถกําหนดค่าการรักษาความปลอดภัยตามระเบียนสําหรับแต่ละระเบียนในพอร์ทัลโดยใช้สิทธิ์ตาราง พอร์ทัล Web API เข้าถึงระเบียนของตาราง (เอนทิตี) และเป็นไปตามสิทธิ์ของตารางที่มอบให้กับผู้ใช้ผ่านบทบาทของเว็บที่เกี่ยวข้อง

คุณสามารถกําหนดค่า สิทธิ์ของคอลัมน์ เพื่อกําหนดสิทธิ์การใช้งานเพิ่มเติมไปยังแต่ละคอลัมน์ภายในตารางขณะที่ใช้พอร์ทัล Web API

การตรวจสอบสิทธิ์คำขอ Web API ของพอร์ทัล

คุณไม่จำเป็นต้องใส่รหัสการรับรองความถูกต้อง เนื่องจากเซสชันของแอปพลิเคชันจะจัดการการรับรองความถูกต้องและการอนุญาต การเรียกใช้ Web API ทั้งหมดต้องมีโทเค็นการปลอมแปลงคำขอข้ามไซต์ (CSRF)

การใช้ EntitySetName

เมื่ออ้างอิงถึงตาราง Dataverse โดยใช้พอร์ทัล Web API ในโค้ดของคุณ ให้ใช้ EntitySetName ตัวอย่างเช่น เมื่อต้องการเข้าถึงตาราง บัญชี ไวยากรณ์โค้ดจะใช้ EntitySetName ของ accounts; /_api/accounts().

หมายเหตุ

ใช้ตาราง ชื่อตรรกะ สำหรับ การตั้งค่าไซต์ (เช่น บัญชีผู้ใช้)

เมื่อต้องการระบุ EntitySetName ของตารางที่เฉพาะเจาะจง ให้ทําตามขั้นตอนเหล่านี้:

  1. ไปที่ https://make.powerapps.com

  2. เลือกแท็บ Dataverse จากแผงด้านข้างและเลือกตาราง

  3. เลือกตัวเลือก ... (คําสั่ง) จากนั้นเลือก ขั้นสูงเครื่องมือ และ คัดลอกชื่อชุด เพื่อคัดลอก EntitySetName ของตารางไปยังคลิปบอร์ดของคุณ

    วิธีค้นหา EntitySetName ของตาราง Dataverse

กฎหมายและข้อบังคับด้านความเป็นส่วนตัว

ส่วนหัวของคําขอทั้งหมดใช้ ID ผู้ติดต่อเพื่อวัตถุประสงค์ในการตรวจสอบ สําหรับผู้ใช้แบบไม่ระบุชื่อ ค่าคือ null

หากเปิดใช้งานการบันทึกการตรวจสอบ ผู้ใช้สามารถดูเหตุการณ์การตรวจสอบทั้งหมดใน บันทึกการตรวจสอบ Office 365

ภาพหน้าจอของบันทึกการตรวจสอบ Office 365

ข้อมูลเพิ่มเติม:
เปิดใช้งาน และใช้การบันทึกกิจกรรม
ส่งออก, กำหนดค่า, และดูเรกคอร์ดบันทึกการตรวจสอบ

ตารางการกำหนดค่าที่ไม่รองรับ

คุณไม่สามารถใช้ Portal Web API สําหรับตารางการกําหนดค่าต่อไปนี้:

adx_contentaccesslevel

adx_contentsnippet

adx_entityform

adx_entityformmetadata

adx_entitylist

adx_entitypermission

adx_entitypermission_webrole

adx_externalidentity

adx_pagealert

adx_pagenotification

adx_pagetag

adx_pagetag_webpage

adx_pagetemplate

adx_portallanguage

adx_publishingstate

adx_publishingstatetransitionrule

adx_publishingstatetransitionrule_webrole

adx_redirect

adx_setting

adx_shortcut

adx_sitemarker

adx_sitesetting

adx_urlhistory

adx_webfile

adx_webfilelog

adx_webform

adx_webformmetadata

adx_webformsession

adx_webformstep

adx_weblink

adx_weblinkset

adx_webnotificationentity

adx_webnotificationurl

adx_webpage

adx_webpage_tag

adx_webpageaccesscontrolrule

adx_webpageaccesscontrolrule_webrole

adx_webpagehistory

adx_webpagelog

adx_webrole_systemuser

adx_website

adx_website_list

adx_website_sponsor

adx_websiteaccess

adx_websiteaccess_webrole

adx_websitebinding

adx_websitelanguage

adx_webtemplate

Limitations

ตารางกิจกรรมแบบกําหนดเองจะสืบทอดคอลัมน์พื้นฐาน (เช่น subject, description, activityid, และ createdon) จาก activitypointer ตาราง เมื่อคุณกําหนดค่าคอลัมน์ API เว็บสําหรับตารางกิจกรรมแบบกําหนดเองโดยใช้มุมมองของระบบ Webapi/<table-name>/fieldsคอลัมน์ API เว็บสําหรับ Power Pages หรือ $select, รวมคอลัมน์อย่างน้อยหนึ่งคอลัมน์ที่กําหนดไว้โดยตรงในตาราง ไม่ใช่แค่คอลัมน์ที่สืบทอดมา

ถ้าคุณกําหนดค่าเฉพาะคอลัมน์ที่ activitypointer สืบทอดมาเท่านั้น API เว็บจะไม่สามารถตรวจพบการเลือกคอลัมน์เฉพาะตารางได้ ด้วยเหตุนี้ จะถือว่าคำขอเป็นอักขระตัวแทน (*) และส่งกลับข้อผิดพลาดต่อไปนี้ แม้ว่าคุณจะกำหนดค่าเขตข้อมูลอย่างชัดเจน: แอตทริบิวต์ คอลัมน์ทั้งหมด ไม่เปิดใช้งานสำหรับ Web API

คำแนะนำ: รวมคอลัมน์อย่างน้อยหนึ่งคอลัมน์ที่กำหนดโดยตรงบนตารางกิจกรรมแบบกำหนดเอง เช่น ข้อคิดเห็นพอร์ทัล/adx_portalcomment พร้อมกับคอลัมน์ใด ๆ ที่สืบทอดมา

ปัญหาที่ทราบกันดี

ผู้ใช้จะได้รับข้อผิดพลาด CDS ถ้าพวกเขาเรียกใช้ GET คำขอ API เว็บสำหรับตารางที่มีหลายระดับของสิทธิ์ของตาราง หนึ่งต่อกลุ่ม หรือ กลุ่มต่อกลุ่ม เมื่อขอบเขต รายการหลัก, ผู้ติดต่อ หรือ ลูกค้าองค์กร เพิ่มเงื่อนไขเพิ่มเติมให้กับการสอบถาม

เมื่อต้องการแก้ไขปัญหานี้ ให้ใช้ FetchXML ในคิวรี OData

ขั้นตอนถัดไป

สืบค้นข้อมูลโดยใช้ Web API ของพอร์ทัล

  • อัปเดตล่าสุดเมื่อ