Power AutomateAPI Web

Στο εξής, όλες οι ροές θα αποθηκεύονται στο Dataverse και θα αξιοποιούν το εμπλουτισμένο API Web.

Αυτό το περιεχόμενο καλύπτει τη διαχείριση των ροών που περιλαμβάνονται στην καρτέλα Λύσεις στο Power Automate. Προς το παρόν, οι ροές στην περιοχή Οι ροές μου δεν υποστηρίζονται από αυτά τα API.

Σύνταξη αιτήσεων HTTP

Για να ξεκινήσετε τη δημιουργία αιτήσεων, θα πρέπει να δημιουργήσετε πρώτα τη διεύθυνση URL. Η μορφή για τη βασική διεύθυνση URL του API Web του Power Automate είναι: https://{Organization ID}.{Regional Subdomain}.dynamics.com/api/data/v9.1/. Οι δύο παράμετροι είναι οι εξής:

  • Το Αναγνωριστικό οργανισμού είναι ένα μοναδικό όνομα για το περιβάλλον που αποθηκεύει τις ροές σας.

  • Ο Τοπικός υποτομέας εξαρτάται από τη θέση του περιβάλλοντός σας.

Για να λάβετε αυτές τις δύο παραμέτρους.

  1. Μεταβείτε στο Κέντρο διαχείρισης του Power Platform.
  2. Επιλέξτε το περιβάλλον που χρησιμοποιείτε για να δημιουργήσετε τις ροές σας.

Διεύθυνση URL ροής.

  1. Αντιγράψτε το αναγνωριστικό του οργανισμού και τον δευτερεύοντα τομέα της περιοχής από τη διεύθυνση URL περιβάλλοντος.

Διεύθυνση URL ροής.

Μπορείτε επίσης, μέσω προγραμματισμού, να λάβετε τη λίστα των παρουσιών που είναι διαθέσιμες σε εσάς μέσω της μεθόδου Λήψη παρουσιών στο API online διαχείρισης.

Κάθε αίτηση στο API Web πρέπει να έχει τις κεφαλίδες Accept και Content-type ορισμένες σε application/json.

Τέλος, συμπληρώστε την κεφαλίδα Authorization με ένα διακριτικό φορέα του Azure AD. Μπορείτε να μάθετε πώς να αποκτήσετε ένα διακριτικό φορέα Azure AD για το Dataverse. Για παράδειγμα, αυτή η αίτηση:

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

Η απάντηση περιέχει τη λίστα ροών μέσα από αυτό το περιβάλλον:

{
    "@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 Dataverse.",
        "clientdata": "{\"properties\":{\"connectionReferences\":{\"shared_commondataservice\":{\"source\":\"NotSpecified\",\"id\":\"/providers/Microsoft.PowerApps/apis/shared_commondataservice\",\"tier\":\"NotSpecified\"}},\"definition\":{...}},\"schemaVersion\":\"1.0.0.0\"}"
    }]
}

Λίστα ροών

Όπως φαίνεται παραπάνω, μπορείτε να λάβετε τη λίστα των ροών εργασιών με κλήση της μεθόδου GET σε workflows. Κάθε ροή εργασιών έχει πολλές ιδιότητες, αλλά οι πιο σχετικές είναι οι εξής:

