Práca s postupmi v počítačovom prostredí pomocou programovania

Článok
11/18/2022

Vývojári môžu pridať toky pracovnej plochy funkčnosť ich aplikácií, vrátane programového spúšťania a rušenia tokov pracovnej plochy. Tieto schopnosti sú ponúkané ako súčasť Microsoft Dataverse plošina.

Požiadavky

Vedomosť o Dataverse Web API,autentifikácia s Dataverse a pomocou protokolu OAuth s Dataverse.
Vedomosť o Dataverse prostredie a organizačné predstavy a ako získať webovú adresu organizácie manuálne alebo programovo.
Vedomosť o desktop tokov pojmy a z čoho spojenia a ako ich vytvoriť.

Important

V tomto článku musíte nahradiť všetky hranaté zátvorky [...] v adresách URL a vstupných/výstupných údajoch hodnotami špecifickými pre váš scenár.

Uveďte dostupné toky na pracovnej ploche

Všetky skripty tokov na pracovnej ploche sú in Dataverse ako súčasť entita pracovného toku.

Filtrujte zoznam pracovných tokov na základe kategórie a identifikujte toky pracovnej plochy.

Žiadosť o získanie tokov pracovnej plochy

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

Odpovedzte na požiadavku na získanie tokov pracovnej plochy

