ทำงานกับโฟลว์เดสก์ท็อปโดยใช้โค้ด

นักพัฒนาสามารถเพิ่มฟังก์ชัน โฟลว์เดสก์ท็อป ไปยังแอปพลิเคชันของพวกเขา รวมถึงการทริกเกอร์และยกเลิกโฟลว์เดสก์ท็อปโดยทางโปรแกรม ความสามารถเหล่านี้เป็นส่วนหนึ่งของแพลตฟอร์ม Microsoft Dataverse

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

1. ความรู้ของ Dataverse Web APIรับรองความถูกต้องด้วย Dataverse และ การใช้ OAuth กับ Dataverse
2. ความรู้ของแนวสภาพแวดล้อมและองค์กรของ Dataverse และ วิธีดึง URL องค์กร ด้วยตนเอง หรือโดยทางโปรแกรม
3. ความรู้ของ แนวคิดโฟลว์เดสก์ท็อป และของสิ่งที่ การเชื่อมต่อและวิธีสร้าง

Important

ในบทความนี้ คุณต้องแทนที่วงเล็บเหลี่ยมทั้งหมด [...] ใน URL และข้อมูลอินพุต/เอาต์พุต ด้วยค่าเฉพาะในสถานการณ์ของคุณ

รายการโฟลว์เดสก์ท็อปที่พร้อมใช้งาน

สคริปต์โฟลว์เดสก์ท็อปทั้งหมดอยู่ใน Dataverse เป็นส่วนหนึ่งของ เอนทิตีเวิร์กโฟลว์

กรองรายการเวิร์กโฟลว์ตามหมวดหมู่เพื่อระบุโฟลว์เดสก์ท็อป

ร้องขอโฟลว์เดสก์ท็อป

Authorization: Bearer eyJ0eXAiOi...
Accept: application/json

GET https://[Organization URI]/api/data/v9.2/workflows?$filter=category+eq+6&$select=name,workflowid&$orderby=name HTTP/1.1  

ตอบสนองต่อคำขอรับโฟลว์เดสก์ท็อป

{
    "@odata.context": "https://[Organization URI]/api/data/v9.2/$metadata#workflows(name,workflowid)",
    "value": [
        {
            "@odata.etag": "W1069462",
            "name": "Desktop flow 1",
            "workflowid": "f091ffab-58bb-4630-a115-659453d56f59",
        },
        {
            "@odata.etag": "W1028555",
            "name": "Desktop flow 2",
            "workflowid": "eafba1a2-e8d4-4efa-b549-11d4dfd9a3d1",
        }
    ]
}

รับสคีมาสำหรับโฟลว์เดสก์ท็อป

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

ร้องขอสคีมาสำหรับโฟลว์เดสก์ท็อป

Authorization: Bearer eyJ0eXAiOi...
Accept: application/json

GET https://[Organization URI]/api/data/v9.2/workflows([Workflow Id])/clientdata/$value HTTP/1.1  

ตอบสนองต่อคำขอรับสคีมาของโฟลว์เดสก์ท็อป

{
    "clientversion": "2.19.00170.22097",
    "properties": {
        "definition": {
            "dependencies": [],
            "isvalid": true,
            "name": "Desktop Flow 1",
            "package": "UEsDBBQAAAAIAIqZlF...",
            "$schema": "https://schema.management.azure.com/providers/Microsoft.Logic/schemas/2016-06-01/workflowdefinition.json#"
        },
        "inputs": {
            "schema": {
                "properties": {
                    "Input1": {
                        "default": "",
                        "description": "",
                        "format": null,
                        "title": "Input 1",
                        "type": "string",
                        "value": "0"
                    },
                    "Input2": {
                        "default": "",
                        "description": "",
                        "format": null,
                        "title": "Input2",
                        "type": "string",
                        "value": ""
                    }
                },
                "type": "object"
            }
        },
        "outputs": {
            "schema": {
                "properties": {
                    "Output1": {
                        "default": "",
                        "description": "",
                        "format": null,
                        "title": "Output",
                        "type": "string",
                        "value": null
                    }
                },
                "type": "object"
            }
        }
    },
    "schemaversion": "ROBIN_20211012",
    "targets": {
        "schema": {
            "properties": {},
            "type": "object"
        }
    }
}

รับสถานะของการเรียกใช้โฟลว์เดสก์ท็อป

Dataverse เก็บการเรียกใช้โฟลว์เดสก์ท็อปทั้งหมดใน เอนทิตีเซสชันโฟลว์

ร้องขอสถานะของการเรียกใช้โฟลว์เดสก์ท็อป

Authorization: Bearer eyJ0eXAiOi...
Accept: application/json

GET https://[Organization URI]/api/data/v9.2/flowsessions([Flow session ID])?$select=statuscode,statecode,startedon,completedon HTTP/1.1  

ตอบสนองต่อสถานะของการเรียกใช้โฟลว์เดสก์ท็อป