Όνομα ιδιότητας Περιγραφή
category Η κατηγορία της ροής. Οι διαφορετικοί τύποι είναι: 0 - κλασικές ροές εργασιών για Dataverse, 1 - κλασικά παράθυρα διαλόγου Dataverse, 2 - επιχειρησιακοί κανόνες, 3 - κλασικές ενέργειες για Dataverse, 4 - ροές επιχειρηματικών διαδικασιών και 5 - αυτοματοποιημένες, άμεσες ή προγραμματισμένες ροές.
statecode Η κατάσταση της ροής. Η κατάσταση μπορεί να είναι 0 - απενεργοποιημένη ή 1 - ενεργοποιημένη.
workflowidunique Το μοναδικό αναγνωριστικό για αυτή την εγκατάσταση της ροής.
workflowid Το μοναδικό αναγνωριστικό για μια ροή cloud σε όλες τις εισαγωγές.
createdon Η ημερομηνία που δημιουργήθηκε η ροή.
_ownerid_value Το μοναδικό αναγνωριστικό του χρήστη ή της ομάδας στους οποίους ανήκει η ροή. Αυτό είναι ένα αναγνωριστικό από τον πίνακα systemusers στο Dataverse.
modifiedon Η τελευταία φορά που ενημερώθηκε η ροή.
ismanaged Υποδεικνύει εάν η ροή εγκαταστάθηκε μέσω μιας διαχειριζόμενης λύσης.
name Το εμφανιζόμενο όνομα που έχετε δώσει στη ροή.
_modifiedby_value Ο τελευταίος χρήστης που ενημέρωσε τη ροή. Αυτό είναι ένα αναγνωριστικό από τον πίνακα systemusers στο Dataverse.
_createdby_value Ο χρήστης που δημιούργησε τη ροή. Αυτό είναι ένα αναγνωριστικό από τον πίνακα systemusers στο Dataverse.
type Υποδεικνύει εάν η ροή είναι μια ροή εκτέλεσης ή ένα πρότυπο που μπορεί να χρησιμοποιηθεί για τη δημιουργία επιπλέον ροών. 1 - ροή, 2 - ενεργοποίηση ή 3 - πρότυπο.
description Η περιγραφή της ροής από τον χρήστη.
clientdata Μια JSON με κωδικοποίηση συμβολοσειράς ενός αντικειμένου που περιέχει το connectionReferences και τον ορισμό της ροής.

Μπορείτε επίσης να ζητήσετε συγκεκριμένες ιδιότητες, να φιλτράρετε τη λίστα των ροών και πολλά άλλα, όπως περιγράφεται στο θέμα Τεκμηρίωση API Dataverse για εφαρμογές για την υποβολή ερωτημάτων δεδομένων. Για παράδειγμα, αυτό το ερώτημα επιστρέφει μόνο τις αυτοματοποιημένες, άμεσες ή προγραμματισμένες ροές που είναι ενεργοποιημένες αυτή τη στιγμή:

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...

Δημιουργία μιας ροής cloud

Καλέστε το POST στη συλλογή workflows για να δημιουργήσετε μια ροή cloud. Οι απαιτούμενες ιδιότητες για τις αυτοματοποιημένες, τις άμεσες και τις προγραμματισμένες ροές είναι: category, name, type, primaryentity και clientdata. Χρήση της τιμής none για την ιδιότητα primaryentity για αυτούς τους τύπους ροών.

Μπορείτε επίσης να δώσετε μια περιγραφή και έναν statecode.

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 Dataverse.",
        "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\"}"
}

Η πιο σημαντική ενότητα είναι η ενότητα clientdata, που περιέχει το connectionReferences που χρησιμοποιεί η ροή και ο ορισμός της ροής. Το connectionReferences είναι οι αντιστοιχίσεις σε κάθε σύνδεση που χρησιμοποιεί τη ροή.

Υπάρχουν τρεις ιδιότητες:

Όνομα ιδιότητας Περιγραφή
connectionName Αναγνωρίζει τη σύνδεση. Μπορείτε να δείτε την ιδιότητα connectionName από τη σελίδα Συνδέσεις και, στη συνέχεια, να την αντιγράψετε από τη διεύθυνση URL της σύνδεσης.
source Είτε Embedded ή Invoker. Η ιδιότητα Invoker ισχύει μόνο για άμεσες ροές (αυτές όπου ένας χρήστης επιλέγει ένα κουμπί για να εκτελέσει τη ροή) και υποδεικνύει ότι ο τελικός χρήστης θα παρέχει τη σύνδεση. Σε αυτή την περίπτωση η ιδιότητα connectionName χρησιμοποιείται μόνο κατά τον χρόνο σχεδίασης. Εάν η σύνδεση είναι Embedded, αυτό σημαίνει ότι χρησιμοποιείται πάντα η ιδιότητα connectionName που καθορίζετε.
id Το αναγνωριστικό της σύνδεσης. Το αναγνωριστικό ξεκινά πάντα με /providers/Microsoft.PowerApps/apis/ και, στη συνέχεια, ακολουθεί το όνομα της σύνδεσης, το οποίο μπορείτε να αντιγράψετε από τη διεύθυνση URL της σύνδεσης ή επιλέγοντας τη σύνδεση από τη σελίδα Συνδέσεις.

Μόλις εκτελέσετε την αίτηση POST, θα λάβετε την επικεφαλίδα OData-EntityId, η οποία θα περιέχει το workflowid για τη νέα ροή σας.

Ενημέρωση μιας ροής cloud

Μπορείτε να καλέσετε μια PATCH στη ροή εργασιών για να ενημερώσετε, να ενεργοποιήσετε ή να απενεργοποιήσετε μια ροή cloud. Χρησιμοποιήστε την ιδιότητα workflowid για να κάνετε αυτές τις κλήσεις. Για παράδειγμα, μπορείτε να ενημερώσετε την περιγραφή και τον κάτοχο της ροής με την ακόλουθη κλήση:

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

Note

Η σύνταξη για την αλλαγή του κατόχου χρησιμοποιεί τη μορφή odata.bind. Αυτό σημαίνει ότι αντί για την ενημέρωση του πεδίου _ownerid_valu απευθείας, μπορείτε να προσαρτήσετε το @odata.bind στο όνομα ιδιότητας και, στη συνέχεια, να αναδιπλώσετε το αναγνωριστικό με το systemusers().

Σε ένα άλλο παράδειγμα, μπορείτε να ενεργοποιήσετε μια ροή cloud με αυτήν την κλήση:

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
}

Διαγραφή μιας ροής cloud

Διαγράψτε μια ροή cloud με μια απλή κλήση DELETE:

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

Note

Δεν μπορείτε να διαγράψετε μια ροή cloud που είναι ενεργοποιημένη. Πρέπει πρώτα να απενεργοποιήσετε τη ροή (ανατρέξτε στην ενότητα Ενημέρωση ροής cloud παραπάνω), διαφορετικά, θα εμφανιστεί το σφάλμα: Cannot delete an active workflow definition.

Παράθεση όλων των χρηστών με τους οποίους γίνεται κοινή χρήση μιας ροής cloud

Η παράθεση των χρηστών με πρόσβαση χρησιμοποιεί μια συνάρτηση στο Dataverse. Αυτή η συνάρτηση λαμβάνει την μοναδική παράμετρο 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 είναι μια συμβολοσειρά JSON με μια μοναδική ιδιότητα που ονομάζεται @odata.id. Αντικαταστήστε το αναγνωριστικό ροής εργασιών στο παραπάνω παράδειγμα. Επιστρέφει:

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

Κοινή χρήση ή κατάργηση κοινής χρήσης μιας ροής cloud

Μπορείτε να θέσετε σε κοινή χρήση μια ροή cloud, χρησιμοποιώντας την ενέργεια GrantAccess.

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 είναι ένα πεδίο με τις ακόλουθες τιμές για διαφορετικά επίπεδα δικαιωμάτων:

Όνομα Περιγραφή
None Χωρίς πρόσβαση.
ReadAccess Το δικαίωμα ανάγνωσης της ροής.
WriteAccess Το δικαίωμα ενημέρωσης της ροής.
DeleteAccess Το δικαίωμα διαγραφής της ροής.
ShareAccess Το δικαίωμα κοινής χρήσης της ροής.
AssignAccess Το δικαίωμα αλλαγής του κατόχου της ροής.

