ביצוע בקשות 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 מחזירה שגיאה או נכשלת בביצוע, הסוכן מפסיק את הפעולה שלו ומפעיל את הנושא מערכת On Error , המציג הודעת שגיאה.

עם זאת, באפשרותך לקבוע את התצורה של טיפול בשגיאות כך שלא יפעיל את הנושא במערכת 'בעת שגיאה'. במקום זאת, באפשרותך לגרום לו לאחסן את קוד המצב של HTTP ואת כל גוף תגובת השגיאה למשתנים שתציין. באפשרותך לחקור משתנים אלה לפי הצורך, והנושא יכול להמשיך לפעול. תצורה זו שימושית בתרחישים שבהם ברצונך שהסוכן ימשיך את הפעולה, גם אם בקשת HTTP מסוימת נכשלת.

כדי לקבוע את אופן הפעולה של טיפול בשגיאות של צומת בקשת HTTP :

1. תחת כותרות וגוף, בחר ערוך. לוח המאפיינים של בקשת HTTP מופיע.

2. תחת טיפול בשגיאות, בחר את אופן הפעולה הרצוי: העלאת שגיאה או המשך בשגיאה.

3. אם תבחר באפשרות המשך בשגיאה, קבע תצורה של משתנים עבור קוד המצב וגוף התגובה לשגיאה.

   

בדוגמה זו, אם בקשת HTTP נכשלת, הסוכן מאחסן את קוד המצב של HTTP Topic.StatusCode במשתנה ואת גוף התגובה במשתנה Topic.ErrorResponse . הסוכן ממשיך לשלבים הבאים בנושא.

סוג משתנה התגובה 'שגיאה' הוא Any. באפשרותך להשתמש בצומת ערך ניתוח כדי להמיר משתנה זה לתוך רשומת Power Fx.

בלוח המאפיינים בקשת HTTP , באפשרותך גם להגדיר מאפיין זמן קצוב לבקשה, באלפיות השניה. ערך ברירת המחדל הוא 30 שניות.