การใช้งาน Microsoft Dataverse

สร้าง อัปเดต ลบ และสอบถามแถว Microsoft Dataverse ใน workflow n8n

ใช้ node Microsoft Dataverse เพื่อทำงานอัตโนมัติใน Microsoft Dataverse และรวมเข้ากับแอปพลิเคชันอื่นๆ คุณสามารถสร้าง อ่าน อัปเดต และลบแถวในตารางมาตรฐานและตารางแบบกำหนดเองได้โดยใช้ Dataverse Web API

Credentials

อ้างถึง Microsoft Dataverse credentials สำหรับการตั้งค่าการรับรองความถูกต้อง node รองรับการเข้าถึงของผู้ใช้ที่ได้รับมอบสิทธิ์และการเข้าถึงผ่านแอปเท่านั้น Microsoft Dataverse OAuth2 API หนังสือรับรอง

การดำเนินงาน

• Row
  • Create : เพิ่มแถวใหม่
  • Create or Update : สร้างแถวหรืออัปเดตแถวที่มีอยู่โดยใช้รหัสแถวหรือคีย์สำรอง
  • Delete : ลบแถว
  • Get : รับแถวตาม ID
  • Get Many : รับหลายแถวพร้อมการกรองและการเรียงลำดับเพิ่มเติม
  • Update : อัพเดตแถวที่มีอยู่ การดำเนินการนี้ไม่สร้างแถวที่ขาดหายไป

เลือกตารางและแถว

ชุด Resource ถึง Row จากนั้นเลือก Operation.

ใน Table Name or ID , เลือก From List เพื่อค้นหาตารางสภาพแวดล้อมของคุณ หากต้องการเข้าสู่ตารางด้วยตนเอง ให้เลือก By ID และป้อนชื่อชุดเอนทิตี Web API เช่น accounts หรือ contacts . นี่ไม่ใช่ชื่อที่แสดงของตาราง ชื่อตรรกะเอกพจน์ หรือ GUID

สำหรับ Get, Update และ Delete ใช้ Row ID เพื่อเลือกแถว From List หรือป้อน GUID By ID . ตัวอย่างเช่น 00000000-0000-0000-0000-000000000001 มีรูปแบบที่ต้องการ แทนที่ด้วย ID ของแถวในสภาพแวดล้อมของคุณ

เท่านั้น Create or Update รองรับ ที่อยู่คีย์สำรอง .

สร้างและอัปเดตแถว

สำหรับ Create, Update และ Create or Update , เลือก Input Mode:

ระบุอย่างน้อยหนึ่งช่อง node ปฏิเสธรายการแถวว่าง ตัวเลือกฟิลด์จะแสดงคอลัมน์ที่เขียนได้สำหรับการดำเนินการที่เลือก สำหรับ Create or Update โดยจะแสดงคอลัมน์ที่รองรับทั้งการสร้างและการอัปเดตแถว

ที่ Field Value input เป็นฟิลด์ string node จะไม่แปลงข้อความตามตัวอักษรเป็นตัวเลขหรือ boolean โดยอัตโนมัติ ใช้ JSON เมื่อคุณต้องการเก็บรักษาประเภทเหล่านี้หรือส่ง null.

สร้างบัญชี (Create an account)

หากต้องการสร้างบัญชี ให้เลือก Create , ตั้ง Table Name or ID ถึง accounts และใช้ JSON input ใส่วัตถุนี้เข้าไป Row Item (JSON):

{
	"name": "Contoso",
	"accountnumber": "ACC-001",
	"numberofemployees": 25,
	"creditonhold": false
}

สำหรับ Update ให้เลือกบัญชีที่มีอยู่ Row ID และส่งเฉพาะช่องที่คุณต้องการเปลี่ยนแปลง ตัวอย่างเช่น {"telephone1": "555-0100"} อัปเดตหมายเลขโทรศัพท์โดยไม่ต้องแทนที่ช่องอื่นๆ

ตั้งค่าคอลัมน์การค้นหา (Set lookup columns)

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

แทนที่ตัวยึดมุมฉากด้วย GUID แถวจากสภาพแวดล้อมของคุณ คุณสามารถละเครื่องหมายทับนำหน้าในข้อมูลอ้างอิงเหล่านี้ได้

ตัวอย่างเช่น หากต้องการตั้งค่าผู้ติดต่อหลักและเจ้าของบัญชี ให้รวมฟิลด์ต่อไปนี้เข้าไป Row Item (JSON):

{
	"primarycontactid": "/contacts(<contact-id>)",
	"ownerid": "/systemusers(<user-id>)"
}

คุณยังสามารถระบุการผูกที่ชัดเจนได้ เช่น {"primarycontactid@odata.bind": "/contacts(<contact-id>)"} . node ผ่านการผูกอย่างชัดเจนผ่านไม่มีการเปลี่ยนแปลง ใช้ชื่อคุณสมบัติการนำทางที่ตรงตามตัวพิมพ์เล็กและตัวพิมพ์ใหญ่จากข้อมูลเมตาของตารางของคุณ ซึ่งอาจแตกต่างจากชื่อตรรกะของคอลัมน์

