แชร์ผ่าน

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

  • บทความ

หมายเหตุ

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

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

ข้อกำหนดเบื้องต้น

  • เวอร์ชันพอร์ทัลของคุณต้องเป็น 9.4.1.x หรือสูงกว่า

  • เปิดใช้งานตารางและฟิลด์สำหรับการดำเนินงานของ Web API ข้อมูลเพิ่มเติม: การตั้งค่าไซต์สำหรับ Web API

  • Web API ของพอร์ทัลเข้าถึงเรกคอร์ดตาราง และติดตามสิทธิ์ของตารางที่มอบให้กับผู้ใช้ผ่านบทบาทเว็บที่เกี่ยวข้อง ตรวจสอบให้แน่ใจว่าคุณตั้งค่าคอนฟิกสิทธิ์ของตารางที่ถูกต้อง ข้อมูลเพิ่มเติม: สร้างบทบาทเว็บ

หมายเหตุ

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

เรกคอร์ดการสอบถาม

ตัวอย่างต่อไปนี้สอบถามเรกคอร์ดลูกค้าองค์กร:

การดำเนินการ Method URI
ดึงข้อมูลเรกคอร์ดตาราง รับ [Portal URI]/_api/accounts

ตัวอย่าง:
 https://contoso.powerappsportals.com/_api/accounts

คำตอบตัวอย่าง

{
"value": [
    {
    "@odata.etag": "W/\"1066412\"",
    "name": "Fourth Coffee (sample)",
    "accountid": "d2e11ba8-92f6-eb11-94ef-000d3a5aa607"
    },
    {
    "@odata.etag": "W/\"1066413\"",
    "name": "Litware, Inc. (sample)",
    "accountid": "d4e11ba8-92f6-eb11-94ef-000d3a5aa607"
    }
]
}

ใช้ตัวเลือกการสอบถามของระบบ $select และ $top เพื่อส่งคืนคุณสมบัติชื่อสำหรับสามบัญชีแรก:

การดำเนินการ Method URI
ดึงข้อมูลเรกคอร์ดเอนทิตีสามรายการแรก รับ [Portal URI]/_api/accounts?$select=name,revenue&$top=3

ตัวอย่าง:
https://contoso.powerappsportals.com/_api/accounts?$select=name,revenue&$top=3

ดึงข้อมูลบัญชีโดยใช้รหัสบัญชี:

การดำเนินการ Method URI
ดึงข้อมูลคุณสมบัติเฉพาะสำหรับเรกคอร์ด รับ [Portal URI]/_api/accounts(e0e11ba8-92f6-eb11-94ef-000d3a5aa607)?$select=name

ตัวอย่าง:
https://contoso.powerappsportals.com/_api/accounts(e0e11ba8-92f6-eb11-94ef-000d3a5aa607)?$select=name

คำตอบตัวอย่าง

{
    "@odata.etag": "W/\"1066414\"",
    "name": "Adventure Works (sample)",
    "accountid": "d6e11ba8-92f6-eb11-94ef-000d3a5aa607"
}

ใช้ตัวเลือกการสอบถามของระบบ

ตัวเลือกการสอบถามของระบบแต่ละรายการที่คุณผนวกเข้ากับ URL สำหรับชุดเอนทิตี จะถูกเพิ่มโดยใช้ไวยากรณ์สำหรับสตริงการสอบถาม รายการแรกถูกผนวกหลังจาก [?] และตัวเลือกการสอบถามต่อไปนี้จะถูกแยกโดยใช้ [&] ตัวเลือกการสอบถามทั้งหมดต้องตรงตามตัวพิมพ์ใหญ่-เล็ก ตามที่แสดงในตัวอย่างต่อไปนี้:

Method URI
รับ [Portal URI]/_api/accounts?$select=name,revenue&$filter=revenue gt 90000&$top=3

ตัวอย่าง:
https://contoso.powerappsportals.com/_api/accounts?$select=name,revenue&$filter=revenue gt 90000&$top=3

ร้องขอคุณสมบัติเฉพาะ

ใช้ตัวเลือกการสอบถามของระบบ $select เพื่อจำกัดคุณสมบัติที่ส่งคืนดังแสดงในตัวอย่างต่อไปนี้:

Method URI
รับ [Portal URI]/_api/accounts?$select=name,revenue&$top=3

ตัวอย่าง:
https://contoso.powerappsportals.com/_api/accounts?$select=name,revenue&$top=3

ข้อสำคัญ

