Asztali folyamatok használata kóddal

Cikk
11/18/2022

A fejlesztők asztali folyamatok funkcióit adhatják hozzá alkalmazásaikhoz, beleértve az asztali folyamatok programozott módon történő aktiválását és megszakítását. Ezeket a képességeket a Microsoft Dataverse platform részeként kínáljuk.

Előfeltételek

A webes API Dataverse ismerete, hitelesítés az OAuth-tal és Dataverse annak használatával. Dataverse
A környezet és a Dataverse szervezet fogalmainak ismerete, valamint a szervezet URL-címének manuális vagy programozott lekérése.
Az asztali folyamatok fogalmának ismerete, valamint a kapcsolatok és azok létrehozásának módja.

Important

Ebben a cikkben le kell cserélnie az URL-címekben és a bemeneti/kimeneti adatokban található összes szögletes zárójelet az adott forgatókönyvre jellemző értékekre.

Az elérhető asztali folyamatok listázása

Az összes asztali folyamat parancsfájlja a Dataverse munkafolyamat-entitás részeként található.

Szűrje a munkafolyamatok listáját a kategória alapján az asztali folyamatok azonosításához.

Asztali folyamatok lekérésének kérése

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

Válasz az asztali folyamatok lekérésére vonatkozó kérésre

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

Az asztali folyamatok sémájának lekérte

Ha le kell kérnie a bemenetek és/vagy kimenetek folyamatsémáját, használhatja a clientData mezőt a cél munkafolyamathoz.

Séma kérése asztali folyamatokhoz

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

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

Válasz az asztali folyamatok sémájának lekérésére vonatkozó kérésre

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

Asztali folyamat futtatásának állapotának lekérte

Dataverse Az összes asztali folyamatfuttatást a FlowSession entitásban tárolja.

Asztali folyamat futtatásának állapotának kérése

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

Válasz az asztali folyamat futtatásának állapotára

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

Asztali folyamat kimeneteinek lekérte

Ha az asztali folyamat kimenetekkel rendelkezik, lekérdezheti a kimenetek mezőt azok lekéréséhez.

Asztali folyamat kimenetének kérése

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

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

Válasz az asztali folyamat kimeneteire vonatkozó kérésre

{
    "Output1": "My output value"
}

Asztali folyamat futtatásának aktiválása

A használatával Dataverse hozzáadhatja az asztali folyamat alkalmazáson keresztüli aktiválásának funkcióját. A funkció megvalósításához a DesktopFlow műveletet kell használnia.

A művelet meghívásához a következő információkra lesz szüksége.

A ID futtatni kívánt asztali folyamat. Ezt az azonosítót az API-n keresztül kaphatja meg, ahogyan azt a cikk korábbi, elérhető asztali folyamatok listája szakasz ismerteti.

Tip

Másik lehetőségként manuálisan is lekérheti az azonosítót az asztali folyamat részleteinek URL-címéről a .Power Automate Az URL formátuma: https://flow.microsoft.com/manage/environments/[Environment ID]/uiflows/[Desktop Flow ID]/details.

További információ: Asztali folyamatok kezelése.
Az name asztali folyamat kapcsolata (amely egy gép-/számítógépcsoportot céloz meg) a folyamat futtatásához. A név ugyanannak a kapcsolati oldalnak az URL-címéről kérhető le a .Power Automate Az URL formátuma a következő:
https://flow.microsoft.com/manage/environments/[Environment ID]/connections?apiName=shared_uiflow&connectionName=[Connection Name].

Note

További információ: Asztali folyamatkapcsolatok létrehozása.

Tip

Azt is megteheti, hogy a kapcsolatnév helyett a kapcsolathivatkozás logikai nevét használja a kapcsolat bemeneteként (az alábbiakban ismertetett használati példa). A kapcsolathivatkozások a Dataverse táblahivatkozásban vannak tárolva, és programozott módon ugyanúgy felsorolhatók, mint az elérhető asztali folyamatok listázása szakaszban részletezett asztali folyamatok .

