Εργασία με ροές επιφάνειας εργασίας με χρήση κώδικα

Άρθρο
11/23/2022

Οι προγραμματιστές μπορούν να προσθέσουν λειτουργίες ροών επιφάνειας εργασίας στις εφαρμογές τους, συμπεριλαμβανομένης της προγραμματικής ενεργοποίησης και ακύρωσης ροών επιφάνειας εργασίας. Αυτές οι δυνατότητες προσφέρονται ως μέρος της πλατφόρμας Microsoft Dataverse.

Προϋποθέσεις

Γνώσεις σχετικά με API Web του Dataverse, έλεγχος ταυτότητας με το Dataverse και χρήση του OAuth με το Dataverse.
Γνώσεις σχετικά με τις έννοιες για το περιβάλλον και τον οργανισμό Dataverse και τον τρόπο ανάκτησης της διεύθυνσης URL του οργανισμού με μη αυτόματο ή προγραμματικό τρόπο.
Γνώσεις σχετικά με τις έννοιες ροών επιφάνειας εργασίας και σχετικά με το τι είναι οι συνδέσεις και πώς μπορείτε να τις δημιουργήσετε.

Important

Σε αυτό το άρθρο, πρέπει να αντικαταστήσετε όλες τις αγκύλες [...] στις διευθύνσεις URL και δεδομένα εισόδου/εξόδου με τιμές που αφορούν ειδικά το σενάριό σας.

Παράθεση διαθέσιμων ροών επιφάνειας εργασίας

Όλες οι δέσμες ενεργειών ροών επιφάνειας εργασίας στο Dataverse αποτελούν μέρος της οντότητας ροής εργασιών.

Φιλτράρετε τη λίστα των ροών εργασιών με βάση την κατηγορία για να προσδιορίσετε τις ροές της επιφάνειας εργασίας.

Ζητήστε να λάβετε ροές επιφάνειας εργασίας

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

Απόκριση στην αίτηση για λήψη ροών επιφάνειας εργασίας

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

Λήψη του σχήματος για ροές επιφάνειας εργασίας

Εάν χρειάζεται να ανακτήσετε το σχήμα ροής για εισόδους ή/και εξόδους, μπορείτε να χρησιμοποιήσετε το πεδίο clientData για τη ροή εργασιών προορισμού.

Αίτηση σχήματος για ροές επιφάνειας εργασίας

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

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

Απόκριση στην αίτηση για λήψη του σχήματος ροών επιφάνειας εργασίας

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

Λάβετε την κατάσταση μιας εκτέλεσης ροής επιφάνειας εργασίας

Το Dataverse αποθηκεύει όλες οι εκτελέσεις ροής επιφάνειας εργασίας στην οντότητα συνεδρίας ροής

Ζητήστε την κατάσταση μιας εκτέλεσης ροής επιφάνειας εργασίας

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

Απόκριση για την κατάσταση μιας εκτέλεσης ροής επιφάνειας εργασίας

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

Λήψη εξόδων ροής επιφάνειας εργασίας

Εάν η ροή της επιφάνειας εργασίας έχει εξόδους, μπορείτε να υποβάλετε ερωτήματα στο πεδίο εξόδου για να τις ανακτήσετε.

Αίτηση για εξόδους ροής επιφάνειας εργασίας

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

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

Απόκριση στην αίτηση για εξόδους ροής επιφάνειας εργασίας

{
    "Output1": "My output value"
}

Ενεργοποιήστε μια εκτέλεση ροής επιφάνειας εργασίας

Χρησιμοποιώντας το Dataverse, μπορείτε να προσθέσετε τη λειτουργικότητα της ενεργοποίησης μιας ροής επιφάνειας εργασίας μέσω της εφαρμογής σας. Για να υλοποιήσετε αυτήν τη λειτουργία, πρέπει να χρησιμοποιήσετε την ενέργεια RunDesktopFlow.

Για να καλέσετε την ενέργεια, θα χρειαστείτε τις ακόλουθες πληροφορίες.

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

