Power AutomateVerkko-ohjelmointirajapinta

Kaikki työnkulut tallennetaan vastaisuudessa Common Data Serviceen, ja ne hyödyntävät monipuolista verkko-ohjelmointirajapintaa.

Tämä sisältö kattaa Power Automaten Ratkaisut-välilehteen sisältyvien työnkulkujen hallinnan. Nämä ohjelmointirajapinnat eivät tällä hetkellä tue Omat työnkulut -kohdassa olevia työnkulkuja.

HTTP-pyyntöjen luominen

Jotta voit aloittaa pyyntöjen luomisen, sinun on ensin luotava URL-osoite. Power Automaten verkko-ohjelmointirajapinnan perus-URL-osoitteen muoto: https://{Organization ID}.{Regional Subdomain}.dynamics.com/api/data/v9.1/. Kaksi parametria:

  • Organisaatiotunnus on työnkulut tallentavan ympäristön yksilöllinen nimi.

  • Alueellinen alitoimialue määräytyy ympäristön sijainnin mukaan.

Hanki nämä kaksi parametria.

  1. Siirry Power Platform -hallintakeskukseen.
  2. Valitse ympäristö, jota käytät työnkulkujesi kokoamiseen.

Työnkulun URL-osoite

  1. Kopioi organisaation tunnus ja alueen alitoimialue ympäristön URL-osoitteesta.

Työnkulun URL-osoite

Voit myös ohjelmallisesti saada luettelon käytettävissä olevista esiintymistä Hae esiintymät -menetelmän kautta verkkohallinta-ohjelmointirajapinnassa.

Jokaisen verkko-ohjelmointirajapintapyynnön Accept- ja Content-type-ylätunnisteiden arvon on oltava application/json.

Lisää lopuksi Authorization-otsikkoon Azure AD -haltijatunnus. Voit oppia hankkimaan Common Data Servicen Azure AD -haltijatunnuksen. Esimerkiksi tämä pyyntö:

GET https://org00000000.crm0.dynamics.com/api/data/v9.1/workflows
Accept: application/json
Authorization: Bearer ey...

Vastaus sisältää luettelon tässä ympäristössä olevista työnkuluista:

{
    "@odata.context": "https://org00000000.crm0.dynamics.com/api/data/v9.1/$metadata#workflows",
    "value": [{
        "@odata.etag": "W/\"12116760\"",
        "category": 5,
        "statecode": 0,
        "workflowidunique": "00000000-0000-0000-0000-000000000001",
        "workflowid" : "00000000-0000-0000-0000-000000000002",
        "createdon": "2018-11-15T19:45:51Z",
        "_ownerid_value": "00000000-0000-0000-0000-000000000003",
        "modifiedon": "2018-11-15T19:45:51Z",
        "ismanaged": false,
        "name": "Sample flow",
        "_modifiedby_value": "00000000-0000-0000-0000-000000000003",
        "_createdby_value": "00000000-0000-0000-0000-000000000003",
        "type": 1,
        "description": "This flow updates some data in Common Data Service.",
        "clientdata": "{\"properties\":{\"connectionReferences\":{\"shared_commondataservice\":{\"source\":\"NotSpecified\",\"id\":\"/providers/Microsoft.PowerApps/apis/shared_commondataservice\",\"tier\":\"NotSpecified\"}},\"definition\":{...}},\"schemaVersion\":\"1.0.0.0\"}"
    }]
}

Työnkulkujen luettelo

Kuten edellä on näytetty, voit saada työnkulkujen luettelon GET-kutsulla workflows-kohdassa. Kullakin työnkululla on monia ominaisuuksia, mutta tärkeimpiä niistä ovat seuraavat:

Ominaisuuden nimi Kuvaus
luokka Työnkulun luokka. Tyypit: 0 – perinteiset Common Data Service -työnkulut, 1 – perinteiset Common Data Service -valintaikkunat, 2 – liiketoimintasäännöt, 3 – perinteiset Common Data Service -toiminnot, 4 – liiketoimintaprosessin työnkulut ja 5 – automaattiset, välittömät tai ajoitetut työnkulut.
statecode Työnkulun tila. Tila voi olla 0 – pois käytöstä tai 1 – käytössä.
workflowuniqueid Tämän työnkulkuasennuksen yksilöllinen tunnus.
workflowid Pilvityönkulun yksilöllinen tunnus kaikissa tuonneissa.
createdon Päivämäärä, jolloin työnkulku luotiin.
_ownerid_value Työnkulun omistavan käyttäjän tai työryhmän yksilöllinen tunnus. Tämä on systemusers-entiteetin tunnus Common Data Servicessä.
modifiedon Työnkulku päivitetty viimeksi.
ismanaged Ilmaisee, asennettiinko työnkulku hallitun ratkaisun kautta.
nimi Työnkululle annettu näyttönimi.
_modifiedby_value Viimeisin käyttäjä, joka päivitti työnkulkua. Tämä on systemusers-entiteetin tunnus Common Data Servicessä.
_createdby_value Käyttäjä, joka loi työnkulun. Tämä on systemusers-entiteetin tunnus Common Data Servicessä.
tyyppi Ilmaisee, onko työnkulku menneillään oleva työnkulku vai malli, jolla voidaan luoda muita työnkulkuja. 1 – työnkulku, 2 – aktivointi tai 3 – malli.
kuvaus Käyttäjän antama työnkulun kuvaus.
clientdata Objektin merkkijonokoodattu JSON, joka sisältää connectionReferences-kentät ja työnkulun määrityksen.

