Praca z przepływami pulpitu przy użyciu kodu

Artykuł
11/23/2022

Programiści mogą dodawać do swoich aplikacji funkcje przepływy pulpitu, w tym programowo wyzwalać i anulować przepływy pulpitu. Te możliwości są oferowane jako część platformy Microsoft Dataverse.

Wymagania wstępne

Znajomość Dataverse Web API, uwierzytelnianie z Dataverse oraz używanie OAuth z Dataverse.
Znajomość środowiska Dataverse i pojęć związanych z organizacją oraz jak pobrać adres URL organizacji ręcznie lub programowo.
Wiedza o pojęciach przepływu pulpitu i o tym, czym są połączenia i jak je tworzyć.

Important

W tym artykule musisz zastąpić wszystkie nawiasy kwadratowe [...] w adresach URL i danych wejściowych/wyjściowych wartościami właściwymi dla twojego scenariusza.

Lista dostępnych przepływów na pulpicie

Wszystkie skrypty przepływu pulpitu są w Dataverse jako część encje przepływu pracy.

Filtruj listę przepływów pracy na podstawie kategorii, aby zidentyfikować przepływy dla komputerów stacjonarnych.

Prośba o uzyskanie przepływów na pulpicie

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

Odpowiedź na żądanie uzyskania przepływu pulpitu

{
    "@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",
        }
    ]
}

Uzyskiwanie schematu dla przepływów pulpitu

Jeśli chcesz pobrać schemat przepływu dla wejść i/lub wyjść, możesz użyć pola clientData dla docelowego przepływu pracy.

Schemat żądania dla przepływów pulpitu

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

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

Odpowiedź na żądanie uzyskania schematu przepływu pulpitu

{
    "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"
        }
    }
}

Uzyskaj status uruchomionego przepływu pulpitu

Dataverse przechowuje wszystkie przepływy pulpitu w encji flowsession.

Zapytaj o status uruchomionego przepływu pulpitu

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

Odpowiedź dotycząca statusu przepływu pulpitu

{
    "@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",
}

Pobierz dane wyjściowe przepływu pulpitu

Jeśli przepływ pulpitu ma wyjścia, możesz zapytać o pole wyjść, aby je pobrać.

Żądanie wyjścia z przepływu pulpitu

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

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

Odpowiedź na prośbę o udostępnienie danych wyjściowych z pulpitu

{
    "Output1": "My output value"
}

Uruchamianie wyzwalania przepływu pulpitu

Korzystając z Dataverse, możesz dodać funkcjonalność wyzwalania przepływu pulpitu przez swoją aplikację. Aby wdrożyć tę funkcję, należy użyć akcji RunDesktopFlow.

Aby wywołać akcję, będziesz potrzebował następujących informacji.

ID przepływu na pulpicie, który chcesz uruchomić. Możesz uzyskać ten identyfikator poprzez API, jak to opisano w sekcji Lista dostępnych przepływów pulpitu wcześniej w tym artykule.

Tip

Możesz też pobrać ID ręcznie z adresu URL szczegółów przepływu pulpitu w Power Automate. Format URL to: https://flow.microsoft.com/manage/environments/[Environment ID]/uiflows/[Desktop Flow ID]/details.

Aby uzyskać więcej informacji, zobacz Zarządzanie przepływami pulpitu.
name połączenia z desktop flow (maszyna docelowa/grupa maszyn), które ma być użyte do uruchomienia przepływu. Nazwa może zostać pobrana z adresu URL tej samej strony połączenia w Power Automate. Format URL to:
https://flow.microsoft.com/manage/environments/[Environment ID]/connections?apiName=shared_uiflow&connectionName=[Connection Name].

Note

Aby uzyskać więcej informacji, zobacz Tworzenie połączeń przepływu pulpitu.

Tip

Alternatywnie można użyć nazwy logicznej odwołania do połączenia jako danych wejściowych połączenia zamiast nazwy połączenia (przykład użycia opisany poniżej). Odniesienia do połączeń są przechowywane w odniesieniach do tabeli Dataverse i mogą być wyświetlane programowo w taki sam sposób, jak przepływy pulpitu opisane szczegółowo w sekcji Lista dostępnych przepływów pulpitu

