Werken met bureaubladstromen met behulp van code
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
- Kennis van Web-API van Dataverse, verificatie met Dataverse en OAuth gebruiken met Dataverse.
- Kennis van begrippen van Dataverse-omgeving en -organisatie en hoe de organisatie-URL kan worden opgehaald handmatig of via een programma.
- 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
IDvan 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
namevan 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).
Feedback
Binnenkort: Gedurende 2024 worden GitHub Issues uitgefaseerd als het feedbackmechanisme voor inhoud. Dit wordt vervangen door een nieuw feedbacksysteem. Ga voor meer informatie naar: https://aka.ms/ContentUserFeedback.
Feedback verzenden en bekijken voor