Voit myös pyytää tiettyjä ominaisuuksia tai suodattaa työnkulkuluettelon tavalla, joka kuvattu Common Data Service -ohjelmointirajapinnan tietojen kyselyä käsittelevässä dokumentaatiossa. Esimerkiksi tämä kysely palauttaa vain automaattiset, välittömät tai ajoitetut työnkulut, jotka ovat tällä hetkellä käytössä:

GET https://org00000000.crm0.dynamics.com/api/data/v9.1/workflows?$filter=category eq 5 and statecode eq 1
Accept: application/json
Authorization: Bearer ey...

Pilvityönkulun luominen

Suorita POST-kutsu workflows-kokoelmasta pilvityönkulun luomiseksi. Pakolliset ominaisuudet automaattisia, välittömiä ja ajoitettuja työnkulkuja varten: catogory, name, type, primaryentity ja clientdata. Käytä primaryentity-ominaisuutta none tällaisissa työnkuluissa.

Voit antaa myös description- ja statecode-ominaisuuden.

POST https://org00000000.crm0.dynamics.com/api/data/v9.1/workflows
Accept: application/json
Authorization: Bearer ey...
Content-type: application/json
{
        "category": 5,
        "statecode": 0,
        "name": "Sample flow name",
        "type": 1,
        "description": "This flow reads some data from Common Data Service.",
        "primaryentity":"none",
        "clientdata": "{\"properties\":{\"connectionReferences\":{\"shared_commondataservice\":{\"connectionName\":\"shared-commondataser-00000000-0000-0000-0000-000000000004\",\"source\":\"Invoker\",\"id\":\"/providers/Microsoft.Power Apps/apis/shared_commondataservice\"}},\"definition\":{\"$schema\": \"https:\/\/schema.management.azure.com\/providers\/Microsoft.Logic\/schemas\/2016-06-01\/workflowdefinition.json#\",\"contentVersion\": \"1.0.0.0\",\"parameters\": {\"$connections\": {\"defaultValue\": {},\"type\": \"Object\"},\"$authentication\": {\"defaultValue\": {},\"type\": \"SecureObject\"}},\"triggers\": {\"Recurrence\": {\"recurrence\": {\"frequency\": \"Minute\",\"interval\": 1},\"type\": \"Recurrence\"}},\"actions\": {\"List_records\": {\"runAfter\": {},\"metadata\": {\"flowSystemMetadata\": {\"swaggerOperationId\": \"GetItems_V2\"}},\"type\": \"ApiConnection\",\"inputs\": {\"host\": {\"api\": {\"runtimeUrl\": \"https:\/\/firstrelease-001.azure-apim.net\/apim\/commondataservice\"},\"connection\": {\"name\": \"@parameters('$connections')['shared_commondataservice']['connectionId']\"}},\"method\": \"get\",\"path\": \"\/v2\/datasets\/@{encodeURIComponent(encodeURIComponent('default.cds'))}\/tables\/@{encodeURIComponent(encodeURIComponent('accounts'))}\/items\",\"queries\": {\"$top\": 1},\"authentication\": \"@parameters('$authentication')\"}}},\"outputs\": {}}},\"schemaVersion\":\"1.0.0.0\"}"
}

Tärkein osa on clientdata, joka sisältää työnkulun käyttämät connectionReferences-kentät ja työnkulun määrityksen. connectionReferences-kentät on yhdistetty kuhunkin työnkulun käyttämään yhteyteen.

Ominaisuuksia on kolme:

Ominaisuuden nimi Kuvaus
connectionName Yksilöi yhteyden. Näet connectionName-ominaisuuden siirtymällä Yhteydet-sivulle ja kopioimalla sen sitten yhteyden URL-osoitteesta.
lähde Joko Embedded tai Invoker. Invoker on käytössä vain pikatyönkuluissa (joissa käyttäjä suorittaa työnkulun valitsemalla painikkeen) ja ilmaisee, että loppukäyttäjä antaa yhteyden. Tässä tapauksessa connectionName-ominaisuutta käytetään vain suunnitteluaikana. Jos yhteys on Embedded, se tarkoittaa, että määritetty connectionName-ominaisuus on aina käytössä.
tunnus Yhdistimen tunnus. id-ominaisuuden alussa on aina /providers/Microsoft.PowerApps/apis/. Sen jälkeen tulee yhdistimen nimi, jonka voi kopioida yhteyden URL-osoitteesta tai valitsemalla yhdistimen Yhdistimet-sivulla.