Aby uzyskać więcej informacji, zobacz Użyj odniesienia do połączenia w rozwiązaniu i tabela referencyjna połączenia/odniesienie do encji

Żądanie wyzwolenia przepływu pulpitu

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\"}"
}

Żądanie uruchomienia przepływu pulpitu z referencją połączenia

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\"}"
}

Odpowiedź na żądanie uruchomienia przepływu pulpitu

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

Warning

Podczas korzystania z interfejsu API istnieją pewne ograniczenia, o których należy pamiętać:

Podczas wyzwalania uruchomienia przepływu na pulpicie przy użyciu interfejsu API dane wejściowe skryptu nie są widoczne na stronie szczegółów uruchomienia w portalu Power Automate.
Właściciel sesji przepływu reprezentującej przebieg jest mapowany na właściciela encji przepływu pracy reprezentującej przepływ pulpitu. Podczas wywoływania interfejsu API w przepływie pracy z uprawnieniem „Użytkownik” będą występować pewne ograniczenia: Anulowanie uruchomienia i sprawdzenie stanu może zostać zablokowane z powodu braku uprawnień w sesji przepływu.
Personifikacja Dataverse nie jest obsługiwana.

Otrzymanie powiadomienia o zakończeniu skryptu

Opcjonalny parametr „callbackUrl” jest dostępny w akcji RunDesktopFlow. Można jej użyć, aby uzyskać powiadomienie o ukończeniu skryptu. Po zakończeniu pracy skryptu do podanego adresu URL zostanie wysłane żądanie POST.

Żądanie odebrane przez punkt końcowy

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"
}

Jeśli nie podano parametru wywołania zwrotnego adresu URL, stan sesji przepływu powinien być odpytywany z Dataverse (odnosi się do Pobierz stan uruchomienia przepływu pulpitu).

Note

Nadal możesz używać sondowania stanu jako mechanizmu rezerwowego, nawet jeśli podasz parametr adresu URL wywołania zwrotnego.
Operacja wywołania punkt końcowy klienta powinna być czynnością idempotent.
Żądanie POST zostanie ponowione trzy razy z jednosekundowym interwałem, jeśli punkt końcowy odpowie odpowiedzią na błąd serwera (kod 500 i nowszy) lub odpowiedzią „Limit czasu żądania” (kod 408).

Wymagania parametru callback URL

Twój serwer musi mieć aktualne TLS i pakiety szyfrowania.
Dozwolone jest tylko protokół HTTPS.
Dostęp do hosta lokalnego (loopback) jest dozwolony.
Nie można używać adresów IP. Należy użyć nazwanego adresu sieci Web, który wymaga rozpoznawania nazw DNS.
Twój serwer musi zezwalać na połączenia z wartości adresów IP usług Power Platform i Dynamics 365 określone w tagu usługi AzureCloud.
Tip

Ponieważ wywołania telefoniczne nie są uwierzytelniane, należy podjąć jakieś działania
- Sprawdź poprawność identyfikatora sesji przepływu po odebraniu powiadomienia zwrotnego. Dataverse to źródło prawdy.
- Implementowanie strategii ograniczenia kursowego po stronie serwera.
- Spróbuj ograniczyć udostępnianie adresu URL wywołania między kilkoma organizacjami.

Anuluj uruchomienie przepływu na pulpicie

Podobnie jak w przypadku funkcji Wyzwalanie, można także anulować przepływ pulpitu w kolejce/uruchomić. Aby anulować przepływ pulpitu, należy użyć akcji CancelDesktopFlowRun.

Żądanie anulowania uruchomienia przepływu pulpitu

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

Odpowiedź na żądanie o anulowanie przepływu pulpitu

HTTP/1.1 204 No Content

Błędy

W przypadku wystąpienia błędu odpowiedź ma inny format, zgodny z komunikatami o błędach Dataverse. Kod błędu http i komunikat powinny dostarczyć wystarczających informacji, aby zrozumieć problem.

HTTP/1.1 403 Forbidden

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