Μπορείτε να συνδυάσετε δικαιώματα χρησιμοποιώντας το κόμμα. Για παράδειγμα, εκχωρήστε τη δυνατότητα ανάγνωσης και ενημέρωσης μιας ροής cloud παραχωρώντας ReadAccess,WriteAccess.

Μπορείτε να καταργήσετε την κοινή χρήση μιας ροής cloud, χρησιμοποιώντας την ενέργεια RevokeAccess. Ακολουθεί ένα παράδειγμα:

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 καταργεί όλα τα δικαιώματα που εκχωρούνται στο AccessMask.

Εξαγωγή ροών

Χρησιμοποιήστε την ενέργεια ExportSolution για να εξαγάγετε ροές σε ένα αρχείο .zip. Πρώτα, προσθέστε τις ροές που θέλετε σε μια λύση.

Όταν η ροή σας είναι μέσα σε μια λύση, καλέστε την ακόλουθη ενέργεια:

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 επιστρέφει μια βασική συμβολοσειρά με κωδικοποίηση 64 στην ιδιότητα ExportSoutionFile.

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

Στη συνέχεια, μπορείτε να αποθηκεύσετε αυτό το αρχείο στο στοιχείο ελέγχου πηγαίου κώδικα ή/και να χρησιμοποιήσετε όποια διαχείριση έκδοσης ή σύστημα διανομής θέλετε.

Εισαγωγή ροών

Καλέστε την ενέργεια ImportSolution για να εισαγάγετε μια λύση.

Όνομα ιδιότητας Περιγραφή
OverwriteUnmanagedCustomizations Εάν δεν υπάρχουν υπάρχουσες παρουσίες αυτών των ροών στο Dataverse για εφαρμογές, πρέπει να οριστεί αυτή η σημαία σε true για την εισαγωγή τους. Σε αντίθετη περίπτωση, δεν θα αντικατασταθούν.
PublishWorkflows Υποδεικνύει αν θα ενεργοποιηθεί οι κλασικές ροές εργασίας Dataverse κατά την εισαγωγή. Αυτή η ρύθμιση δεν ισχύει για άλλους τύπους ροών.
ImportJobId Παρέχει ένα νέο, μοναδικό GUID για την παρακολούθηση της εργασίας εισαγωγής.
CustomizationFile Ένα βασικό αρχείο zip με κωδικοποίηση 64 που περιέχει τη λύση.
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..."
}

Δεδομένου ότι η εισαγωγή είναι μια λειτουργία μεγάλης διάρκειας, η απόκριση στην ενέργεια ImportSolution θα είναι ένα 204 No content. Για να παρακολουθήσετε την πρόοδο, καλέστε μια ενέργεια GET στο αντικείμενο importjobs, παρέχοντας το ImportJobId που έχετε συμπεριλάβει στην αρχική ενέργεια ImportSolution.

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

Αυτή η κλήση επιστρέφει την κατάσταση της διαδικασίας εισαγωγής, συμπεριλαμβανομένων των progress (ποσοστό ολοκλήρωσης), startedon και completedon (εάν η εισαγωγή ολοκληρώθηκε).

Όταν η εισαγωγή ολοκληρωθεί με επιτυχία, θα χρειαστεί να ρυθμίσετε τις συνδέσεις για τη ροή, εφόσον το στοιχείο connectionNames πιθανόν να είναι διαφορετικό στο περιβάλλον προορισμού (εάν υπάρχουν οι συνδέσεις). Εάν κάνετε εγκατάσταση νέων συνδέσεων στο περιβάλλον προορισμού, τότε, ο κάτοχος των ροών πρέπει να τις δημιουργήσει στη σχεδίαση Power Automate. Εάν οι συνδέσεις είναι ήδη εγκατεστημένες στο νέο περιβάλλον, τότε, μπορείτε να κάνετε PATCH του clientData της ροής με τα ονόματα των συνδέσεων.