Kun olet suorittanut POST-pyynnön, saat OData-EntityId-otsikon, joka sisältää workflowid-ominaisuuden uutta työnkulkua varten.

Pilvityönkulun päivittäminen

Voit kutsua PATCH pilvityönkulussa sen päivittämiseksi, ottamiseksi käyttöön tai poistamiseksi käytöstä. Tee nämä kutsut käyttämällä workflowid-ominaisuutta. Voit esimerkiksi päivittää kuvauksen ja työnkulun omistajan seuraavalla kutsulla:

PATCH https://org00000000.crm0.dynamics.com/api/data/v9.1/workflows(00000000-0000-0000-0000-000000000002)
Accept: application/json
Authorization: Bearer ey...
Content-type: application/json
{
    "description" : "This flow will ensure consistency across systems.",
    "ownerid@odata.bind": "systemusers(00000000-0000-0000-0000-000000000005)",
}

Huomautus

Omistajan muuttamisen syntaksissa käyttää odata.bind-muotoa. Tämä tarkoittaa, että _ownerid_value-kentän suoran korjaamisen sijaan voit lisätä @odata.bindominaisuuden nimeen ja käyttää sitten tunnusta systemusers()-ominaisuuden kanssa.

Toisessa esimerkissä voit ottaa pilvityönkulun käyttöön tämän kutsun avulla:

PATCH https://org00000000.crm0.dynamics.com/api/data/v9.1/workflows(00000000-0000-0000-0000-000000000002)
Accept: application/json
Authorization: Bearer ey...
Content-type: application/json
{
    "statecode" : 1
}

Pilvityönkulun poistaminen

Poista pilvityönkulku yksinkertaisella DELETE-kutsulla:

DELETE https://org00000000.crm0.dynamics.com/api/data/v9.1/workflows(00000000-0000-0000-0000-000000000002)
Accept: application/json
Authorization: Bearer ey...

Huomautus

Et voi poistaa pilvityönkulkua, joka on käytössä. Sinun on ensin poistettava pilvityönkulku käytöstä (katso edellä oleva kohta Työnkulun päivittäminen) tai muutoin näkyviin tulee virhe: Cannot delete an active workflow definition.

Hae kaikki käyttäjät, joille pilvityönkulku on jaettu

Käyttäjien, joilla on käyttöoikeudet, luetteloinnissa käytetään Common Data Servicessä funktiota. Tässä funktiossa on yksi parametri Target:

GET https://org00000000.crm0.dynamics.com/api/data/v9.1/RetrieveSharedPrincipalsAndAccess(Target=@tid)?@tid={'@odata.id':'workflows(00000000-0000-0000-0000-000000000002)'}
Accept: application/json
Authorization: Bearer ey...

Target-parametri on JSON:n kaltainen merkkijono, jossa on yksi @odata.id-niminen ominaisuus. Korvaa työnkulun tunnus edellä olevassa esimerkissä. Se palautuksena on

{
    "@odata.context": "https://org00000000.crm0.dynamics.com/api/data/v9.1/$metadata#Microsoft.Dynamics.CRM.RetrieveSharedPrincipalsAndAccessResponse",
    "PrincipalAccesses": [
        {
            "AccessMask": "ReadAccess",
            "Principal": {
                "@odata.type": "#Microsoft.Dynamics.CRM.systemuser",
                "ownerid": "00000000-0000-0000-0000-000000000005"
            }
        }
    ]
}

Pilvityönkulun jakaminen tai jakamisen poistaminen

Voit jakaa pilvityönkulun GrantAccess-toiminnon avulla.

POST https://org00000000.crm0.dynamics.com/api/data/v9.1/GrantAccess
Accept: application/json
Authorization: Bearer ey...
Content-type: application/json
{
    "Target" : {
        "@odata.type": "Microsoft.Dynamics.CRM.workflow",
        "workflowid" : "00000000-0000-0000-0000-000000000002"
    },
    "PrincipalAccess": {
        "Principal": {
            "@odata.type" : "Microsoft.Dynamics.CRM.systemuser",
            "ownerid" : "00000000-0000-0000-0000-000000000005"
        },
        "AccessMask": "ReadAccess"
    }
}

AccessMask-parametri on kenttä, jossa on seuraavat arvot eri käyttöoikeustasoille:

Nimi Kuvaus
Ei ole Ei käyttöoikeutta.
Lukuoikeus Oikeus lukea työnkulku.
WriteAccess Oikeus päivittää työnkulkua.
DeleteAccess Oikeus poistaa työnkulku.
ShareAccess Oikeus jakaa työnkulku.
AssignAccess Oikeus muuttaa työnkulun omistajaa.

Voit yhdistää käyttöoikeudet pilkulla, esimerkiksi tarjota mahdollisuuden sekä lukea pilvityönkulku että päivittää sitä myöntämällä käyttöoikeudet ReadAccess,WriteAccess.

Voit poistaa pilvityönkulun jakamisenRevokeAccess-toiminnon avulla. Esimerkki:

POST https://org00000000.crm0.dynamics.com/api/data/v9.1/RevokeAccess
Accept: application/json
Authorization: Bearer ey...
Content-type: application/json
{
    "Target" : {
        "@odata.type": "Microsoft.Dynamics.CRM.workflow",
        "workflowid" : "00000000-0000-0000-0000-000000000002"
    },
    "Revokee": {
        "@odata.type" : "Microsoft.Dynamics.CRM.systemuser",
        "ownerid" : "00000000-0000-0000-0000-000000000005"
    }
}

RevokeAccess poistaa kaikki käyttöoikeudet, jotka on myönnetty AccessMask-toiminnossa.

Työnkulkujen vieminen

Voit viedä työnkulut .zip-tiedostoon ExportSolution-toiminnon avulla. Lisää ensiksi haluamasi työnkulut ratkaisuun.

Kun työnkulku on ratkaisussa, kutsu seuraava toiminto:

POST https://org00000000.crm0.dynamics.com/api/data/v9.1/ExportSolution
Accept: application/json
Authorization: Bearer ey...
Content-type: application/json
{
    "SolutionName" : "Awesome solution 1",
    "Managed": false
}

ExportSolution palauttaa 64-koodatun perusmerkkijonon ExportSoutionFile-ominaisuudessa.

{
    "@odata.context": "https://org00000000.crm0.dynamics.com/api/data/v9.1/$metadata#Microsoft.Dynamics.CRM.ExportSolutionResponse",
    "ExportSolutionFile": "UEsDBBQAAgAI..."
}

Voi sitten tallentaa tämän tiedoston lähteen ohjausobjektiin ja/tai käyttää minkä tahansa haluamasi version hallinta- tai jakelujärjestelmää.

Työnkulkujen tuominen

Tuo ratkaisu kutsumalla ImportSolution-toiminto.

Ominaisuuden nimi Kuvaus
OverwriteUnmanagedCustomizations Jos näiden työnkulkujen esiintymiä on Common Data Servicessa, tämän merkinnän arvoksi on määritettävä true niiden tuomiseksi. Muussa tapauksessa niitä ei korvata.
PublishWorkflows Ilmaisee, aktivoidaanko perinteiset Common Data Service -työnkulut tuotaessa. Tämä asetus ei koske muuntyyppisiä työnkulkuja.
ImportJobId Antaa uuden, yksilöllisen GUID-tunnuksen tuontityön seuraamista varten.
CustomizationFile Perus-64-koodattu zip-tiedosto, joka sisältää ratkaisun.
POST https://org00000000.crm0.dynamics.com/api/data/v9.1/ImportSolution
Accept: application/json
Authorization: Bearer ey...
Content-type: application/json
{
    "OverwriteUnmanagedCustomizations": false,
    "PublishWorkflows" : true,
    "ImportJobId" : "00000000-0000-0000-0000-000000000006",
    "CustomizationFile" : "UEsDBBQAAgAI..."
}

Koska tuonti kestään pitkään, vastaus ImportSolution-toimintoon on 204 No content. Jos haluat seurata edistymistä, voit tehdä GET-kutsun importjobs-objektissa antamalla ImportJobId-ominaisuuden , jonka sisällytettiin alkuperäiseen ImportSolution-toimintoon.

GET https://org00000000.crm0.dynamics.com/api/data/v9.1/importjobs(00000000-0000-0000-0000-000000000006)
Accept: application/json
Authorization: Bearer ey...

Tämä kutsu palauttaa tuontitoiminnon tilan, mukaan lukien progress (valmistumisprosentti), startedon ja completedon (jos tuonti päättyi).

Kun tuonti on valmis, sinun on määritettävä yhteydet työnkululle, koska connectionNames on todennäköisesti erilainen kohdeympäristössä (jos yhteyksiä on edes olemassa). Jos määrität kohdeympäristössä uusia yhteyksiä, työnkulkujen omistajan on luotava ne Power Automate -suunnittelutoiminnossa. Jos yhteydet on jo määritetty uudessa ympäristössä, voit käyttää PATCH-kutsua työnkulun clientData-ominaisuutta yhteyksien nimien osalta.