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

บทความ
03/16/2023

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

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

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

หมายเหตุ

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

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

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

การดำเนินการ	Method	URI
ดึงข้อมูลเรกคอร์ดตาราง	GET	`[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
ดึงข้อมูลเรกคอร์ดเอนทิตีสามรายการแรก	GET	`[Portal URI]/_api/accounts?$select=name,revenue&$top=3` ตัวอย่าง: `https://contoso.powerappsportals.com/_api/accounts?$select=name,revenue&$top=3`

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

การดำเนินการ	Method	URI
ดึงข้อมูลคุณสมบัติเฉพาะสำหรับเรกคอร์ด	GET	`[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
GET	`[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
GET	`[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
GET	`[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
GET	`[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
GET	`[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
GET	`[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
GET	`[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

แชร์ผ่าน

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

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

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

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

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

กรองผลลัพธ์

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

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

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

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

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

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

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

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

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

ดูเพิ่มเติม

แหล่งทรัพยากรเพิ่มเติม

แชร์ผ่าน

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

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

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

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

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

กรองผลลัพธ์

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

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

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

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

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

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

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

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

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

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

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

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

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

ดูเพิ่มเติม

แหล่งทรัพยากรเพิ่มเติม