Υποβολή αιτήσεων HTTP

Στο Copilot Studio, μπορείτε να επεκτείνετε τις δυνατότητες ενός παράγοντα καλώντας εξωτερικά API REST χρησιμοποιώντας τον κόμβο αίτησης HTTP. Αυτή η κλήση μπορεί να είναι χρήσιμη όταν χρειάζεται να ανακτήσετε δεδομένα από ένα εξωτερικό σύστημα ή να διαχειριστείτε δεδομένα σε αυτό το σύστημα.

Προαπαιτούμενα

• Δημιουργία και επεξεργασία θεμάτων

Χρήση του κόμβου αίτησης HTTP

1. Επιλέξτε το εικονίδιο Προσθήκη κόμβου κάτω από τον κόμβο όπου θέλετε να καλέσετε ένα εξωτερικό API, τοποθετήστε τον δείκτη του ποντικιού στην επιλογή Για προχωρημένους και επιλέξτε Αποστολή αίτησης HTTP.

2. Στο πλαίσιο URL, πληκτρολογήστε τη διεύθυνση URL για το API τελικό σημείο που θέλετε να καλέσετε.

3. Επιλέξτε την κατάλληλη μέθοδο αίτησης από την αναπτυσσόμενη λίστα. Υποστηρίζονται μέθοδοι GET, POST, PATCH, PUT και DELETE.

   

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

5. Μπορείτε, προαιρετικά, να προσθέσετε μία ή περισσότερες κεφαλίδες στην αίτηση HTTP. Επιλέξτε το κουμπί Προσθήκη για να προσθέσετε το κλειδί και την τιμή κάθε κεφαλίδας.

   

   Μπορείτε να χρησιμοποιήσετε την ενότητα κεφαλίδων για να διαβιβάσετε διακριτικά ελέγχου ταυτότητας, τύπο περιεχομένου ή οποιεσδήποτε άλλες απαιτούμενες κεφαλίδες για το API που καλείτε. Για παράδειγμα, μπορείτε να προσθέσετε μια κεφαλίδα όπως Authorization: Bearer <your_token> για τον έλεγχο ταυτότητας της αίτησης.

6. Από προεπιλογή, δεν αποστέλλεται περιεχόμενο στο σώμα της αίτησης HTTP, αλλά μπορείτε να καθορίσετε περιεχόμενο στο σώμα.

7. Στον κόμβο, επιλέξτε Τύπος δεδομένων απόκρισης από τις διαθέσιμες επιλογές.

   Μπορείτε να δώσετε ένα παράδειγμα απόκρισης JSON, το οποίο μπορείτε συνήθως να βρείτε στην τεκμηρίωση για το API που καλείτε. Δημιουργεί μια μεταβλητή Power Fx, επιτρέποντάς σας να τη χρησιμοποιήσετε αλλού στον καμβά συγγραφής σας, με υποστήριξη intellisense στον επεξεργαστή Power Fx. Επιλέξτε Από δείγμα δεδομένων και, στη συνέχεια, επιλέξτε Λήψη σχήματος από το δείγμα JSON. Επικολλήστε το δείγμα απάντησης στο πρόγραμμα επεξεργασίας και επιλέξτε Επιβεβαίωση.

8. Στην περιοχή Αποθήκευση απόκρισης χρήστη ως, επιλέξτε πού θέλετε να αποθηκεύεται η απόκριση αίτησης HTTP, είτε δημιουργώντας μια νέα μεταβλητή είτε επιλέγοντας μια υπάρχουσα.

Αποστολή περιεχομένου στο σώμα της αίτησης HTTP

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

