Работа с классическими потоками с помощью кода

Статья
11/23/2022

Разработчики могут добавить функциональность классических потоков в свои приложения, включая программный запуск и отмену классических потоков. Эти возможности предлагаются как часть платформы Microsoft Dataverse.

Предварительные условия

Знание веб-API Dataverse, аутентификация с 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 хранит все выполнения классических потоков в сущности 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, как описано в разделе Список доступных классических потоков ранее в этой статье.

Tip

Кроме того, вы можете получить идентификатор вручную из 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

Кроме того, вы можете использовать логическое имя ссылки на подключение в качестве входных данных подключения вместо имени подключения (пример использования описан ниже). Ссылки на подключение хранятся в таблице 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 не поддерживается.

Получение уведомления о завершении скрипта

Необязательный параметр "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-адреса обратного вызова.
Ваша операция обратного вызова конечной точки должна быть идемпотентной.
Запрос POST будет повторен три раза с интервалом в одну секунду, если ваш конечная точка ответит ответом «Ошибка сервера» (код 500 и выше) или ответом «Тайм-аут запроса» (код 408).

Требования к параметру URL-адреса обратного вызова

На вашем сервере должна быть актуальные версии протокола TLS и наборов шифров.
Разрешен только протокол HTTPS.
Доступ к локальному хосту (замыкание на себя) не разрешен.
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...*)”
    }
}