Tip

Εναλλακτικά, μπορείτε να ανακτήσετε το αναγνωριστικό με μη αυτόματο τρόπο από τη διεύθυνση URL λεπτομερειών ροής επιφάνειας εργασίας στο Power Automate. Η μορφή διεύθυνσης URL είναι: https://flow.microsoft.com/manage/environments/[Environment ID]/uiflows/[Desktop Flow ID]/details.

Για περισσότερες πληροφορίες, δείτε Διαχείριση ροών επιφάνειας εργασίας.
Το name της σύνδεσης ροής επιφάνειας εργασίας (στοχεύοντας μια ομάδα μηχανής/μηχανής) για χρήση για την εκτέλεση της ροής σας. Το όνομα μπορεί να ανακτηθεί από τη διεύθυνση URL της ίδιας σελίδας σύνδεσης στο Power Automate. Η μορφή διεύθυνσης URL είναι:
https://flow.microsoft.com/manage/environments/[Environment ID]/connections?apiName=shared_uiflow&connectionName=[Connection Name].

Note

Για περισσότερες πληροφορίες, δείτε Δημιουργία συνδέσεων ροών επιφάνειας εργασίας.

Tip

Εναλλακτικά, μπορείτε να χρησιμοποιήσετε το λογικό όνομα μιας αναφοράς σύνδεσης ως είσοδο της σύνδεσης αντί για το όνομα της σύνδεσης (παράδειγμα χρήσης που περιγράφεται παρακάτω). Οι αναφορές σύνδεσης αποθηκεύονται στην αναφορά σύνδεσης του πίνακα Dataverse και είναι δυνατό να παρατίθενται προγραμματικά με τον ίδιο τρόπο που εμφανίζονται αναλυτικά οι ροές επιφάνειας εργασίας στην ενότητα Λίστα διαθέσιμων ροών επιφάνειας εργασίας.

Για περισσότερες πληροφορίες, ανατρέξτε στην ενότητα Χρήση μιας αναφοράς σύνδεσης σε μια λύση και αναφορά πίνακα/οντότητα αναφοράς σύνδεσης.

Αίτηση ενεργοποίησης ροής επιφάνειας εργασίας

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

Αίτηση ενεργοποίησης ροής επιφάνειας εργασίας με αναφορά σύνδεσης

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

Απόκριση από αίτηση ενεργοποίησης ροής επιφάνειας εργασίας

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

Warning

Όταν χρησιμοποιείτε το API, υπάρχουν ορισμένοι περιορισμοί που πρέπει να γνωρίζετε:

Κατά την ενεργοποίηση μιας εκτέλεσης ροής επιφάνειας εργασίας με χρήση του API, δεν είναι δυνατή η προβολή των εισόδων της δέσμης ενεργειών στη σελίδα λεπτομερειών εκτέλεσης στην πύλη power automate.
Ο κάτοχος της περιόδου λειτουργίας ροής που αντιπροσωπεύει την εκτέλεση αντιστοιχίζεται στον κάτοχο της οντότητας ροής εργασιών που αντιπροσωπεύει τη ροή της επιφάνειας εργασίας. Θα υπάρχουν ορισμένοι περιορισμοί κατά την κλήση του API σε μια ροή εργασιών με προνόμιο "Χρήστη": Η ακύρωση της εκτέλεσης και η υποβολή ερωτημάτων για την κατάσταση ενδεχομένως να αποκλειστεί για δικαιώματα που λείπουν στην περίοδο λειτουργίας ροής.
Η απομίμηση του Dataverse δεν υποστηρίζεται.

Λήψη ειδοποίησης κατά την ολοκλήρωση της δέσμης ενεργειών

Μια προαιρετική παράμετρος "callbackUrl" είναι διαθέσιμη στο σώμα της ενέργειας RunDesktopFlow. Μπορείτε να τη χρησιμοποιήσετε εάν θέλετε να ειδοποιηθείτε για την ολοκλήρωση της δέσμης ενεργειών. Όταν ολοκληρωθεί η δέσμη ενεργειών, θα αποσταλεί μια αίτηση POST στην παρεχόμενη διεύθυνση URL.

