Delen via

Werken met bureaubladstromen met behulp van code

  • Artikel

Ontwikkelaars kunnen functionaliteit van bureaubladstromen toevoegen aan hun toepassingen, inclusief het programmatisch activeren en annuleren van bureaubladstromen. Deze mogelijkheden worden geboden als onderdeel van het Microsoft Dataverse-platform.

Vereisten

  1. Kennis van Web-API van Dataverse, verificatie met Dataverse en OAuth gebruiken met Dataverse.
  2. Kennis van begrippen van Dataverse-omgeving en -organisatie en hoe de organisatie-URL kan worden opgehaald handmatig of via een programma.
  3. Kennis van begrippen van bureaubladstromen en van wat verbindingen zijn en hoe u ze kunt maken.

Important

In dit artikel moet u alle vierkante haken [...] in URL's en invoer-/uitvoergegevens vervangen door waarden die specifiek zijn voor uw scenario.

Beschikbare bureaubladstromen weergeven

Alle scripts van bureaubladstromen zijn in Dataverse een onderdeel van de werkstroomentiteit.

Filter de lijst met werkstromen op basis van de categorie om bureaubladstromen te identificeren.

Aanvraag op bureaubladstromen op te halen

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

Respons op de aanvraag om bureaubladstromen op te halen

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

Het schema voor bureaubladstromen ophalen

Als u het stroomschema voor invoer en/of uitvoer moet ophalen, kunt u het veld clientData gebruiken voor de doelwerkstroom.

Schema voor bureaubladstromen aanvragen

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

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

Respons op de aanvraag om het schema voor bureaubladstromen op te halen

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

De status van de uitvoering van een bureaubladstroom ophalen

In Dataverse worden alle bureaubladstroomuitvoeringen opgeslagen in de stroomsessie-entiteit.

De status van de uitvoering van een bureaubladstroom aanvragen

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

Respons op de status van de uitvoering van een bureaubladstroom

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

Bureaubladstroomuitvoer ophalen

Als de bureaubladstroom uitvoer heeft, kunt u het uitvoerveld opvragen om deze op te halen.

Aanvraag voor uitvoer van bureaubladstromen

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

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

Respons op de aanvraag voor uitvoer van bureaubladstromen

{
    "Output1": "My output value"
}

De uitvoering van een bureaubladstroom activeren

Door Dataverse te gebruiken, kunt u de functionaliteit toevoegen om een bureaubladstroom via uw toepassing te activeren. Als u deze functionaliteit wilt implementeren, moet u gebruikmaken van de actie RunDesktopFlow.

Als u de actie wilt aanroepen, hebt u de volgende informatie nodig.

  • De ID van de bureaubladstroom die u wilt uitvoeren. U kunt deze id via de API verkrijgen zoals is uitgelegd in de sectie Beschikbare bureaubladstromen weergeven eerder in dit artikel.

    Tip

    U kunt de id ook handmatig ophalen uit de URL van de desktopstroomdetails in Power Automate. De URL-indeling is: https://flow.microsoft.com/manage/environments/[Environment ID]/uiflows/[Desktop Flow ID]/details.

    Zie Bureaubladstromen beheren voor meer informatie.

  • De name van de bureaubladstroomverbinding (doelcomputer/computergroep) die u wilt gebruiken om uw stroom uit te voeren. De naam kan worden opgehaald uit de URL van dezelfde verbindingspagina in Power Automate. De URL-indeling is:
    https://flow.microsoft.com/manage/environments/[Environment ID]/connections?apiName=shared_uiflow&connectionName=[Connection Name].

    Note

    Zie Bureaubladstroomverbindingen maken voor meer informatie.

    Tip

    Als alternatief kunt u de logische naam van een verbindingsverwijzing gebruiken als invoer van de verbinding in plaats van de verbindingsnaam (gebruiksvoorbeeld hieronder beschreven). De verbindingsverwijzingen worden opgeslagen in de Dataverse-tabel connectionreference en kan programmatisch worden weergegeven op dezelfde manier als bureaubladstromen die worden beschreven in de sectie Beschikbare bureaubladstromen weergeven.

    Zie Een verbindingsverwijzing gebruiken in een oplossing en tabel connectionreference/entiteitsverwijzing voor meer informatie.

