Del via

Arbeide med skrivebordsflytprosesser ved hjelp av kode

  • Artikkel

Utviklere kan legge til funksjonalitet for skrivebordsflyter i programmene, inkludert programmatisk utløsing og avbryting av flyter på skrivebordet. Disse funksjonene tilbys som en del av Microsoft Dataverse-plattformen.

Forutsetning

  1. Kunnskap om Dataverse-web-API, godkjenning med Dataverse og bruk av OAuth med Dataverse.
  2. Kunnskap om Dataverse-miljø- og organisasjonsvarsler, og hvordan du henter organisasjonens URL-adresse manuelt eller programmatisk.
  3. Kunnskap om skrivebordsflyter og varsler og hva tilkoblinger er og hvordan de opprettes.

Important

I denne artikkelen må du erstatte alle klammeparenteser [...] i URL-adresser og inndata/utdata med verdier som er spesifikke for ditt scenario.

Liste over tilgjengelige skrivebordsflyter

Alle skrivebordsflyt finnes i Dataverse som en del av arbeidsflytenheten.

Filtrer listen over arbeidsflyter basert på kategorien for å identifisere skrivebordsflyter.

Forespørsel om å hente skrivebordsflyter

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å forespørselen om å hente skrivebordsflyter

{
    "@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 skjemaet for skrivebordsflyter

Hvis du må hente flytskjemaet for inndata og/eller utdata, kan du bruke clientData-feltet for målarbeidsflyten.

Forespørre skjema for skrivebordsflyter

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

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

Svar på forespørselen om å hente skrivebordsflytskjemaet

{
    "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 statusen for en kjøring for skrivebordsflyt

Dataverse lagrer alle skrivebordsflytkjøringer i flowsession-enheten.

Forespørre statusen for en kjøring for skrivebordsflyt

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å statusen for en kjøring for skrivebordsflyt

{
    "@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 skrivebordsflytutdata

Hvis skrivebordsflyten har utdata, kan du spørre utdatafeltet om å hente dem.

Forespørre skrivebordsflytutdata

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å forespørselen for skrivebordsflytutdata

{
    "Output1": "My output value"
}

Utløs en skrivebordsflytkjøring

Ved å bruke Dataverse kan du legge til funksjonaliteten ved å utløse en skrivebordsflyt gjennom programmet. Du må bruke RunDesktopFlow-handlingen for å kunne implementere denne funksjonaliteten.

For å kalle opp handlingen trenger du følgende informasjon.

  • ID-en til skrivebordsflyten som du vil kjøre. Du kan få denne ID-en via API-en, som delen Liste over tilgjengelige skrivebordsflyter tidligere i denne artikkelen.

    Tip

    Du kan også hente IDen manuelt fra URL-adressen detaljer for skrivebordsflyt i Power Automate. URL-formatet er: https://flow.microsoft.com/manage/environments/[Environment ID]/uiflows/[Desktop Flow ID]/details.

    Se Behandle skrivebordsflyter hvis du vil ha mer informasjon.

  • name for skrivebordsflyttilkoblinen (målrett en maskin/maskingruppe) som skal brukes til å kjøre flyten. Navnet kan hentes fra URL-adressen til den samme tilkoblingssiden i Power Automate. URL-formatet er:
    https://flow.microsoft.com/manage/environments/[Environment ID]/connections?apiName=shared_uiflow&connectionName=[Connection Name].

    Note

    Hvis du vil ha mer informasjon, kan du se Opprett skrivebordsflyttilkoblinger.

    Tip

    Du kan også bruke det logiske navnet til en tilkoblingsreferanse som inndata for tilkoblingen i stedet for tilkoblingsnavnet (brukseksempel beskrevet nedenfor). Tilkoblingsreferansene lagres i tilkoblingsreferansen for Dataverse-tabellen og kan vises programmatisk på samme måte som skrivebordsflyter som er detaljisert i delen Liste over tilgjengelige skrivebordsflyter.

    Se Bruke en tilkoblingsreferanse i en løsning og connectionreference-tabell-/enhetsreferanse hvis du vil ha mer informasjon.

Forespørsel om å utløse en skrivebordsflyt

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

Forespørsel om å utløse en skrivebordsflyt med en tilkoblingsreferanse

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 forespørsel om å utløse en skrivebordsflyt

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

Warning

Når du bruker API-en, er det noen begrensninger du må være klar over:

  • Når en flyt for stasjonær datamaskin utløses ved hjelp av API, kan ikke skriptets inndata vises på siden for kjøringsdetaljer på Power Automate-portal.

  • Eieren av flytøkten som representerer kjøringen, tilordnes eieren av arbeidsflytenheten som representerer flyten på skrivebordet. Det finnes noen begrensninger når du kaller API-en i en arbeidsflyt med brukerrettigheten Bruker: Annullering av kjøringen og spørring av statusen kan være blokkert for manglende rettigheter i flytøkten.

  • Dataverse-representasjon støttes ikke.

Motta varsel ved fullføring av skript

Den valgfrie parameteren callbackUrl er tilgjengelig i brødteksten i handlingen RunDesktopFlow. Du kan bruke den hvis du vil bli varslet om at skriptet er fullført. En POST-forespørsel sendes til den angitte nettadressen når skriptet er fullført.

Forespørsel mottatt av endepunktet for returoppkall

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 ingen parameter for nettadresse for returoppkall angis, må statusen for flytøkten avspørres fra Dataverse (henviser til Hente statusen for en kjøring for skrivebordsflyt).

Note

  • Du kan fortsatt bruke statusavspørringen som en reservemekanisme, selv om du angir en parameter for nettadresse for returoppkall.
  • Operasjonen for endepunktet for returoppkall skal være idempotent.
  • POST-forespørselen blir forsøkt på nytt tre ganger med ett sekunds intervall hvis endepunkt svarer med en serverfeil (kode 500 og høyere) eller svaret «Forespørselen ble tidsavbrutt» (kode 408).

Krav for parameteren for nettadresse for returoppkall

  • Serveren må ha gjeldende TLS og chiffreringsserier.

  • Bare HTTPS-protokollen er tillatt.

  • Tilgang til localhost (tilbakekobling) er ikke tillatt.

  • IP-adresser kan ikke brukes. Du må bruke en navngitt nettadresse som krever DNS-navneløsning.

  • Serveren må tillate tilkoblinger fra IP-adresseverdiene for Power Platform og Dynamics 365-tjenester som er angitt under AzureCloud-servicemerket.

    Tip

    Siden returoppkallet ikke er godkjent, må du ta noen forholdsregler

    • Kontroller validiteten til flytøkt-ID-en når du mottar varselet om returoppkall. Dataverse er sannhetskilden.
    • Implementer en frekvensgrensestrategi på serversiden.
    • Prøv å begrense deling av nettadresse for returoppkall mellom flere organisasjoner.

Avbryt en skrivebordsflytkjøring

På samme måte som Utløser-funksjonaliteten, kan du også avbryte en flyt som kjører / er i kø på skrivebordet. Hvis du vil avbryte en skrivebordsflyt, bruker du handlingen CancelDesktopFlowRun.

Forespørsel om å avbryte en skrivebordsflytkjøring

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 en forespørsel for å avbryte en skrivebordsflyt

HTTP/1.1 204 No Content

Feil

Når det oppstår en feil, har svaret et annet format som samsvarer med Dataverse-feilmeldinger. HTTP-feilkoden og meldingen bør gi nok informasjon til at den forstår problemet.

HTTP/1.1 403 Forbidden

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

Note

Kan du fortelle oss om språkinnstillingene for dokumentasjonen? Ta en kort undersøkelse. (vær oppmerksom på at denne undersøkelsen er på engelsk)

Undersøkelsen tar rundt sju minutter. Det blir ikke samlet inn noen personopplysninger (personvernerklæring).