További információ: Kapcsolathivatkozás használata megoldásban és connectionreference tábla/entitás referenciája.

Asztali folyamat aktiválására vonatkozó kérés

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

Asztali folyamat aktiválására vonatkozó kérés kapcsolathivatkozással

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

Válasz az asztali folyamat aktiválására irányuló kérésre

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

Warning

Az API használatakor figyelembe kell venni néhány korlátozást:

Amikor az API-val indít el egy asztali folyamatot, a szkript bemenetei nem tekinthetők meg a power automate portál futtatás részletei oldalán.
A futtatást képviselő folyamat-munkamenet tulajdonosa az asztali folyamatot képviselő munkafolyamat-entitás tulajdonosára van leképezve. Az API "Felhasználó" jogosultsággal rendelkező munkafolyamaton való hívásakor bizonyos korlátozások lesznek érvényben: A futtatás megszakítása és az állapot lekérdezése blokkolva lehet a folyamat-munkamenet hiányzó jogosultságai miatt.
Dataverse A megszemélyesítés nem támogatott.

Értesítés fogadása a szkript befejezéséről

A "callbackUrl" opcionális paraméter a RunDesktopFlow művelet törzsében érhető el. Akkor használhatja, ha értesítést szeretne kapni a szkript befejezéséről. A szkript befejezésekor a rendszer POST kérést küld a megadott URL-címre.

A visszahívási végpont kapott kérés

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

Ha nincs megadva visszahívási URL-paraméter, a folyamat munkamenetének állapotát a következőből Dataverse kell lekérdezni (lásd: Asztali folyamat futtatásának állapotának lekérése).

Note

Az állapotlekérdezést továbbra is használhatja tartalék mechanizmusként, még akkor is, ha visszahívási URL-paramétert ad meg.
A visszahívási végpont műveletnek idempotensnek kell lennie.
A POST kérést háromszor újrapróbálkozik egy másodperces időközönként, ha a végpont szerverhibára adott válasszal (500-as vagy újabb kód) vagy "Kérés időtúllépése" válasszal (408-as kód) válaszol.

A visszahívási URL-paraméterre vonatkozó követelmények

A kiszolgálónak az aktuális TLS- és titkosítási csomagokkal kell lennie.
Csak a HTTPS protokoll engedélyezett.
A localhost (loopback) hozzáférése nem engedélyezett.
Az IP-címek nem használhatók. Olyan elnevezett webcímet kell használnia, amely DNS-névfeloldást igényel.
A kiszolgálónak engedélyeznie kell a kapcsolatokat Power Platform és a Dynamics 365-szolgáltatások IP-címértékeit, amelyek az AzureCloud szolgáltatáscímkében vannak megadva.
Tip

Mivel a visszahívási hívás nincs hitelesítve, bizonyos óvintézkedéseket meg kell tenni
- Ellenőrizze a folyamat-munkamenet azonosítójának érvényességét a visszahívási értesítés fogadásakor. Dataverse az igazság forrása.
- Valósítson meg egy sebességkorlátozási stratégiát a kiszolgálóoldalon.
- Próbálja meg korlátozni a visszahívási URL-címek megosztását több szervezet között.

Asztali folyamat futtatásának megszakítása

Az Eseményindító funkcióhoz hasonlóan megszakíthat egy várólistán lévő/futó asztali folyamatot is. Asztali folyamat megszakításához használja a CancelDesktopFlowRun műveletet.

Asztali folyamat futtatásának megszakítására vonatkozó kérelem

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

Válasz egy asztali folyamat megszakítására vonatkozó kérésre

HTTP/1.1 204 No Content

Hibák

Hiba esetén a válasz formátuma eltér Dataverse a hibaüzenetektől. A http hibakódnak és az üzenetnek elegendő információt kell nyújtania a probléma megértéséhez.

HTTP/1.1 403 Forbidden

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