使用代码处理桌面流
开发人员可以向他们的应用程序添加桌面流功能，包括以编程方式触发和取消桌面流。 这些功能作为 Microsoft Dataverse 平台的一部分提供。
先决条件
- 了解 Dataverse Web API、使用 Dataverse 进行身份验证以及在 Dataverse 中使用 OAuth。
- 了解 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 将所有桌面流运行存储在 flowsession 实体中。
请求桌面流运行的状态
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 手动检索 ID。 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 请求将以一秒间隔重试三次。
回叫 URL 参数的要求
您的服务器必须具有最新的 TLS 和密码套件。
仅允许 HTTPS 协议。
不允许访问本地主机（环回）。
不能使用 IP 地址。 您必须使用需要 DNS 名称解析的命名 Web 地址。
您的服务器必须允许连接到 AzureCloud 服务标记下指定的 Power Platform 和 Dynamics 365 服务 IP 地址值。
Tip
由于回叫调用未经过身份验证，因此应采取一些预防措施
- 当收到回叫通知时，检查流会话 ID 的有效性。 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...*)”
}
}