Työpöytätyönkulkujen käsitteleminen koodin avulla

Artikkeli
11/23/2022

Kehittäjät voivat lisätä sovelluksiin työpöytätyönkulkujen toimintoja, mukaan lukien työpöytätyönkulkujen ohjelmallinen käynnistäminen ja peruuttaminen. Nämä ominaisuudet ovat osa Microsoft Dataverse -ympäristöä.

Edellytykset

Dataversen verkon ohjelmointirajapinnan tietämys, todentaminen Dataversen avulla ja OAuthin käyttäminen Dataversen avulla.
Dataverse-ympäristön tietämys ja organisaation käsitykset sekä miten organisaation URL-osoite noudetaan manuaalisesti tai ohjelmoidusti.
Työpöytätyönkulkujen käsitysten tietämys ja tieto siitä, mitä yhteydet ovat ja miten niitä luodaan.

Important

Tässä artikkelissa URL-osoitteiden kaikki hakasulkeet [...] ja syöttö-/tulostiedot, joilla on skenaariota koskevia arvoja, on korvattava.

Saatavilla olevien työpöytätyönkulkujen luettelo

Kaikki Dataversen työpöytätyönkulkujen komentosarjat ovat osa työnkulkuentiteettiä.

Suodata työnkulkuluettelot luokan perusteella työpöytätyönkulkujen tunnistamiseksi.

Työpöytätyönkulkujen noutopyyntö

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

Työpöytätyönkulkujen noutopyynnön vastaus

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

Työpöytätyönkulkujen rakenteen nouto

Jos haluat noutaa työnkulun rakenteen syöttöjä ja/tai tuloksia varten, voit käyttää kohdetyönkulun clientData-kenttää.

Työpöytätyönkulkujen rakenteen pyyntö

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

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

Työpöytätyönkulkujen rakenteen noutopyynnön vastaus

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

Työpöytätyönkulun suorituksen tilan nouto

Dataverse tallentaa kaikki työpöytätyönkulkujen suoritukset flowsession-entiteettiin.

Työpöytätyönkulun suorituksen tilan pyyntö

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

Työpöytätyönkulun suorituksen tilan vastaus

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

Työpöytätyönkulun tulosten nouto

Jos työpöytätyönkululla on tuloksia, voit tehdä kyselyn tulosten kentästä ja noutaa ne.

Työpöytätyönkulkujen tulosten pyyntö

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

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

Työpöytätyönkulkujen tulosten pyynnön vastaus

{
    "Output1": "My output value"
}

Työpöytätyönkulun suorituksen käynnistäminen

Dataversen avulla voit lisätä toimintoja, jotka käynnistävät työpöytätyönkulun sovelluksessa. Sinun täytyy käyttää tämän ominaisuuden toteuttamiseen RunDesktopFlow-toimintoa.

Jos haluat kutsua toimintoa, tarvitset seuraavat tiedot.

Suoritettavan alityöpöytätyönkulun ID. Voit hakea tämän tunnuksen ohjelmointirajapinnan avulla, kuten Saatavilla olevien työpöytätyönkulkujen luettelo -osassa aiemmin tässä artikkelissa kerrotaan.

Tip

Vaihtoehtoisesti voit noutaa tunnuksen manuaalisesti työpöytätyönkulun tietojen URL-osoitteesta Power Automatessa. URL-osoitteen muoto on seuraava: https://flow.microsoft.com/manage/environments/[Environment ID]/uiflows/[Desktop Flow ID]/details.

Lisätietoja on kohdassa Työpöytätyönkulkujen hallinta.
Työpöytätyönkulun yhteyden (kohteena kone/koneryhmä) name, jota käytetään työnkulun suorittamisessa. Nimi voidaan noutaa Power Automaten saman yhteyssivun URL-osoitteesta. URL-osoitteen muoto on seuraava:
https://flow.microsoft.com/manage/environments/[Environment ID]/connections?apiName=shared_uiflow&connectionName=[Connection Name].

Note

Lisätietoja on kohdassa Luo työpöytätyönkulkujen yhteyksiä.

Tip

Voit käyttää yhteyden syötteenä vaihtoehtoisesti yhteysviitteen loogista nimeä yhteyden nimen sijaan (käyttöesimerkki kuvattu alla kuvattu). Yhteysviitteet tallennetaan Dataverse-taulukkoon connectionreference, ja niistä voidaan laatia luettelo ohjelmallisesti samalla tavalla kuin työpöytätyönkuluista, niin kuin Saatavilla olevien työpöytätyönkulkujen luettelo -osiossa on kuvattu.