{
    "@odata.context": "https://[Organization URI]/api/data/v9.2/$metadata#flowsessions(statuscode,statecode,startedon,completedon)/$entity",
    "@odata.etag": "W1276122",
    "statuscode": 8,
    "statecode": 0,
    "startedon": "2022-06-16T12:54:40Z",
    "completedon": "2022-06-16T12:57:46Z",
}

รับผลลัพธ์โฟลว์เดสก์ท็อป

ถ้าโฟลว์เดสก์ท็อปมีเอาต์พุต คุณสามารถสอบถามฟิลด์เอาต์พุตเพื่อเรียกข้อมูลเหล่านั้นได้

ร้องขอเอาต์พุตของโฟลว์เดสก์ท็อป

Authorization: Bearer eyJ0eXAiOi...
Accept: application/json

GET https://[Organization URI]/api/data/v9.2/flowsessions([Flow session ID])/outputs/$value HTTP/1.1  

ตอบสนองต่อคำขอรับเอาต์พุตของโฟลว์เดสก์ท็อป

{
    "Output1": "My output value"
}

ทริกเกอร์การเรียกใช้โฟลว์เดสก์ท็อป

โดยการใช้ Dataverse คุณสามารถเพิ่มฟังก์ชันการทำงานของการทริกเกอร์โฟลว์เดสก์ท็อปผ่านแอปพลิเคชันของคุณได้ ในการใช้ฟังก์ชันนี้ คุณต้องใช้ การดำเนินการ RunDesktopFlow

ในการเรียกการดำเนินการ คุณต้องมีข้อมูลต่อไปนี้

• ID ของโฟลว์เดสก์ท็อปที่คุณต้องการเรียกใช้ คุณสามารถรับ ID นี้ผ่าน API เป็นส่วนสรุป รายการโฟลว์เดสก์ท็อปที่พร้อมใช้งาน ตอนต้นในบทความนี้

  Tip

  อีกวิธีหนึ่ง คุณสามารถดึง ID ด้วยตนเองจาก URL รายละเอียดโฟลว์เดสก์ท็อปใน Power Automate รูปแบบ URL คือ: https://flow.microsoft.com/manage/environments/[Environment ID]/uiflows/[Desktop Flow ID]/details

  สำหรับข้อมูลเพิ่มเติม ดูที่ จัดการโฟลว์เดสก์ท็อป

• name ของการเชื่อมต่อโฟลว์เดสก์ท็อป (กำหนดเครื่อง/กลุ่มเครื่องเป้าหมาย) เพื่อใช้ในการเรียกใช้โฟลว์ของคุณ สามารถเรียกชื่อได้จาก URL ของหน้าการเชื่อมต่อเดียวกันใน Power Automate รูปแบบ URL คือ:
  https://flow.microsoft.com/manage/environments/[Environment ID]/connections?apiName=shared_uiflow&connectionName=[Connection Name]

  Note

  สำหรับข้อมูลเพิ่มเติม ดูที่ สร้างการเชื่อมต่อโฟลว์เดสก์ท็อป

  Tip

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

  สำหรับข้อมูลเพิ่มเติม ดูที่ ใช้การอ้างอิงการเชื่อมต่อในโซลูชัน และ การอ้างอิงตาราง/เอนทิตี connectionreference

คำขอเพื่อทริกเกอร์โฟลว์เดสก์ท็อป

Authorization: Bearer eyJ0eXAiOi...
Accept: application/json

POST https://[Organization URI]/api/data/v9.2/workflows([Workflow ID])/Microsoft.Dynamics.CRM.RunDesktopFlow HTTP/1.1  
{
    "runMode": "attended",
    "runPriority": "normal",
    "connectionName": "[Connection Name]",
    "timeout": 7200,
    "inputs": "{\"Input1\":\"Value\", \"Input2\":\"Value\"}"
}

ขอให้ทริกเกอร์โฟลว์เดสก์ท็อปด้วยการอ้างอิงการเชื่อมต่อ

Authorization: Bearer eyJ0eXAiOi...
Accept: application/json

POST https://[Organization URI]/api/data/v9.2/workflows([Workflow ID])/Microsoft.Dynamics.CRM.RunDesktopFlow HTTP/1.1  
{
    "runMode": "attended",
    "runPriority": "normal",
    "connectionName": "[Connection Reference Logical Name]",
    "connectionType": 2,
    "timeout": 7200,
    "inputs": "{\"Input1\":\"Value\", \"Input2\":\"Value\"}"
}

ตอบสนองจากคำขอเพื่อทริกเกอร์โฟลว์เดสก์ท็อป

{
    "@odata.context": "https://[Organization URI]/api/data/v9.2/$metadata#Microsoft.Dynamics.CRM.RunDesktopFlowResponse",
    "flowsessionId": "d9687093-d0c0-ec11-983e-0022480b428a"
}

Warning

เมื่อใช้ API มีข้อจำกัดบางประการที่ควรทราบ:

• เมื่อทริกเกอร์การเรียกใช้โฟลว์เดสก์ท็อปโดยใช้ API อินพุตของสคริปต์จะไม่สามารถดูได้ในหน้ารายละเอียดการเรียกใช้บนพอร์ทัล Power Automate