Αίτημα που λήφθηκε από το τελικό σημείο επιστροφής κλήσης

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

Εάν δεν παρέχεται παράμετρος διεύθυνσης URL επιστροφής κλήσης, θα πρέπει να ερωτηθεί η κατάσταση ροής από το Dataverse (αναφέρεται στο Λήψη της κατάστασης εκτέλεσης ροής επιφάνειας εργασίας).

Note

Μπορείτε ακόμα και τώρα να χρησιμοποιήσετε την ερώτηση κατάστασης ως εναλλακτικό μηχανισμό ακόμα και αν δώσετε μια παράμετρο διεύθυνσης URL επιστροφής κλήσης.
Η λειτουργία τελικού σημείου επιστροφής κλήσης θα πρέπει να είναι idempotent.
Η αίτηση POST θα επαναληφθεί τρεις φορές με ένα δεύτερο διάλειμμα εάν το τελικό σημείο αποκρίνεται με απόκριση σφάλματος διακομιστή (κωδικός 500 και άνω) ή με απόκριση "Χρονικό όριο αίτησης" (κωδικός 408).

Απαιτήσεις για την παράμετρο διεύθυνσης URL επιστροφής κλήσης

Ο διακομιστής σας πρέπει να διαθέτει τις τρέχουσες οικογένειες προγραμμάτων TLS και κρυπτογράφησης.
Επιτρέπεται μόνο το πρωτόκολλο HTTPS.
Η πρόσβαση στο localhost (loopback) δεν επιτρέπεται.
Δεν είναι δυνατό να χρησιμοποιηθούν διευθύνσεις IP. Πρέπει να χρησιμοποιήσετε μια διεύθυνση web με όνομα, η οποία απαιτεί επίλυση ονόματος DNS.
Ο διακομιστής σας πρέπει να επιτρέπει συνδέσεις από τιμές διευθύνσεων IP υπηρεσιών Power Platform και Dynamics 365 που προσδιορίζονται στην ετικέτα υπηρεσίας AzureCloud.
Tip

Καθώς η κλήση επιστροφής κλήσης δεν υποβάλλεται σε έλεγχο ταυτότητας, θα πρέπει να ληφθούν ορισμένα προληπτικά μέτρα
- Ελέγξτε το αναγνωριστικό περιόδου λειτουργίας ροής κατά τη λήψη της ειδοποίησης επιστροφής κλήσης. Το Dataverse είναι η πηγή της αλήθειας.
- Εφαρμόστε μια στρατηγική ορίου ποσοστού από την πλευρά του διακομιστή σας.
- Προσπαθήστε να περιορίσετε την κοινή χρήση της διεύθυνσης URL επιστροφής κλήσης μεταξύ πολλών οργανισμών.

Ακυρώστε μια εκτέλεση ροής επιφάνειας εργασίας

Με τη λειτουργία " Ενεργοποίηση", μπορείτε επίσης να ακυρώσετε μια ροή επιφάνειας εργασίας σε ουρά/σε εκτέλεση. Για να ακυρώσετε μια ροή επιφάνειας εργασίας, χρησιμοποιήστε την ενέργεια CancelDesktopFlowRun.

Αίτημα για ακύρωση μιας εκτέλεσης ροής επιφάνειας εργασίας

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

Απάντηση από αίτημα για ακύρωση ροής επιφάνειας εργασίας

HTTP/1.1 204 No Content

Σφάλματα

Όταν παρουσιάζεται ένα σφάλμα, η απόκριση έχει διαφορετική μορφή η οποία συμφωνεί με τα μηνύματα σφάλματος του Dataverse. Ο κωδικός σφάλματος http και το μήνυμα θα πρέπει να παρέχουν αρκετές πληροφορίες για να κατανοήσουν το ζήτημα.

HTTP/1.1 403 Forbidden

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