Arbeta med datorflöden med hjälp av kod

Artikel
11/22/2022

Utvecklare kan lägga till funktioner för datorflöden i sina appar, inklusive datorflöden som utlöses och avbryts programmässigt. De här funktionerna ingår i Microsoft Dataverse-plattformen.

Förutsättningar

Kunskap om webb-API för Dataverse, autentisering med Dataverse och hur man använder OAuth med Dataverse.
Kunskap om Dataverse-miljön och organisationsnotationer och hur man hämtar organisationens URL manuellt eller programmässigt.
Kunskap om notationer för datorflöden och vilka anslutningar som finns och hur du skapar dem.

Important

I den här artikeln måste du ersätta alla hakparenteser [...] i URL:er och indata/utdata med värden som är specifika för ditt scenario.

Lista med tillgängliga datorflöden

Alla skript för datorflöden är i Dataverse en del av arbetsflödesentiteten.

Filtrera listan med arbetsflöden utifrån kategorin för att identifiera datorflödena.

Begär att få hämta datorflöden

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

Svar på begäran om att hämta datorflöden

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

Hämta schemat för datorflöden

Om du behöver hämta flödesschemat för indata och/eller utdata kan du använda fältet clientData för målarbetsflödet.

Begär schema för datorflöden

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

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

Svar på begäran om att hämta schema för datorflöden

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

Hämta status för körningen av ett datorflöde

Dataverse lagrar alla körningar av datorflöden i entiteten flödessession

Begär status för körningen av ett datorflöde

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

Svar på status för körningen av ett datorflöde

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

Hämta utdata från datorflöde

Om datorflödet har utdata kan du ställa frågor i utdatafältet för att hämta dem.

Begär utdata från datorflöden

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

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

Svar på begäran om utdata från datorflöden

{
    "Output1": "My output value"
}

Starta ett körning av ett datorflöde

Genom att använda Dataverse kan du lägga till funktionen att utlösa ett datorflöde via appen. För att implementera den här funktionen måste du använda RunDesktopFlow.

Om du vill anropa åtgärden behöver du följande information.

ID för datorflödet som du vill köra. Du kan hämta det här ID:t via API:et på det sätt som beskrivs i avsnittet Lista över tillgängliga datorflöden tidigare i den här artikeln.

Tip

Du kan också hämta ID:t manuellt från URL:en för datorflödesinformation i Power Automate. URL-formatet är: https://flow.microsoft.com/manage/environments/[Environment ID]/uiflows/[Desktop Flow ID]/details.

Mer information finns i Hantera datorflöden.
Det name på anslutningen för datorflödet (måldator/maskingrupp) som ska användas för att köra ditt flöde. Namnet kan hämtas från URL:en för samma anslutningssida i Power Automate. URL-formatet är:
https://flow.microsoft.com/manage/environments/[Environment ID]/connections?apiName=shared_uiflow&connectionName=[Connection Name].

Note

Mer information finns i Skapa datorflödesanslutningar.

Tip

Du kan också använda en anslutningsreferenss logiska namn som indata för anslutningen i stället för anslutningsnamnet (användningsexempel som beskrivs nedan). Anslutningsreferenserna lagras i Dataverse-tabellens anslutningsreferens och kan listas programmässigt på samma sätt som för datorflöden som beskrivs i avsnittet Ange tillgängliga datorflöden.

Mer information finns i Använda en anslutningsreferens i en lösning ochanslutningsreferenstabell/entitetsreferens.

Begär att utlösa ett datorflöde

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

Begära att utlösa ett datorflöde med en anslutningsreferens

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

Svar från begäran att utlösa ett datorflöde

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

Warning

När du använder API:et finns det vissa begränsningar att känna till:

När du utlöser ett datorflöde som körs med API, kan indata i skriptet inte visas på sidan för körningsinformation på Power Automate-portalen.
Ägaren till flödessessionen som representerar körningen mappas till ägaren av arbetsflödesentiteten som representerar datorflödet. Det finns vissa begränsningar när du anropar API i ett arbetsflöde med privilegiet Användare: Avbryta körningen och ställa frågor om status kan blockeras för saknade privilegier för flödessessionen.
Dataverse personifiering stöds inte.

Få meddelande när skriptet har slutförts

En valfri parameter "callbackUrl" finns i delen av åtgärden RunDesktopFlow. Du kan använda den om du vill få meddelanden om att ditt skript har slutförts. En POST-förfrågan skickas till url:en när skriptet har slutförts.

Förfrågan som motringning av slutpunkt

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

Om ingen återuppringningsadressparameter tillhandahålls, bör flödessessionens status hämtas från Dataverse (hänvisa till Hämta status för körningen av ett datorflöde).

Note

Du kan fortfarande använda status avsökning som en grundmekanism även om du anger en motringningsadress parameter.
Din motringningsslutpunkt ska vara iropsåtgärd.
POST-begäran kommer att försökas igen tre gånger med en sekunds intervall om din slutpunkt svarar med ett serverfelsvar (kod 500 och högre) eller ett svar på "Tidsgräns för begäran" (kod 408).

Krav för parametern för motringningsadress

Servern måste ha de aktuella TLS och chiffersvit.
Endast HTTPS-protokollet är tillåtet.
Åtkomst till localhost (loopback) är inte tillåtet.
IP-adresser kan inte användas. Du måste använda en namngiven webbadress som kräver EN DNS-namnmatchning.
Din server måste tillåta anslutningar från Power Platform och Dynamics 365 IP-adressvärden för tjänster som anges under Azure Cloud-tjänsttaggen.
Tip

När motringningssamtalet inte autentiseras bör vissa problem vidtas
- Kontrollera att flödesessionens ID är giltigt när motringningsaviseringen tas emot. Dataverse är sanningens källa.
- Implementera en taktgränsstrategi på din serversida.
- Försök att begränsa url-delningen för callback mellan flera organisationer.

Avbryt en körning av datorflöde

På samma sätt som med utlösar funktionen kan du även avbryta ett datorflöde i kö eller köra. För att avbryta ett datorflöde, använd CancelDesktopFlowRun åtgärden.

Begäran om att avbryta en datorflödeskörning

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

Svar från begäran att avbryta ett datorflöde

HTTP/1.1 204 No Content

Fel

När ett fel inträffar har svaret ett annat format som överensstämmer med Dataverse-felmeddelandena. HTTP-felkoden och meddelandet bör innehålla tillräckligt med information för att du ska förstå problemet.

HTTP/1.1 403 Forbidden

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