Arbejde med skrivebordsflow ved hjælp af kode

Artikel
11/23/2022

Udviklere kan føje funktioner for skrivebordsflow til deres programmer, herunder programmeringsmæssig udløsning og annullering af skrivebordsflow. Disse funktioner tilbydes som en del af Microsoft Dataverse-platformen.

Forudsætninger

Kendskab til Dataverse-web-API, godkendelse med Dataverse og brug af OAuth med Dataverse.
Kendskab til Dataverse-miljøer og -organisationer, og hvordan URL-adressen til organisationen hentes manuelt eller via programmering.
Viden om skrivebordsflow og hvilke forbindelser der er, og hvordan de kan oprettes.

Important

I denne artikel skal du erstatte alle kantede parenteser [...] i URL-adresser og input/output-data med værdier, der er specifikke for dit scenario.

Vise listen over skrivebordsflows

Alle scripts for skrivebordsflow er i Dataverse som en del af arbejdsprocesobjektet.

Filtrer listen over arbejdsprocesser baseret på kategorien for at identificere skrivebordsflow.

Anmode om at få skrivebordsflow

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

Svare på anmodningen om at hente skrivebordsflow

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

Hente skemaet til skrivebordsflow

Hvis du skal hente flowskemaet til input og/eller output, kan du bruge feltet clientData til målarbejdsprocessen.

Anmode om skema til skrivebordsflow

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

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

Svare på anmodningen om at hente skema til skrivebordsflow

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

Hente status for kørsel af skrivebordsflow

Dataverse gemmer alle kørsler af skrivebordsflow i flowsession-objektet.

Anmode om status for kørsel af skrivebordsflow

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

Besvare status for kørsel af skrivebordsflow

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

Hente output af skrivebordsflow

Hvis skrivebordsflowet har output, kan du forespørge på outputfeltet for at hente dem.

Anmode om output af skrivebordsflow

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

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

Svare på anmodningen om output af skrivebordsflow

{
    "Output1": "My output value"
}

Udløse et skrivebordsflow

Ved hjælp af Dataverse kan du tilføje funktionaliteten til at udløse et skrivebordsflow i dit program. Hvis du vil implementere denne funktionalitet, skal du bruge handlingen RunDesktopFlow.

Du skal have følgende oplysninger for at kalde handlingen.

ID for det skrivebordsflow, der skal køres. Du kan få dette ID via API'en, som afsnittet Vise listen over skrivebordsflows skitserer tidligere i denne artikel.

Tip

Du kan også hente id'et manuelt fra URL-adressen til oplysninger om skrivebordsflow i Power Automate. URL-formatet er: https://flow.microsoft.com/manage/environments/[Environment ID]/uiflows/[Desktop Flow ID]/details.

Du kan finde flere oplysninger i Administrere skrivebordsflow.
Det name på forbindelse til skrivebordsflow (destinationscomputer/maskingruppe), der skal bruges til at køre flowet. Navnet kan hentes fra URL-adressen til samme forbindelsesside i Power Automate. URL-formatet er:
https://flow.microsoft.com/manage/environments/[Environment ID]/connections?apiName=shared_uiflow&connectionName=[Connection Name].

Note

Du kan finde flere oplysninger under Oprette forbindelser til skrivebordsflow.

Tip

Du kan også bruge en forbindelsesreferences logiske navn som input til forbindelsen i stedet for forbindelsesnavnet (eksempel på anvendelse beskrives nedenfor). Forbindelsesreferencerne lagres i Dataverse-tabellen connectionreference og kan angives programmatisk på samme måde som skrivebordsflow, der er beskrevet i sektionen Vise listen over skrivebordsflows.

Du kan finde flere oplysninger i Bruge en forbindelsesreference i en løsning og connectionreference-tabel/objektreference.

Anmodning om at udløse et skrivebordsflow

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

Anmodning om at udløse et skrivebordsflow med en forbindelsesreference

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 fra anmodning om at udløse et skrivebordsflow

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

Warning

Når du bruger API'en, er der visse begrænsninger, du skal være opmærksom på:

Når et skrivebordsflow udløses ved hjælp af API'en, kan inputtet fra scriptet ikke vises på siden med kørselsdetaljer på Power Automate-portalen.
Ejeren af den flowsession, der repræsenterer kørslen, er knyttet til ejeren af det arbejdsprocesobjekt, der repræsenterer skrivebordsflowet. Der er visse begrænsninger, når du kalder API'en i en arbejdsproces med rettigheden "Bruger": Hvis du annullerer kørslen og forespørger om status, kan det være blokeret af manglende rettigheder til flowsessionen.
Dataverse-repræsentation understøttes ikke.

Modtage meddelelse om fuldførelse af script

Den valgfri parameter "callbackUrl" er tilgængelig i brødteksten i handlingen RunDesktopFlow. Du kan bruge den, hvis du vil have besked om, at scriptet er fuldført. Der sendes en POST-anmodning til den angivne URL-adresse, når scriptet er fuldført.

Anmodningen blev modtaget af tilbagekaldsslutpunkt

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

Hvis der ikke angives en URL-parameter for tilbagekald, skal status for flowsessionen forespørges fra Dataverse (henviser til Hent status for en kørsel af skrivebordsflow).

Note

Du kan stadig bruge status-polling som reservemekanisme, selvom du angiver en URL-parameter for tilbagekald.
Handlingen for tilbagekaldsslutpunkt skal være idempotent (give samme resultat hver gang).
POST-anmodningen vil blive forsøgt igen tre gange med ét sekunds interval, hvis slutpunktet svarer med en serverfejlrespons (kode 500 og derover) eller et "Timeout for anmodning"-svar (kode 408).

Krav til URL-parameteren for tilbagekald

Serveren skal have de aktuelle TLS- og krypteringspakker.
Det er kun HTTPS-protokollen, der er tilladt.
Adgang til localhost (loopback) er ikke tilladt.
IP-adresser kan ikke bruges. Du skal bruge en navngivet webadresse, der kræver en DNS-navnefortolkning.
Din server skal tillade forbindelser fra Power Platform og Dynamics 365-tjenesters IP-adresseværdier, der er angivet under tjenestekoden AzureCloud.
Tip

Da tilbagekaldet ikke godkendes, skal der tages visse sikkerhedsforanstaltninger
- Kontrollér flowsessions-id'et for, hvornår meddelelsen om tilbagekald modtages. Dataverse er kilden til sandheden.
- Implementer en strategi for hastighedsbegrænsning på serversiden.
- Prøv at begrænse delingen af URL-adressen for tilbagekald mellem flere organisationer.

Annullere en kørsel af skrivebordsflow

På samme måde som med funktionen Udløser kan du også annullere et skrivebordsflow, der er i kø/kører. Hvis du vil annullere et skrivebordsflow, skal du bruge handlingen CancelDesktopFlowRun.

Anmodning om at annullere en skrivebordskørsel

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 fra anmodning om at annullere et skrivebordsflow

HTTP/1.1 204 No Content

Fejl

Når der opstår en fejl, har svaret et andet format, der matcher Dataverse-fejlmeddelelser. Http-fejlkoden og meddelelsen skal indeholde tilstrækkelige oplysninger til at forstå problemet.

HTTP/1.1 403 Forbidden

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