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.
- Siirry Power Platform -hallintakeskukseen.
- Valitse ympäristö, jota käytät työnkulkujesi kokoamiseen.
- Kopioi organisaation tunnus ja alueen alitoimialue ympäristön URL-osoitteesta.
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.