使用程式碼處理桌面流程

發行項
11/23/2022

開發人員可以將桌面流程功能新增至其應用程式，包括以程式設計方式觸發和取消桌面流程。這些功能作為 Microsoft Dataverse 平台的一部分提供。

先決條件

了解 Dataverse Web API、使用 Dataverse 驗證和 OAuth 和 Dataverse 搭配使用
了解 Dataverse 環境和組織觀念，以及如何手動或以程式方式擷取組織 URL。
了解桌面流程概念以及連接是什麼和如何建立它們。

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。您可以透過 API 取得此 ID，如前文列出可用桌面流程的區段所述。

Tip

或者，您也可以手動從 Power Automate 的桌面流程詳細資料 URL 手動擷取 UD。 URL 格式為：https://flow.microsoft.com/manage/environments/[Environment ID]/uiflows/[Desktop Flow ID]/details。

如需詳細資訊，請參閱管理桌面流程。
用於執行流程的桌面流程連接 (針對電腦/電腦群組) 的 name。您可以從 Power Automate 中相同連接頁面的 URL 擷取該名稱。 URL 格式為：
https://flow.microsoft.com/manage/environments/[Environment ID]/connections?apiName=shared_uiflow&connectionName=[Connection Name]。

Note

如需詳細資訊，請參閱建立桌面流程連接。

Tip

或者，也可以使用連接參考的邏輯名稱做為連接輸入，而不使用連接名稱 (使用範例如下所述)。連接參考會儲存在 Dataverse 資料表 connectionreference 中，並且可以透過程式設計來列出，其方式與列出可用的桌面流程一節中詳述的桌面流程相同。

如需詳細資訊，請參閱在解決方案中使用連接參考和 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 模擬。

在指令碼完成時接收通知

在 RunDesktopFlow 動作的主體中提供可選參數 "callbackUrl"。如果想在指令碼完成時收到通知，可以使用它。當指令碼完成時，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 參數，仍然可以將狀態輪詢做為回撥機制。
您的回撥端點作業應為等冪。
如果您的端點回應伺服器錯誤回應 (代碼 500 及以上) 或「要求超時」回應 (代碼 408)，則 POST 要求將會重試三次，間隔為 1 秒。

回撥 URL 參數的需求

您的伺服器必須有目前的 TLS 和加密套件。
僅允許使用 HTTPS 通訊協定。
不允許存取 localhost (loopback)。
無法使用 IP 位址。您必須使用需要 DNS 名稱解析的命名網址。
您的伺服器必須允許來自在 Azure 雲端服務標記下指定的 Power Platform 和 Dynamics 365 服務 IP 位址值的連接。
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...*)”
    }
}