Lisätietoja on kohdassa Yhteysviitteen käyttö ratkaisussa ja connectionreference-taulukon/entiteetin viiteoppaassa.

Työpöytätyönkulun käynnistyspyyntö

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

Työpöytätyönkulun käynnistämisen pyytäminen yhteysviitteellä

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

Työpöytätyönkulun käynnistyspyynnön vastaus

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

Warning

Ohjelmointirajapintaa käytettäessä on joitakin rajoituksia, jotka tulee huomioida:

Kun käynnistät työpöytätyönkulun käyttämällä ohjelmointirajapintaa, komentosarjan syötteitä ei voi tarkastella suorituksen tietosivulta Power Automate -portaalissa.
Suoritusta edustavan työnkulkuistunnon omistaja on yhdistetty työpöytätyönkulkua edustavan työnkulkuentiteetin omistajaan. Ohjelmointirajapinnan kutsumisessa työnkululle on joitakin rajoituksia käyttäjän käyttöoikeuksilla: suorituksen peruuttaminen ja tilan noutaminen saatetaan estää, jos työnkulkuistunnon käyttöoikeudet puuttuvat.
Dataverse-tekeytymistä ei tueta.

Komentosarjan valmistumista koskevan ilmoituksen vastaanottaminen

RunDesktopFlow-toiminnon rungossa on käytettävissä valinnainen parametri nimeltään "callbackUrl". Voit käyttää sitä, jos haluat saada ilmoituksen komentosarjan valmistumisesta. Annettuun URL-osoitteeseen lähetetään POST-pyyntö, kun komentosarja on valmis.

Vastakutsun päätepisteen vastaanottama pyyntö

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

Jos vastakutsun URL-parametria ei ole annettu, työnkulkuistunnon tila on noudettava Dataversestä (katso lisätietoja kohdasta Työpöytätyönkulun suorituksen tilan nouto).

Note

Voit edelleen käyttää tilan kyselyä varamekanismina, vaikka antaisit vastakutsun URL-parametrin.
Vastakutsun päätepisteen toiminnon tulisi olla idempotenttinen.
POST-pyyntöä yritetään uudelleen kolme kertaa sekunnin välein, jos päätepisteesi palauttaa palvelinvirhevastauksen (koodi 500 tai suurempi) tai "Pyyntö aikakatkaistu" -vastauksen (koodi 408).

Vastakutsun URL-parametrin vaatimukset

Palvelimellasi täytyy olla ajankohtaiset TLS- ja salausohjelmistopaketit.
Vain HTTPS-protokolla sallitaan.
localhost-päätepisteen (kaikutesti) käyttö ei ole sallittu.
IP-osoitteita ei voi käyttää. Sinun täytyy käyttää nimettyä WWW-osoitetta, joka edellyttää DNS-nimen ratkaisua.
Palvelimesi täytyy sallia yhteydet Power Platform- ja Dynamics 365 -palveluiden IP-osoitearvoista, jotka on määritetty AzureCloud-palvelutunnisteessa.
Tip

Koska vastakutsua ei todenneta, joitakin varotoimia tulisi noudattaa
- Tarkista työkulkuistunnon tunnuksen kelpoisuus, kun vastakutsun ilmoitus vastaanotetaan. Dataverse on totuuden lähde.
- Toteuta tiedonsiirtorajoituksen strategia palvelinpuolella.
- Yritä rajoittaa vastakutsujen URL-osoitteiden jakamista useiden organisaatioiden välillä.

Työpöytätyönkulun suorituksen peruuttaminen

Käynnistin-toiminnon tavoin myös jonoon asetetun tai suoritettavan työpöytätyönkulun voi peruuttaa. Jos haluat peruuttaa työpöytätyönkulun, käytä CancelDesktopFlowRun-toimintoa.

Työpöytätyönkulun suorittamisen peruutuspyyntö

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

Työpöytätyönkulun peruutuspyynnön vastaus

HTTP/1.1 204 No Content

Virheet

Kun virhe ilmenee, vastauksella on erilainen muoto, joka vastaa Dataversen virhesanomia. HTTP-virhekoodissa ja -sanomassa on oltava riittävästi tietoja ongelman ymmärtämiseksi.

HTTP/1.1 403 Forbidden

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