Aanvraag om een bureaubladstroom te activeren

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

Verzoek om een bureaubladstroom te activeren met een verbindingsverwijzing

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

Respons op de aanvraag om een bureaubladstroom te activeren

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

Warning

Bij het gebruik van de API zijn er enkele beperkingen waarmee u rekening moet houden:

  • Bij het activeren van een uitvoering van een bureaubladstroom met behulp van de API, is de invoer van het script niet zichtbaar op de pagina met uitvoeringsdetails in de Power Automate-portal.

  • De eigenaar van de stroomsessie die de uitvoering vertegenwoordigt, wordt toegewezen aan de eigenaar van de werkstroomentiteit die de bureaubladstroom vertegenwoordigt. Er zijn enkele beperkingen bij het aanroepen van de API voor een werkstroom met het recht "gebruiker": het annuleren van de uitvoering en het opvragen van de status worden mogelijk geblokkeerd vanwege ontbrekende rechten op de stroomsessie.

  • Dataverse-imitatie wordt niet ondersteund.

Een melding ontvangen bij voltooiing van het script

Een optionele parameter "callbackUrl" is beschikbaar in de hoofdtekst van de actie RunDesktopFlow. U kunt dezegebruiken als u op de hoogte wilt worden gesteld van het voltooien van uw script. Er wordt een POST-aanvraag naar de opgegeven URL verzonden wanneer het script is voltooid.

Aanvraag ontvangen door het callback-eindpunt

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

Als er geen callback-URL-parameter is opgegeven, moet de status van de stroomsessie worden opgevraagd vanuit Dataverse (verwijst naar De status van de uitvoering van een bureaubladstroom ophalen).

Note

  • U kunt de statusopvraging nog steeds gebruiken als een terugvalmechanisme, zelfs als u een callback-URL-parameter opgeeft.
  • Uw callback-eindpuntbewerking moet idempotent zijn.
  • De POST-aanvraag wordt drie keer opnieuw geprobeerd met een interval van één seconde als uw eindpunt reageert met een respons Serverfout (code 500 en hoger) of een respons Time-out aanvragen (code 408).

Vereisten voor de callback-URL-parameter

  • Uw server moet de huidige TLS-suite en suite met coderingsmethoden bevatten.

  • Alleen het HTTPS-protocol is toegestaan.

  • Toegang tot localhost (loopback) is niet toegestaan.

  • IP-adressen kunnen niet worden gebruikt. U moet een benoemd webadres gebruiken waarvoor DNS-naamomzetting is vereist.

  • Uw server moet verbindingen vanuit IP-adreswaarden voor Power Platform- en Dynamics 365-services die zijn opgegeven onder de AzureCloud-servicetag toestaan.

    Tip

    Aangezien de terugbeloproep niet wordt geverifieerd, moeten enkele voorzorgsmaatregelen worden genomen

    • Controleer de geldigheid van de stroomsessie-id bij ontvangst van de terugbelmelding. Dataverse is de bron van waarheid.
    • Implementeer een frequentielimietstrategie aan uw serverzijde.
    • Probeer het delen van callback-URL's tussen verschillende organisaties te beperken.

De uitvoering van een bureaubladstroom annuleren

Net als bij de Trigger-functionaliteit, kunt u ook een in de wachtrij geplaatste/actieve bureaubladstroom annuleren. Gebruik de actie CancelDesktopFlowRun om een bureaubladstroom te annuleren.

Aanvraag om een actieve bureaubladstroom te annuleren

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

Respons op de aanvraag om een bureaubladstroom te annuleren

HTTP/1.1 204 No Content

Fouten

Als er een fout optreedt, heeft de respons een andere indeling die overeenkomt met Dataverse-foutmeldingen. De http-foutcode en het bericht moeten voldoende informatie bevatten om het probleem te begrijpen.

HTTP/1.1 403 Forbidden

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

Note

Laat ons uw taalvoorkeuren voor documentatie weten! Beantwoord een korte enquête. (houd er rekening mee dat deze in het Engels is)

De enquête duurt ongeveer zeven minuten. Er worden geen persoonlijke gegevens verzameld (privacyverklaring).