นี่คือวิธีปฏิบัติที่ดีที่สุดของประสิทธิภาพการทำงาน หากไม่ได้ระบุคุณสมบัติและคุณได้ตั้งค่าคอนฟิกค่าการตั้งค่าไซต์ Webapi/<table name>/fields เป็น * จากนั้น คุณสมบัติทั้งหมดจะถูกส่งคืนโดยใช้ $select หากไม่ได้ระบุคุณสมบัติไว้ ข้อผิดพลาดจะถูกส่งคืน

กรองผลลัพธ์

ใช้ตัวเลือกการสอบถามของระบบ $filter เพื่อกำหนดเกณฑ์ที่จะส่งคืนแถว

ตัวดำเนินการตัวกรองมาตรฐาน

Web API รองรับตัวดำเนินการตัวกรอง OData มาตรฐานที่แสดงในตารางต่อไปนี้:

Operator รายละเอียด ตัวอย่างเช่น
ตัวดำเนินการเปรียบเทียบ
eq เท่ากับ $filter=revenue eq 100000
ne ไม่เท่ากับ $filter=revenue ne 100000
gt มากกว่า $filter=revenue gt 100000
ge มากกว่าหรือเท่ากับ $filter=revenue ge 100000
lt น้อยกว่า $filter=revenue lt 100000
le น้อยกว่าหรือเท่ากับ $filter=revenue le 100000
ตัวดำเนินการทางตรรกะ:
and ทางตรรกะและ $filter=revenue lt 100000 และ revenue gt 2000
or ทางตรรกะหรือ $filter=contains(name,'(sample)') หรือ contains(name,'test')
not นิเสธเชิงตรรกะ $filter=not contains(name,'sample')
ตัวดำเนินการจัดกลุ่ม
( ) การจัดกลุ่มความสำคัญ (contains(name,'sample') หรือ contains(name,'test')) และ revenue gt 5000

ฟังก์ชันการสอบถามมาตรฐาน

Web API รองรับฟังก์ชันการสอบถามสตริง OData มาตรฐานเหล่านี้:

ฟังก์ชัน ตัวอย่างเช่น
มี $filter=contains(name,'(sample)')
ลงท้ายด้วย $filter=endswith(name,'Inc.')
เริ่มต้นด้วย $filter=startswith(name,'a')

ฟังก์ชันการสอบถาม Dataverse

Web API รองรับฟังก์ชันการสอบถาม Dataverse เพื่อกรองผลลัพธ์ ดูข้อมูลเพิ่มเติมที่ การอ้างอิงฟังก์ชันการสอบถาม Web API

ผลลัพธ์ที่เป็นลำดับ

ระบุลำดับที่จะมีการส่งคืนสินค้าโดยใช้ตัวเลือกการสอบถามของระบบ $orderby  ใช้คำต่อท้าย asc หรือ desc  เพื่อระบุลำดับจากน้อยไปมากหรือมากไปหาน้อยตามลำดับ ค่าเริ่มต้นคือน้อยไปหามาก ถ้าไม่ได้ใช้คำต่อท้าย ตัวอย่างต่อไปนี้แสดงการดึงชื่อและคุณสมบัติรายได้ของบัญชีที่เรียงลำดับตามรายได้จากน้อยไปมากและตามชื่อจากมากไปน้อย

Method URI
รับ [Portal URI]/_api/accounts?$select=name,revenue&$orderby=name asc,revenue desc&$filter=revenue gt 90000

ตัวอย่าง:
https://contoso.powerappsportals.com/_api/accounts?$select=name,revenue&$orderby=name asc,revenue desc&$filter=revenue gt 90000

ผลการรวมและการจัดกลุ่ม

โดยใช้  $apply  คุณสามารถรวมและจัดกลุ่มข้อมูลของคุณแบบไดนามิกตามที่เห็นในตัวอย่างต่อไปนี้:

สถานการณ์สมมติ ตัวอย่างเช่น
รายการของสถานะที่ไม่ซ้ำกันในการสอบถาม accounts?$apply=groupby((statuscode))
ผลรวมของค่าโดยประมาณ opportunities?$apply=aggregate(estimatedvalue with sum as total)
ขนาดเฉลี่ยของดีลตามมูลค่าและสถานะโดยประมาณ opportunities?$apply=groupby((statuscode),aggregate(estimatedvalue with average as averagevalue)
ผลรวมของมูลค่าโดยประมาณตามสถานะ opportunities?$apply=groupby((statuscode),aggregate(estimatedvalue with sum as total))
รายได้จากโอกาสทางการขายทั้งหมดตามชื่อบัญชี opportunities?$apply=groupby((parentaccountid/name),aggregate(estimatedvalue with sum as total))
ชื่อผู้ติดต่อหลักสำหรับบัญชีใน 'WA' accounts?$apply=filter(address1_stateorprovince eq 'WA')/groupby((primarycontactid/fullname))
เวลาและวันที่ของเรกคอร์ดที่สร้างล่าสุด accounts?$apply=aggregate(createdon with max as lastCreate)
เวลาและวันที่ของเรกคอร์ดที่สร้างเป็นครั้งแรก accounts?$apply=aggregate(createdon with min as firstCreate)

ดึงข้อมูลจำนวนแถว

ใช้ตัวเลือกการสอบถามของระบบ $count ที่มีค่าเป็น จริง เพื่อรวมจำนวนของเอนทิตีที่ตรงกับเกณฑ์ตัวกรองสูงสุด 5,000 รายการ

Method URI
รับ [Portal URI/_api/accounts?$select=name&$filter=contains(name,'sample')&$count=true

ตัวอย่าง:
https://contoso.powerappsportals.com/_api/accounts?$select=name&$filter=contains(name,'sample')&$count=true

คำตอบตัวอย่าง

{
"@odata.count": 10,
"value": [
    {
    "@odata.etag": "W/\"1066412\"",
    "name": "Fourth Coffee (sample)",
    "accountid": "d2e11ba8-92f6-eb11-94ef-000d3a5aa607"
    },
    {
    "@odata.etag": "W/\"1066413\"",
    "name": "Litware, Inc. (sample)",
    "accountid": "d4e11ba8-92f6-eb11-94ef-000d3a5aa607"
    },
    {
    "@odata.etag": "W/\"1066414\"",
    "name": "Adventure Works (sample)",
    "accountid": "d6e11ba8-92f6-eb11-94ef-000d3a5aa607"
    }
]
}

หากคุณไม่ต้องการส่งคืนข้อมูลใดๆ ยกเว้นการนับ คุณสามารถใช้ $count กับคอลเลกชันใดๆ เพื่อให้ได้เฉพาะค่า

Method URI
รับ [Portal URI/_api/accounts/$count

ตัวอย่าง:
https://contoso.powerappsportals.com/_api/accounts/$count

คำตอบตัวอย่าง

3

การเปรียบเทียบคอลัมน์

ตัวอย่างต่อไปนี้แสดงวิธีเปรียบเทียบคอลัมน์โดยใช้ Web API:

Method URI
GET [Portal URI]/_api/contacts?$select=firstname&$filter=firstname eq lastname

ตัวอย่าง:
https://contoso.powerappsportals.com/_api/contacts?$select=firstname&$filter=firstname eq lastname

ดึงข้อมูลเรกคอร์ดตารางที่เกี่ยวข้องด้วยการสอบถาม

ใช้ตัวเลือกการสอบถามของระบบ $expand ในคุณสมบัติการนำทาง เพื่อควบคุมว่าจะส่งคืนข้อมูลใดบ้างจากเอนทิตีที่เกี่ยวข้อง

ค้นหาคุณสมบัติการนำทางที่เกี่ยวข้อง

คุณจะต้องใช้ Microsoft.Dynamics.CRM.associatednavigationproperty เป็นแอตทริบิวต์การค้นหาเมื่อใช้ตัวเลือกกการสอบถาม $expand

เพื่อกำหนด Microsoft.Dynamics.CRM.associatednavigationproperty ของแอตทริบิวต์ คุณสามารถขอ http GET ต่อไปนี้ สำหรับคอลัมน์โดยใช้หลักการตั้งชื่อต่อไปนี้: _name_value

ในตัวอย่างต่อไปนี้ เราสามารถกำหนดคุณสมบัติการนำทางที่เกี่ยวข้องของคอลัมน์ ผู้ติดต่อหลัก ของตาราง บัญชี โดยระบุชื่อคอลัมน์ primarycontactid โดยการจัดรูปแบบชื่อในคำขอ: _primarycontactid_value

Method URI
GET [Portal URI]/_api/accounts?$select=_primarycontactid_value

ตัวอย่างเช่น
https://contoso.powerappsportals.com/_api/accounts?$select=_primarycontactid_value

คำตอบตัวอย่าง

{
"value": [
    {
        "@odata.etag": "W/\"2465216\"",
        "_primarycontactid_value@OData.Community.Display.V1.FormattedValue": "Yvonne McKay (sample)",
        "_primarycontactid_value@Microsoft.Dynamics.CRM.associatednavigationproperty": "primarycontactid",
        "_primarycontactid_value@Microsoft.Dynamics.CRM.lookuplogicalname": "contact",
        "_primarycontactid_value": "417319b5-cd18-ed11-b83c-000d3af4d812",
        "accountid": "2d7319b5-cd18-ed11-b83c-000d3af4d812"
    }
]
}

เราเห็นจากการตอบกลับว่าคุณสมบัติการนำทางที่เกี่ยวข้องคือ primarycontactid คุณสมบัติการนำทางที่เกี่ยวข้องสามารถเป็นคอลัมน์ค้นหาของ ชื่อตรรกะหรือชื่อสคีมา ขึ้นอยู่กับวิธีการสร้างตาราง

สำหรับข้อมูลเพิ่มเติม ดูได้ที่ ดึงข้อมูลเกี่ยวกับคุณสมบัติการค้นหา

ดึงข้อมูลเรกคอร์ดตารางที่เกี่ยวข้องโดยการขยายคุณสมบัติการนำทางแบบค่าเดียว

ตัวอย่างต่อไปนี้แสดงวิธีการเรียกข้อมูลผู้ติดต่อสำหรับเรกคอร์ดลูกค้าองค์กรทั้งหมด สำหรับเรกคอร์ดผู้ติดต่อที่เกี่ยวข้อง เรากำลังดึงข้อมูลเฉพาะ contactid และ fullname

Method URI
GET [Portal URI]/_api/accounts?$select=name&$expand=primarycontactid($select=contactid,fullname)

ตัวอย่าง:
https://contoso.powerappsportals.com/_api/accounts?$select=name&$expand=primarycontactid($select=contactid,fullname)

คำตอบตัวอย่าง

{
"value": [
    {
    "@odata.etag": "W/\"1066412\"",
    "name": "Fourth Coffee (sample)",
    "accountid": "d2e11ba8-92f6-eb11-94ef-000d3a5aa607",
        "primarycontactid": {
        "contactid": "e6e11ba8-92f6-eb11-94ef-000d3a5aa607",
        "fullname": "Yvonne McKay (sample)"
        }
    },
    {
    "@odata.etag": "W/\"1066413\"",
    "name": "Litware, Inc. (sample)",
    "accountid": "d4e11ba8-92f6-eb11-94ef-000d3a5aa607",
        "primarycontactid": {
        "contactid": "e8e11ba8-92f6-eb11-94ef-000d3a5aa607",
        "fullname": "Susanna Stubberod (sample)"
        }
    }
]
}

ดึงข้อมูลตารางที่เกี่ยวข้องโดยการขยายคุณสมบัติการนำทางที่มีค่าคอลเลกชัน

หากคุณขยายพารามิเตอร์การนำทางที่มีค่าคอลเลกชันเพื่อดึงข้อมูลตารางที่เกี่ยวข้องสำหรับชุดเอนทิตี ระบบจะส่งคืนความลึกเพียงระดับเดียวเท่านั้น หากมีข้อมูล มิฉะนั้น คอลเลกชันจะส่งคืนอาร์เรย์ที่ว่างเปล่า

Method URI
รับ [Portal URI]/_api/accounts?$top=5&$select=name&$expand=Account_Tasks($select=subject,scheduledstart)

ตัวอย่าง:
https://contoso.powerappsportals.com/_api/accounts?$top=5&$select=name&$expand=Account_Tasks($select=subject,scheduledstart)

ดึงข้อมูลตารางที่เกี่ยวข้องโดยการขยายคุณสมบัติการนำทางทั้งแบบที่มีค่าคอลเลกชันและแบบค่าเดียว

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

Method URI
รับ [Portal URI]/_api/accounts?$top=5&$select=name&$expand=primarycontactid($select=contactid,fullname),Account_Tasks($select=subject,scheduledstart)

ตัวอย่าง:
https://contoso.powerappsportals.com/_api/accounts?$top=5&$select=name&$expand=primarycontactid($select=contactid,fullname),Account_Tasks($select=subject,scheduledstart)

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

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

ดูเพิ่มเติม

ภาพรวมของ API เว็บของพอร์ทัล
บทช่วยสอน: ใช้ Web API ของพอร์ทัล
กำหนดค่าสิทธิ์ของคอลัมน์

หมายเหตุ

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

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