2. Στο Σώμα επιλέξτε τον κατάλληλο τύπο περιεχομένου. Από προεπιλογή, το Σώμα έχει οριστεί σε Χωρίς περιεχόμενο, όπου δεν πρέπει να υπάρχει περιεχόμενο στο σώμα της αίτησης, το οποίο χρησιμοποιείται συνήθως με την αίτηση GET. Για να προσθέσετε περιεχόμενο στο σώμα του οργανισμού, επιλέξτε μία από τις διαθέσιμες επιλογές.

   

   • Περιεχόμενο JSON: Το περιεχόμενο JSON σάς επιτρέπει να παρέχετε ένα αντικείμενο JSON στο σώμα της αίτησης. Αυτό το αντικείμενο χρησιμοποιείται συχνά κατά την υποβολή αιτήσεων POST ή PUT. Όταν επιλέξετε αυτή την επιλογή, ένα πρόγραμμα επεξεργασίας σάς επιτρέπει να καταχωρήσετε το περιεχόμενο JSON.

     Μπορείτε επίσης να καθορίσετε το περιεχόμενο JSON χρησιμοποιώντας Power Fx, επιτρέποντάς σας να συμπεριλάβετε δυναμικές τιμές και μεταβλητές αναφοράς. Επιλέξτε το κουμπί Επεξεργασία JSON, επιλέξτε Τύπος και, στη συνέχεια, εισαγάγετε ένα αντικείμενο Power Fx (τυχόν υπάρχον JSON που είχε εισαχθεί μετατρέπεται σε αντικείμενο Power Fx για εσάς), το οποίο μετατρέπεται σε JSON όταν γίνεται η αίτηση HTTP.

     

   • Μη επεξεργασμένο περιεχόμενο: Το μη επεξεργασμένο περιεχόμενο σάς επιτρέπει να εισαγάγετε μια συμβολοσειρά δεδομένων στο σώμα της αίτησης και αυτή η συμβολοσειρά μπορεί να είναι τύπος περιεχομένου που καθορίζετε. Το ακατέργαστο περιεχόμενο εισάγεται χρησιμοποιώντας έναν τύπο Power Fx, όπως το περιεχόμενο συμβολοσειράς που παρουσιάζεται στο ακόλουθο παράδειγμα.

     

Χειρισμός σφαλμάτων και λήξη χρονικού ορίου

Ο κόμβος αιτήματος HTTP περιλαμβάνει πολλές επιλογές για το χειρισμό σε περιπτώσεις όπου η αίτηση HTTP ενδέχεται να αποτύχει ή να επιστρέψει ένα σφάλμα.

Από προεπιλογή, το χαρακτηριστικό εμφανίζει σφάλμα. Αυτό σημαίνει ότι όταν μια αίτηση HTTP επιστρέφει σφάλμα ή αποτυγχάνει να εκτελεστεί, ο παράγοντας διακόπτει τη λειτουργία της και ενεργοποιεί το θέμα συστήματος Σε σφάλμα, εμφανίζοντας ένα μήνυμα σφάλματος.

Ωστόσο, μπορείτε να ρυθμίσετε τις παραμέτρους του χειρισμού σφαλμάτων ώστε να μην ενεργοποιεί το θέμα συστήματος Σε σφάλμα. Αντίθετα, μπορείτε να κάνετε την αποθήκευση του κωδικού κατάστασης HTTP και οποιουδήποτε σώματος απόκρισης σφάλματος σε μεταβλητές που καθορίζετε. Μπορείτε να εξετάσετε αυτές τις μεταβλητές ανάλογα με τις ανάγκες και το θέμα συζήτησης μπορεί να συνεχίσει να εκτελείται. Αυτή η ρύθμιση παραμέτρων είναι χρήσιμη σε σενάρια όπου θέλετε ο εκπρόσωπος να συνεχίσει να λειτουργεί, ακόμα και αν αποτύχει μια συγκεκριμένη αίτηση HTTP.

Για να ρυθμίσετε τις παραμέτρους της συμπεριφοράς χειρισμού σφαλμάτων ενός κόμβου αίτησης HTTP:

1. Στην περιοχή Κεφαλίδες και σώμα κειμένου, επιλέξτε Επεξεργασία. Εμφανίζεται ο πίνακας ιδιοτήτων αίτησης HTTP.

2. Στην περιοχή Χειρισμός σφαλμάτων, επιλέξτε την επιθυμητή συμπεριφορά: Εμφάνιση σφάλματος ή Συνέχεια σε περίπτωση σφάλματος.

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

   

Σε αυτό το παράδειγμα, εάν αποτύχει η αίτηση HTTP, ο παράγοντας αποθηκεύει τον κωδικό κατάστασης HTTP στη μεταβλητή Topic.StatusCode και το σώμα απόκρισης στη Topic.ErrorResponse μεταβλητή. Ο εκπρόσωπος συνεχίζει στα επόμενα βήματά του στο θέμα.

Ο τύπος μεταβλητής απόκρισης σφάλματος είναι Οποιοσδήποτε. Μπορείτε να χρησιμοποιήσετε τον κόμβο Ανάλυση τιμής για να μετατρέψετε αυτήν τη μεταβλητή σε καρτέλα Power Fx.

Στον πίνακα ιδιοτήτων αίτησης HTTP, μπορείτε επίσης να ορίσετε μια ιδιότητα χρονικού ορίου αίτησης σε χιλιοστά του δευτερολέπτου. Η προεπιλεγμένη τιμή είναι 30 δευτερόλεπτα.