Sdílet prostřednictvím

Práce s desktopovými toky pomocí kódu

  • Článek

Vývojáři mohou přidat funkčnost desktopových toků do svých aplikací, včetně programového spouštění a rušení desktopových toků. Tyto schopnosti jsou nabízeny jako součást platformy Microsoft Dataverse.

Předpoklady

  1. Znalosti webového API Dataverse, autentizace v Dataverse a používání OAuth spolu s Dataverse.
  2. Znalosti prostředí a organizačních pojmů Dataverse a způsob získání adresy URL organizace ručně nebo programově.
  3. Znalosti pojmů desktopových toků a připojení a jejich vytvoření.

Important

V tomto článku musíte nahradit všechny hranaté závorky [...] v adresách URL a vstupních/výstupních datech hodnotami specifickými pro váš scénář.

Seznam dostupných desktopových toků

Všechny skripty desktopových toků jsou v Dataverse součástí entity pracovního postupu.

Filtrujte seznam pracovních postupů na základě kategorie a identifikujte tak desktopové toky.

Žádost o načtení desktopových toků

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

Odpověď na žádost o načtení desktopových toků

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

Získání schématu desktopových toků

Pokud potřebujete načíst schéma toku pro vstupy a/nebo výstupy, můžete pro cílový pracovní postup použít pole clientData.

Žádost o načtení schématu desktopových toků

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

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

Odpověď na žádost o načtení schématu desktopových toků

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

Získání stavu spuštění desktopových toků

Dataverse ukládá všechna spuštění desktopového toku v entitě flowsession.

Žádost o načtení stavu spuštění desktopových toků

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

Odpověď na žádost o načtení stavu spuštění desktopových toků

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

Získání výstupů desktopových toků

Pokud má desktopový tok výstupy, můžete se dotazovat na pole výstupů a načíst je.

Žádost o načtení výstupů desktopových toků

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

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

Odpověď na žádost o načtení výstupů desktopových toků

{
    "Output1": "My output value"
}

Aktivace spuštění desktopového toku

Používáním Dataverse můžete přidat funkci spouštění desktopového toku do své aplikace. K implementaci této funkce musíte použít akci RunDesktopFlow.

K volání akce potřebujete následující informace.

  • ID desktopového toku, který chcete spustit. Toto ID můžete získat prostřednictvím API, jak je popsáno v části Seznam dostupných desktopových toků dříve v tomto článku.

    Tip

    Případně můžete ID načíst ručně z adresy URL s podrobnostmi o desktopovém toku v Power Automate. Formát URL je: https://flow.microsoft.com/manage/environments/[Environment ID]/uiflows/[Desktop Flow ID]/details.

    Další informace najdete v článku Správa desktopových toků.

  • Vlastnost name připojení desktopového toku (zacílení na počítač/skupinu strojů), které chcete použít ke spuštění toku. Název lze získat z adresy URL stejné stránky připojení v Power Automate. Formát URL je:
    https://flow.microsoft.com/manage/environments/[Environment ID]/connections?apiName=shared_uiflow&connectionName=[Connection Name].

    Note

    Více informací viz Vytvoření připojení desktopového toku.

    Tip

    Alternativně můžete místo názvu připojení použít jako vstup připojení logický název informací o připojení (příklady použití popsané níže). Informace o připojení jsou uloženy v tabulce Dataverse connectionreference a mohou být programově uvedena stejným způsobem jako desktopové toky popsané v části Seznam dostupných desktopových toků.

    Další informace naleznete v části Použijte informace o připojení v řešení a reference tabulky/entity connectionreference.

Žádost o spuštění desktopového toku

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

Požadavek na spuštění desktopového toku s informací o připojení

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

Odpověď na žádost o spuštění desktopového toku

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

Warning

Při používání rozhraní API je třeba zohlednit některá omezení:

  • Při spouštění desktopového toku pomocí rozhraní API nelze vstupy skriptu zobrazit na stránce podrobností o běhu na portálu power automate.

  • Vlastník relace toku představující běh je mapován na vlastníka entity pracovního postupu představující desktopový tok. Při volání rozhraní API v pracovním postupu s oprávněním „Uživatel“ budou určitá omezení: Zrušení běhu a dotazování na stav může být zablokováno kvůli chybějícím oprávněním v relaci toku.

  • Zosobnění Dataverse podporováno.

Příjem oznámení o dokončení skriptu

V těle akce RunDesktopFlow je k dispozici volitelný parametr „callbackUrl“. Můžete ho použít, pokud chcete být informováni o dokončení skriptu. Po dokončení skriptu bude na zadanou adresu URL odeslán požadavek POST.

Požadavek přijatý koncovým bodem zpětného volání

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

Pokud není zadán žádný parametr adresy URL zpětného volání, měl by být stav relace toku dotazován z Dataverse (odkazuje na Získání stavu běhu desktopového toku).

Note

  • Dotazování stavu můžete stále používat jako záložní mechanismus, i když zadáte parametr URL zpětného volání.
  • Vaše operace koncového bodu zpětného volání by měla být idempotentní.
  • Požadavek POST bude zopakován třikrát s jednosekundovým intervalem, pokud koncový bod odpoví chybovou odpovědí serveru (kód 500 a vyšší) nebo odpovědí „Časový limit požadavku“ (kód 408).

Požadavky na parametr URL zpětného volání

  • Váš server musí mít aktuální TLS a šifrovací sady.

  • Je povolen pouze protokol HTTPS.

  • Přístup k localhost (loopback) není povolen.

  • IP adresy nelze použít. Musíte použít pojmenovanou webovou adresu, která vyžaduje překlad názvů DNS.

  • Server musí povolovat připojení z hodnot IP adresy služeb Power Platform a Dynamics 365 uvedených pod značkou služby AzureCloud.

    Tip

    Vzhledem k tomu, že zpětné volání není ověřeno, je třeba přijmout určitá opatření

    • Po obdržení upozornění na zpětné volání zkontrolujte platnost ID relace toku. Dataverse je zdrojem pravdy.
    • Implementujte strategii omezení rychlosti na straně serveru.
    • Pokuste se omezit sdílení URL zpětného volání mezi několika organizacemi.

Zrušení spuštění desktopového toku

Podobně jako funkci Trigger můžete také zrušit desktopový tok zařazený ve frontě/běžící. Chcete-li zrušit desktopový tok, použijte akci CancelDesktopFlowRun.

Žádost o zrušení spouštění desktopového toku

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

Odpověď na žádost o zrušení desktopového toku

HTTP/1.1 204 No Content

Chyby

Když dojde k chybě, odpověď má jiný formát, který odpovídá chybovým zprávám Dataverse. Kód chyby HTTP a zpráva by měly poskytnout dostatek informací k pochopení problému.

HTTP/1.1 403 Forbidden

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

Note

Můžete nám sdělit, jaké máte jazykové preference pro dokumentaci? Zúčastněte se krátkého průzkumu. (upozorňujeme, že tento průzkum je v angličtině)

Průzkum bude trvat asi sedm minut. Nejsou shromažďovány žádné osobní údaje (prohlášení o zásadách ochrany osobních údajů).