• เจ้าของเซสชันโฟลว์ที่แสดงถึงการเรียกใช้ถูกแมปกับเจ้าของเอนทิตีเวิร์กโฟลว์ที่แสดงโฟลว์เดสก์ท็อป มีข้อจำกัดบางประการเมื่อเรียกใช้ API บนเวิร์กโฟลว์ที่มีสิทธิ์การใช้งาน "ผู้ใช้": การยกเลิกการเรียกใช้และการสอบถามสถานะอาจถูกบล็อกเนื่องจากไม่มีสิทธิ์การใช้งานในเซสชันของโฟลว์

• การเลียนแบบ Dataverse ไม่ได้รับการสนับสนุน

รับการแจ้งเตือนเมื่อสคริปต์เสร็จสิ้น

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

ได้รับคำขอโดยตำแหน่งข้อมูลการติดต่อกลับ

User-Agent: EnterpriseConnectors/1.0
Content-type: application/json; charset=utf-8
x-ms-workflow-id: [Workflow ID]
x-ms-run-id: [Flow session ID]

POST [yourCallbackURL]  

{
    "statuscode": 4,
    "statecode": 0,
    "startedon": "2022-09-05T08:04:11Z",
    "completedon": "2022-09-05T08:04:41Z",
    "flowsessionid": "d9687093-d0c0-ec11-983e-0022480b428a"
}

หากไม่มีพารามิเตอร์ URL ติดต่อกลับ สถานะโฟลว์เซสชันควรถูกสำรวจจาก Dataverse (อ้างถึง รับสถานะของการเรียกใช้โฟลว์เดสก์ท็อป)

Note

• คุณยังสามารถใช้การสำรวจสถานะเป็นกลไกทางเลือกได้ แม้ว่าคุณจะระบุพารามิเตอร์ URL ติดต่อกลับ
• การดำเนินการตำแหน่งข้อมูล URL ติดต่อกลับของคุณควรเป็นเหตุเป็นผล
• คำขอ POST จะถูกลองใหม่สามครั้งด้วยช่วงเวลาหนึ่งวินาที ถ้าตำแหน่งข้อมูลของคุณตอบสนองด้วยการตอบสนองข้อผิดพลาดของเซิร์ฟเวอร์ (รหัส 500 ขึ้นไป) หรือการตอบสนอง "คำขอหมดเวลา" (รหัส 408)

ข้อกำหนดสำหรับพารามิเตอร์ URL ติดต่อกลับ

• เซิร์ฟเวอร์ของคุณต้องมี TLS และชุดรหัส ปัจจุบัน

• อนุญาตเฉพาะโปรโตคอล HTTPS เท่านั้น

• ไม่อนุญาตให้เข้าถึง localhost (loopback)

• ใช้ที่อยู่ IP ไม่ได้ คุณต้องใช้ที่อยู่เว็บที่มีชื่อซึ่งต้องมีการแก้ไขชื่อ DNS

• เซิร์ฟเวอร์ของคุณต้องอนุญาตการเชื่อมต่อจาก ค่าที่อยู่ IP ของ Power Platform และบริการ Dynamics 365 ที่ระบุภายใต้แท็กบริการ AzureCloud

  Tip

  เนื่องจากการติดต่อกลับไม่ได้รับการยืนยัน จึงควรระมัดระวังเป็นพิเศษ

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

ยกเลิกการเรียกใช้โฟลว์เดสก์ท็อป

คล้ายกับฟังก์ชัน ทริกเกอร์ คุณยังสามารถยกเลิกโฟลว์เดสก์ท็อปที่เข้าคิว/รันอยู่ได้ หากต้องการยกเลิกโฟลว์เดสก์ท็อป ให้ใช้ การดำเนินการ CancelDesktopFlowRun

คำขอเพื่อยกเลิกการเรียกใช้ร์โฟลว์เดสก์ท็อป

Authorization: Bearer eyJ0eXAiOi...
Accept: application/json

POST https://[Organization URI]/api/data/v9.2/flowsessions(d9687093-d0c0-ec11-983e-0022480b428a)/Microsoft.Dynamics.CRM.CancelDesktopFlowRun HTTP/1.1  

ตอบสนองจากคำขอเพื่อยกเลิกโฟลว์เดสก์ท็อป

HTTP/1.1 204 No Content

ข้อผิดพลาด

เมื่อเกิดข้อผิดพลาด การตอบสนองจะมีรูปแบบต่างๆ ที่ตรงกับข้อความแสดงข้อผิดพลาด Dataverse รหัสข้อผิดพลาด http และข้อความควรให้ข้อมูลที่เพียงพอเพื่อทำความเข้าใจปัญหา

HTTP/1.1 403 Forbidden

{
    "error": {
        "code": "0x80040220",
        "message": " Principal user (Id=526..., type=8) is missing prvReadworkflow privilege (Id=88...*)”
    }
}

Note

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

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