{
    "@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ískajte schému pre toky na pracovnej ploche

Ak potrebujete načítať schému toku pre vstupy a/alebo výstupy, pre cieľový pracovný tok môžete použiť pole clientData.

Žiadosť o schému pre toky na pracovnej ploche

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

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

Odpoveď na požiadavku získať schému tokov pracovnej plochy

{
    "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ískajte stav spustenia toku pracovnej plochy

Dataverse ukladá všetky behy pracovnej plochy v flowsession entity.

Vyžiadajte si stav behu toku pracovnej plochy

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

Odpoveď na stav behu toku pracovnej plochy

{
    "@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ískajte výstupy toku pracovnej plochy

Ak má tok pracovnej plochy výstupy, môžete dopytovať pole výstupov a získať ich.

Požiadavka na výstupy toku na pracovnej ploche

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

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

Odpoveď na požiadavku na výstupy toku pracovnej plochy

{
    "Output1": "My output value"
}

Spustite spustenie toku pracovnej plochy

Používaním Dataverse, môžete pridať funkciu spúšťania toku pracovnej plochy cez vašu aplikáciu. Na implementáciu tejto funkcie musíte použiť Akcia RunDesktopFlow.

Ak chcete vykonať akciu, budete potrebovať nasledujúce informácie.

TheID toku pracovnej plochy, ktorý chcete spustiť. Toto ID môžete získať cez API ako Uveďte dostupné toky na pracovnej ploche sekcia načrtnutá vyššie v tomto článku.

Tip

Prípadne môžete ID získať manuálne z adresy URL s podrobnosťami o postupe na pracovnej ploche Power Automate. Formát adresy URL je:https://flow.microsoft.com/manage/environments/[Environment ID]/uiflows/[Desktop Flow ID]/details.

Viac informácií nájdete v časti Spravujte toky pracovnej plochy.
Thename pripojenia toku pracovnej plochy (zacielenie na počítač/skupinu strojov), ktoré sa má použiť na spustenie toku. Názov je možné získať z adresy URL tej istej stránky pripojenia v Power Automate. Formát adresy URL je:
https://flow.microsoft.com/manage/environments/[Environment ID]/connections?apiName=shared_uiflow&connectionName=[Connection Name].

Note

Viac informácií nájdete v časti Vytvorte pripojenia toku pracovnej plochy.

Tip

Prípadne môžete použiť logický názov odkazu na pripojenie ako vstup pripojenia namiesto názvu pripojenia (príklad použitia je popísaný nižšie). Odkazy na pripojenie sú uložené v Dataverse tabuľka odkaz na pripojenie a môže byť uvedená programovo rovnakým spôsobom ako toky pracovnej plochy podrobne opísané v Uveďte dostupné toky na pracovnej ploche oddiele.

Viac informácií nájdete v časti V riešení použite odkaz na pripojenie a odkaz na tabuľku/odkaz na entitu.

Žiadosť o spustenie toku pracovnej plochy

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žiadavka na spustenie toku pracovnej plochy s odkazom na pripojenie

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

Odpoveď z požiadavky na spustenie toku pracovnej plochy

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

Warning

Pri používaní rozhrania API sú potrebné určité obmedzenia:

Pri spustení spúšťania toku na pracovnej ploche pomocou rozhrania API sa vstupy skriptu nedajú zobraziť na stránke podrobností o spustení na portáli power automate.
Vlastník relácie toku reprezentujúcej spustenie je namapovaný na vlastníka entity pracovného toku reprezentujúcej tok pracovnej plochy. Pri volaní rozhrania API v pracovnom toku s privilégiom „Používateľ“ budú existovať určité obmedzenia: Zrušenie spustenia a dotazovanie sa na stav môže byť zablokované pre chýbajúce privilégiá v relácii toku.
Dataverse odcudzenie identity nie je podporované.

Dostávať upozornenie o dokončení skriptu

V tele súboru je k dispozícii voliteľný parameter „callbackUrl“.Akcia RunDesktopFlow. Môžete ho použiť, ak chcete byť informovaní o dokončení skriptu. Po dokončení skriptu sa na zadanú adresu URL odošle požiadavka POST.

Žiadosť prijatá koncovým bodom spätného volania

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

Ak nie je zadaný žiadny parameter webovej adresy spätného volania, stav relácie toku by sa mal volať z Dataverse (odkazuje na Získajte stav spustenia toku pracovnej plochy).

Note

Zisťovanie stavu môžete stále používať ako záložný mechanizmus, aj keď zadáte parameter adresy URL spätného volania.
Vaša operácia koncového bodu spätného volania by mala byť idempotentná.
Požiadavka POST sa zopakuje trikrát s jednosekundovým intervalom, ak váš koncový bod odpovie chybovou odpoveďou servera (kód 500 a vyšší) alebo odpoveďou „Časový limit požiadavky“ (kód 408).

Požiadavky na parameter webovej adresy spätného volania

Váš server musí mať aktuálny TLS a šifrovacie súpravy.
Povolený je iba protokol HTTPS.
Prístup k localhost (loopback) nie je povolený.
IP adresy nie je možné použiť. Musíte použiť pomenovanú webovú adresu, ktorá vyžaduje preklad názvu DNS.
Váš server musí povoliť pripojenia z Power Platform Hodnoty adresy IP služieb a Dynamics 365 zadané pod značkou služby AzureCloud.
Tip

Keďže spätné volanie nie je overené, mali by sa prijať určité opatrenia
- Po prijatí upozornenia na spätné volanie skontrolujte platnosť ID relácie toku. Dataverse je zdrojom pravdy.
- Implementujte stratégiu obmedzenia rýchlosti na strane servera.
- Skúste obmedziť zdieľanie adresy URL spätného volania medzi niekoľkými organizáciami.

Zrušte spustenie toku pracovnej plochy

Podobné ako Spúšťač môžete tiež zrušiť tok pracovnej plochy vo fronte/spustený. Ak chcete zrušiť tok pracovnej plochy, použite Zrušiť akciuDesktopFlowRun.

Žiadosť o zrušenie spustenia toku pracovnej plochy

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

Odpoveď zo žiadosti o zrušenie toku pracovnej plochy

HTTP/1.1 204 No Content

Chyby

Keď sa vyskytne chyba, odpoveď má iný formát, ktorý sa zhoduje Dataverse chybové hlásenia. Kód chyby http a správa by mali poskytnúť dostatok informácií na pochopenie problému.

HTTP/1.1 403 Forbidden

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