หากต้องการล้างการค้นหาเป้าหมายเดียว ให้ส่ง null ตัวอย่างเช่น {"primarycontactid": null} . สำหรับการค้นหาแบบหลายตาราง ให้ล้างคุณสมบัติการนำทางเฉพาะแทน หาก Dataverse อนุญาตให้ล้างความสัมพันธ์นั้น

สร้างหรืออัปเดตแถว

เลือก Create or Update เพื่อระบุแถวโดยใช้อย่างใดอย่างหนึ่งเหล่านี้ Identifier Type ค่า:

• Row ID (GUID) : เลือกหรือป้อน Row ID . หากไม่มีแถวดังกล่าว Dataverse จะสร้างแถวนั้นด้วย GUID นั้น
• Alternate Key : ป้อน Alternate Key Predicate เช่น accountnumber='ACC-001' . กำหนดค่าคีย์สำรองบนตารางใน Dataverse ก่อนใช้งาน

ป้อนเฉพาะภาคแสดง โดยไม่มีชื่อตารางหรือวงเล็บล้อมรอบ สำหรับคีย์ string ให้ใส่เครื่องหมายคำพูดเดี่ยวไว้รอบค่า node ปฏิเสธตัวคั่น URL ตัวคั่นเส้นทาง และอักขระควบคุมในภาคแสดง

ภายใต้ Options ใช้ Behavior เพื่อควบคุมการเขียน:

ตัวอย่างเช่น เลือก accounts โต๊ะ เลือกเลย Alternate Key และเข้า accountnumber='ACC-001' . ส่ง {"name": "Contoso"} ใน Row Item (JSON) เพื่อสร้างหรืออัพเดตบัญชีด้วยหมายเลขบัญชีนั้น

แถวแบบสอบถาม

ที่ Get รองรับการดำเนินงาน Select Column Names or IDs และ Expand Query ภายใต้ Options. Get Many รองรับตัวเลือกเหล่านั้นและตัวกรองเพิ่มเติม การเรียงลำดับ และขีดจำกัดผลลัพธ์

รับหลายแถวด้วย OData (Get many rows with OData)

เลือก Get Many และกำหนดค่า parameter ต่อไปนี้:

ตัวอย่างเช่น เพื่อดึงข้อมูลบัญชีที่ใช้งานอยู่สูงสุด 100 บัญชีซึ่งมีชื่อขึ้นต้นด้วย Contoso:

1. ชุด Table Name or ID ถึง accounts.
2. ลาออก Return All ปิดและตั้งค่า Limit ถึง 100.
3. ภายใต้ Options ให้เลือก name และ accountnumber ใน Select Column Names or IDs.
4. ชุด Filter Rows ถึง statecode eq 0 and startswith(name,'Contoso').
5. ชุด Sort Column Name or ID ถึง name และ Sort Direction ถึง Ascending.

ตัวเลือกการอ่านคอลัมน์ใช้ชื่อคุณสมบัติการค้นหา เช่น _primarycontactid_value โดยอัตโนมัติ เมื่อเขียนตัวกรองดิบหรือ expression การเรียงลำดับ ให้ใช้แบบฟอร์มคุณสมบัตินั้นสำหรับ GUID การค้นหา เช่น กรองตาม _primarycontactid_value eq <contact-id> , แทนที่ <contact-id> ด้วย GUID ที่ไม่มีเครื่องหมายคำพูด ใช้ชื่อคุณสมบัติการนำทางสำหรับ Expand Query.

การจำกัด pagination และผลลัพธ์ (Pagination and result limits)

สำหรับการสอบถาม OData node จะตามมา @odata.nextLink จนกว่าจะถึง Limit หรือดึงผลลัพธ์ที่มีอยู่ทั้งหมด

เมื่อ Limit คือ 5,000 หรือน้อยกว่า node ก็ส่งเป็นเช่นกัน $top . สำหรับขีดจำกัดที่มากขึ้น node จะออกจากการทำงาน $top ไม่ได้ตั้งค่าเพื่อให้ Dataverse สามารถส่งคืนหลายหน้าได้ ที่ชัดเจน Row Count ($Top) มีความสำคัญเหนือกว่าและสามารถจำกัดผลลัพธ์ได้แม้เมื่อใดก็ตาม Return All เปิดอยู่

หากต้องการดึงข้อมูลมากกว่า 5,000 แถว ให้ออก Row Count ($Top) ยกเลิกการตั้งค่าและเปิดใช้งาน Return All หรือชุด Limit สูงกว่า 5,000. กฎการเพจเหล่านี้ใช้กับแบบสอบถาม OData ไม่ใช่ FetchXML

Use FetchXML

ชุด Options > FetchXML Query เพื่อเรียกใช้แบบสอบถาม FetchXML จะแทนที่การเลือก OData กรอง เรียงลำดับ ขยาย และตัวเลือกด้านบน เก็บ Return All ปิดและตั้งค่า Limit เพื่อปิดแถวที่ส่งคืน

ตัวอย่างเช่น เลือก accounts ตารางและป้อนคำค้นหานี้เพื่อดึงข้อมูลบัญชีที่ใช้งานอยู่สูงสุด 50 บัญชี:

<fetch top="50">
	<entity name="account">
		<attribute name="name" />
		<attribute name="accountnumber" />
		<filter>
			<condition attribute="statecode" operator="eq" value="0" />
		</filter>
	</entity>
</fetch>

FetchXML ใช้ชื่อตรรกะของตาราง account แม้ว่า Table Name or ID ใช้ชื่อชุดเอนทิตี accounts.

pagination FetchXML (FetchXML pagination)

node Microsoft Dataverse ไม่รองรับ pagination FetchXML FetchXML Query ด้วย Return All ทำให้เกิดข้อผิดพลาด กำลังปิด Return All หลีกเลี่ยงข้อผิดพลาดแต่เพิ่มขึ้น Limit ไม่ดึงข้อมูลหน้า FetchXML เพิ่มเติม ใช้แบบสอบถาม OData สำหรับ pagination อัตโนมัติ

ทำงานกับโต๊ะยืดหยุ่น

สำหรับ Get, Get Many และ Delete , ตั้ง Options > Partition ID เมื่อคุณต้องการกำหนดเป้าหมายพาร์ติชันตารางยืดหยุ่น

Create, Update และ Create or Update อย่าเปิดเผย Partition ID ตัวเลือก สำหรับ Create รวมถึง partitionid ในแถว JSON เมื่อสร้างแถวที่แบ่งพาร์ติชัน

หากต้องการอัปเดตหรือเพิ่มแถวที่แบ่งพาร์ติชัน ให้ใช้ Create or Update ด้วย Identifier Type ตั้งค่าเป็น Alternate Key . รวมคีย์หลักของตารางและ partitionid ใน Alternate Key Predicate:

<primary-key-column>=<row-id>,partitionid='<partition-id>'

แทนที่ตัวยึดตำแหน่งด้วยชื่อลอจิคัลของคอลัมน์คีย์หลักของตาราง, GUID ของแถว และ ID พาร์ติชัน ชุด Behavior ถึง Update Only ถ้าแถวนั้นต้องมีอยู่แล้ว อ้างอิงถึง Microsoft เอกสารตารางยืดหยุ่น สำหรับพฤติกรรมและข้อจำกัดเฉพาะตาราง

output และข้อมูลเมตา

• Create, Update และ Create or Update ขอแถวหลังจากการเขียนและส่งคืนการตอบกลับของ Dataverse
• Get ส่งคืนแถวเดียว
• Get Many ส่งคืนแต่ละแถวเป็นรายการ n8n แยกกัน แทนที่จะเป็นคอลเลกชันภายใน a value สนาม
• Delete ผลตอบแทน {"success": true, "id": "<row-id>"} หลังจากลบสำเร็จ

การดำเนินการทั้งหมดยกเว้น Delete ข้อเสนอ Options > Return Full Metadata ซึ่งปิดอยู่ตามค่าเริ่มต้น เปิดเพื่อขอคำอธิบายประกอบ OData รวมถึงค่าที่จัดรูปแบบที่ Dataverse จัดเตรียมไว้ให้ node ไม่เปลี่ยนชื่อคอลัมน์หรือลดความซับซ้อนของคำอธิบายประกอบ

ปัญหาทั่วไป

ตัวเลือกตารางหรือคอลัมน์ไม่โหลด (Table or column options don't load)

ตรวจสอบสถานะ HTTP และข้อผิดพลาด Dataverse ที่แสดงในเครื่องมือเลือก ตรวจสอบ URL ของสภาพแวดล้อมและการเข้าถึง credentials รวมถึงการเข้าถึงข้อมูลเมตาของตาราง อ้างถึง การแก้ไขปัญหาข้อมูลประจำตัวของ Microsoft Dataverse .

หากคุณทราบชื่อชุดเอนทิตีของตาราง คุณสามารถป้อนได้โดยใช้ Table Name or ID > By ID . สิ่งนี้ไม่ข้ามสิทธิ์ Dataverse

ค่าการค้นหาถูกปฏิเสธ (A lookup value is rejected)

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

แบบสอบถามส่งกลับแถวน้อยกว่าที่คาดไว้ (A query returns fewer rows than expected)

ตรวจสอบ Limit , ลบ Row Count ($Top) หากคุณต้องการเพจจิ้ง และยืนยันว่าแบบสอบถามใช้ FetchXML หรือไม่ อ้างถึง การจำกัด pagination และผลลัพธ์ และ ใช้ FetchXML .

ทรัพยากรที่เกี่ยวข้อง

• Microsoft Dataverse credentials
• เอกสารประกอบ Dataverse Web API
• สืบค้นข้อมูลโดยใช้ Web API
• ใช้คีย์สำรองกับ Web API