חיפוש פניות Jira באמצעות פעולה מותאמת אישית

Jira אינה אינטגרציה מובנית של Quickchat AI. הדף הזה הוא דוגמה מלאה לבניית פעולת API מותאמת אישית מול REST API של צד שלישי, ואפשר להשתמש באותה שיטה עם כל API אחר.

במדריך הזה נראה איך לחבר את סוכן ה-AI שלכם ל-Jira. נשתמש ב:

• חשבון Jira (בחינם)
• סוכן AI של Quickchat (הירשמו כאן והשתמשו בחינם)

כך סוכן ה-Quickchat AI שלכם יוכל:

• לחפש בפניות Jira שלכם, וגם
• להשיב על שאלות על בסיסן בחוכמה

נשתמש בפעולות AI של Quickchat (פעולות HTTP מותאמות אישית) כדי לאפשר לסוכן לקרוא לנקודת הקצה Enhanced search for issues של Jira (Atlassian) API.

צרו סוכן AI שמפרש קלט של משתמשים באופן יצירתי

בדיקות דוגמה אופציונליות

• תצוגה מקדימה של בקשת פעולת API. הרכיבו תבנית בקשה שסיפקתם עם ערכי דוגמה סינתטיים בלי לשלוח אותה. השמיטו כותרות עם פרטי גישה.

• תצוגה מקדימה של התאמות JSONPath. בדקו נתיבי שורש, שדה, אינדקס מערך ותווים כלליים מול JSON שסיפקתם. הבדיקה אינה מפעילה פעולה או שומרת זיכרון שיחה.

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

צפו בסרטון

Play

איך זה עובד

כך סוכן ה-AI יפעל במהלך שיחות:

1. המשתמש שואל שאלה כגון “מה קורה עם הפניות שקשורות ל-mercury?”
2. סוכן ה-AI מביא מידע רלוונטי מ-Jira API באמצעות שאילתה כמו “mercury”
3. סוכן ה-AI משיב למשתמש על סמך המידע שהתקבל מה-API

פעלו לפי השלבים הבאים. ההגדרה כולה אמורה לקחת לכל היותר 10 דקות!

שלב 0: יצירת חשבון ופרויקט ב-Jira

1. עברו אל id.atlassian.com/signup, צרו חשבון ואמתו אותו.
2. הוסיפו את Jira לאפליקציות Atlassian שלכם (התוכנית החינמית מספיקה להתחלה).
3. הגדירו את הפרויקט הראשון וצרו פניות כמו בדוגמה הבאה.

לוח לדוגמה עם פניות Jira

שלב 1: אסימון אימות של Jira API

עברו אל id.atlassian.com/manage-profile/security/api-tokens וצרו אסימון API שייראה בערך כך:

ATATT3xFfGF01sKUl0HEW2-_-u9umfLSz7jeblmeLzEHZ1DLcdLbKeVF137iTHGkKhPuNMSKX8mkbwLpHXT4-qXEn-xNEnfiK8_XDVW6XXvGd_SBV3HD4kJInGNjfg2_yEoJFN6uwy4NRqeuhV2tjmyzxozLBRn35OhXkDA6QGfLFvf2_PKuNtA=8DA704E4

כדי להשתמש באסימון Atlassian API בפעולות Quickchat AI, צריך לקודד אותו ב-base64 יחד עם כתובת האימייל שלכם:

your_email@example.com:ATATT3xFfGF01sKUl0HEW2-_-u9umfLSz7jeblmeLzEHZ1DLcdLbKeVF137iTHGkKhPuNMSKX8mkbwLpHXT4-qXEn-xNEnfiK8_XDVW6XXvGd_SBV3HD4kJInGNjfg2_yEoJFN6uwy4NRqeuhV2tjmyzxozLBRn35OhXkDA6QGfLFvf2_PKuNtA=8DA704E4

הקפידו לכלול את כתובת האימייל המדויקת שבה השתמשתם ליצירת חשבון Atlassian

אפשר להשתמש בכלי מקוון פשוט כמו base64encode.org.

הקפידו להשתמש בLive mode, שמבטיח שהקידוד מתבצע כולו בדפדפן שלכם.

אפשר להשתמש בכלי מקוון חינמי לקידוד אסימון ה-API

לחלופין, כך עושים זאת במחשב שלכם באמצעות סקריפט Python פשוט:

import base64

email = "your_email@example.com"
api_token = "ATATT3xFfGF01sKUl0HEW2-_-u9umfLSz7jeblmeLzEHZ1DLcdLbKeVF137iTHGkKhPuNMSKX8mkbwLpHXT4-qXEn-xNEnfiK8_XDVW6XXvGd_SBV3HD4kJInGNjfg2_yEoJFN6uwy4NRqeuhV2tjmyzxozLBRn35OhXkDA6QGfLFvf2_PKuNtA=8DA704E4"

credentials = f"{email}:{api_token}"
b64_credentials = base64.b64encode(credentials.encode("utf-8")).decode("utf-8")

print(f"Basic {b64_credentials}")

הסקריפט שלעיל מספק כותרת מוכנה לשימוש עם האסימון המקודד, שנראית בערך כך:

Basic eW91cl9lbWFpbEBleGFtcGxlLmNvbTpBVEFUVDN4RmZHRjAxc0tVbDBIRVcyLV8tdTl1bWZMU3o3amVibG1lTHpFSFoxRExjZExiS2VWRjEzN2lUSEdrS2hQdU5NU0tYOG1rYndMcEhYVDQtcVhFbi14TkVuZmlLOF9YRFZXNlhYdkdkX1NCVjNIRDRrSkluR05qZmcyX3lFb0pGTjZ1d3k0TlJxZXVoVjJ0am15enhvekxCUm4zNU9oWGtEQTZRR2ZMRnZmMl9QS3VOdEE9OERBNzA0RTQ=

שלב 2: יצירת פעולת Quickchat AI

באפליקציית Quickchat AI, עברו אל פעולות ו־MCP והוסיפו פעולה:

דף פעולת AI

תנו לפעולת ה-AI שם מתאים:

שם: Search Jira issues

הזינו שם לפעולת ה-AI

שלב 3: הגדרת פרמטרי קלט

המשימה העיקרית של סוכן ה-AI תהיה לתרגם את נושא השאלה של המשתמש לשאילתה מדויקת לחיפוש בפניות Jira. לצורך חיפוש פניות, Jira עברה לאחרונה באופן מלא ל-JQL (Jira Query Language) כדי לאפשר חיפושים מורכבים יותר. כך הסוכן יכול להיות עוצמתי הרבה יותר. הגדירו את פרמטרי הקלט כך:

פורמט	שם	תיאור	ערך ברירת מחדל	חובה
Text	jql	(ראו בהמשך)	-	✅

כדי להשיג ביצועים מצוינים עם סוכן ה-AI, תיאור מנוסח היטב חשוב במיוחד:

תיאור:

A single valid JQL (Jira Query Language) string built per the description. Favor recall: prefer `(text ~ "term1" OR text ~ "term2")` over chaining with AND, and use parentheses for grouping. For "not started / in progress / done" questions, filter on `statusCategory` ("To Do", "In Progress", "Done"), which is stable across projects; use `status = "..."` only when the user names a specific status that exists on the board. Avoid custom fields. Examples: `statusCategory = "In Progress" AND (text ~ "mercury" OR text ~ "venus")`, `(text ~ "planet*" OR text ~ "integration")`, `project = "Solar System" AND statusCategory = "To Do"`.

תיאור פרמטר מנוסח היטב הוא המפתח לביצועי סוכן ה-AI

הערה על מצבים ב-Jira

Jira מבחינה בין שם מצב לקטגוריה שלו, ו-JQL מתייחסת אליהם אחרת:

• שם המצב הוא מה שמוצג בלוח. פרויקט אחד משתמש ב-To Do / In Progress / Done, ואחר ב-Open / In Review / Closed.
• קטגוריית המצב היא אחת משלוש קבוצות קבועות שכל מצב ממופה אליהן: To Do, ‏In Progress, ‏Done.

status = "To Do" מסנן לפי שם, ולכן אינו מחזיר דבר בלוח שהעמודה הראשונה שלו נקראת Open. זו סיבה נפוצה לכך שסוכן מדווח בביטחון “אין פניות לביצוע” בזמן שהלוח מלא בהן. עבור שאלות כמו “מה עוד לא התחיל”, “מה בטיפול” ו”מה הושלם”, סננו לפי קטגוריה:

statusCategory = "To Do"
statusCategory = "In Progress"
statusCategory = "Done"

שמרו את status = "..." למקרים שבהם המשתמש מציין מצב מסוים שאתם יודעים שקיים בלוח. אפשר גם לרשום בתיאור הפעולה (שלב 7) את שמות המצבים בפועל בלוח, כדי שהסוכן ימפה בקשה כגון “מוכן לבדיקת איכות” למצב הנכון.

שלב 4: הגדרת כתובת נקודת הקצה של ה-API

1. בחרו GET כשיטת בקשת ה-API
2. הגדירו את כתובת נקודת הקצה לכתובת של Jira /rest/api/3/search/jql

הגדירו את כתובת נקודת הקצה של ה-API

הקפידו להשתמש בשם הדומיין שלכם ב-Atlassian. תמצאו אותו בכתובת של לוח Jira שלכם.

שם הדומיין שלכם ב-Atlassian

שלב 5: הגדרת כותרות בקשת ה-API

הגדירו את כותרות בקשת ה-API כך:

Accept	Autorization
application/json	Basic cGlvdHJAcXVpY2tjaGF0LmFpOkFUQVRUM3hGZkdGMGlQOVNacEhVZ1o5YUJfWGhmQjZJWjJId3MyaHlsMzEtTlNpYW90Z2tZVzRxQXEwQ3R4UVY1OXFTZkpWWVZNcXlxem42MWRkR0VobmJWNzdzaWtrb19ZWkhtLUgwazFOZGh4WlpQMnltYmZ1SzhBRmlFMnJEUmdqd182N1hkSFFUelFQY2I2U1lrNUFPRlRuVnZvaGxkZUd3djVpM2VrcEFyMVJ4QnJWRncyYz04MEZGQTcyMA==

הקפידו במיוחד על עיצוב נכון של כותרת Authorization: ‏Basic <base64-encoded email:api token>

הגדירו את כותרות בקשת ה-API

שלב 6: הגדרת פרמטרי השאילתה של בקשת ה-API

הגדירו שני פרמטרי שאילתה לבקשת ה-AI:

• jql מקבל ערך דינמי שהוגדר קודם בסעיף מה לשאול את המשתמש תחילה. תפקידו של סוכן ה-AI למלא את ערך הפרמטר על בסיס מה שהמשתמש אמר בשיחה.
• fields מקבל ערך קבוע. עבור כל פנייה ב-Jira, מעניינים אותנו רק ה_סיכום_, ה_תיאור_ וה_מצב_ שלה.

jql	fields
{{jql}}	summary,description,status

הגדירו את פרמטרי השאילתה של בקשת ה-API

ודאו שהפרמטר jql מפנה כראוי לערך שהוגדר קודם. אפשר לבחור בו מהתפריט הוספת נתוני AI.

בחרו את הפרמטר הדינמי jql מתוך התפריט

שלב 7: הגדרת תיאור פעולת ה-API

המרכיב החיוני האחרון בפעולת AI שמוגדרת היטב הוא התיאור שלה. אף שסוכן ה-AI מבין היטב את נקודת הקצה של ה-API כבר מהכתובת ומהפרמטרים שלה, חשוב להתאים את התנהגותו למקרה השימוש שלכם.

שלושת ההיבטים החשובים ביותר שנכללים בפרומפט הם:

• מתי להפעיל את הפעולה: רשמו כל ניסוח שהמשתמש עשוי לבחור (מצא / חפש / אתר, וגם הסבר / ספר לי על / תאר / מהו / מה המצב של), כדי שהסוכן לא ידלג על הקריאה כשהמשתמש אינו אומר “חפש”
• הצעות לשימוש בתחביר JQL מתקדם בחיפוש פניות Jira
• איך לטפל בתוצאות ריקות: הסוכן חייב לומר זאת במפורש, במקום לטעון שאין לו גישה

זהו תיאור פעולת API שמתקבל:

Use this action whenever the user asks anything that could be answered by data in their Jira — projects, issues, statuses, sprints, test cycles, descriptions, owners, comments — regardless of how they phrase the request (find / search / look for / explain / tell me about / describe / what is / how is the status of, etc.). Do not refuse access; query Jira first.

Construct a JQL that prioritises recall over precision: prefer `(text ~ "term1" OR text ~ "term2")` over chaining with AND, and use parentheses for grouping. For lifecycle questions (not started, in progress, done) filter on `statusCategory` ("To Do" / "In Progress" / "Done") rather than `status`, because status names vary by board; use `status = "..."` only when the user names a specific status. Avoid custom fields.

If Jira returns no matches, say so explicitly to the user and suggest a refined query.

שלב 8: בדיקת פעולת ה-API

לפני שנבדוק את פעולת ה-AI בשיחה, אפשר לבדוק כיצד מתבצעת הקריאה ל-API עצמו בלשונית בדיקת תגובה. נבצע בדיקה ראשונה עם השאילתה הבאה, שאמורה להחזיר את כל הפניות בפרויקט: project = "Solar System"

חיפוש כל הפניות בפרויקט Solar System

להלן תגובת הבדיקה שמתקבלת. כצפוי, היא מציגה את שדות הסיכום, התיאור והמצב של כל שש הפניות בלוח Jira שלנו.

התגובה מציגה את כל הפניות בפרויקט Solar System

ננסה שאילתה נוספת. הפעם נחפש את כל הפניות שמזכירות “mercury”: ‏text ~ "mercury"

חיפוש פניות שמזכירות mercury

כעת אימתנו שפעולת ה-AI קוראת לנקודת הקצה שלנו כראוי. אפשר לעבור לבדיקת שיחות מלאות עם סוכן ה-AI!

שלב 9: בדיקת סוכן ה-AI בשיחות

חזרו לאפליקציית Quickchat AI ובדקו את סוכן ה-AI בתצוגה המקדימה של השיחה.

שיחה מס’ 1

סוכן ה-AI מסכם את כל הפניות בפרויקט

בשיחה הפשוטה הזו, סוכן ה-AI נותן סקירה של כל הפניות בפרויקט. מבט מאחורי הקלעים מראה שהשאילתה המדויקת שהפעיל מול נקודת הקצה הייתה: project = "Solar System"

שיחה מס’ 2

סוכן ה-AI משיב לשאלות על פניות ומצבים מסוימים

במקרה הזה נשאל סוכן ה-AI על שני היבטים נפרדים: פנייה מסוימת ופניות בטיפול באופן כללי. מבט מאחורי הקלעים מראה שהוא בחר להשתמש ב-Jira API בתהליך בן שני שלבים:

1. בדיקה אם pluto נמצא בטיפול:

status = "In Progress" AND (text ~ "pluto" OR text ~ "ongoing" OR text ~ "current" OR text ~ "active" OR text ~ "progress")

2. בדיקה מה עוד נמצא בטיפול:

status = "In Progress"

שיחה מס’ 3

סוכן ה-AI משיב לשאלה יצירתית 😉

במקרה הזה רציתי לאתגר את סוכן ה-AI ושאלתי שאלה שדורשת מעט יצירתיות כדי לפרש אותה נכון. כך היא תורגמה לשאילתת JQL:

(text ~ "planet" OR text ~ "upstream" OR text ~ "mercury" OR text ~ "venus")

נסו את הניסוחים האלה

כדי לוודא שפעולת ה-AI מופעלת בלי תלות בניסוח הבקשה של משתמשי הקצה, הריצו כל אחד מהפרומפטים הבאים בתרחיש הבדיקה שלכם. הסוכן צריך לפנות ל-Jira בכל אחד מהם, ולא רק בניסוחים שמבקשים חיפוש:

• “מצא את כל הפניות הפתוחות על תוצאות בזמן אמת”
• “חפש פניות עם mercury”
• “הסבר את פרויקט Solar System”
• “ספר לי על הפניות הפתוחות בספרינט הזה”
• “תאר מה נמצא כרגע בטיפול”
• “מה המצב של pluto?”

אם אחד הניסוחים האלה אינו מפעיל את פעולת ה-AI, בדקו שוב שתיאור פעולת ה-API (שלב 7) מציין במפורש את הפעלים האלה.

למה לצפות כשאין ב-Jira פניות תואמות

כש-Jira מחזירה אפס תוצאות, סוכן ה-AI צריך לומר זאת במפורש, למשל: “בדקתי ב-Jira ולא מצאתי פניות שתואמות לשאילתה שלך. אפשר לנסות ניסוח רחב יותר או להסיר את מסנן המצב.”

אם במקום זאת הסוכן משיב “אין לי גישה ישירה ל-Jira שלך”, פעולת ה-AI לא הופעלה כלל. בדקו שוב את התיאור משלב 7 וודאו שהוא מציין במפורש פעלים שאינם חיפוש (explain, ‏tell me about, ‏describe, ‏what is).

סיכום

במדריך הזה הראינו איך להגדיר סוכן AI כך שישתמש בנקודת קצה מסוימת של API באופן יצירתי בשיחות. ההגדרה הנכונה אינה מתקבלת אוטומטית; היא דורשת מידע נוסף ומפורט על מקרה השימוש המבוקש. אתם מוזמנים להשתמש מחדש בפרומפטים ובתיאורים שבמדריך כדי ליצור סוכני AI דומים משלכם!

מעדיפים מדריך ארוך עם קריינות? אותה הגדרה מתוארת גם בפוסט בבלוג quickchat.ai. דף התיעוד הזה הוא המקור הראשי שמתעדכן באופן שוטף.

המשך הדרך

פעולת Jira אינה חייבת להיות בקשה קבועה אחת. אפשר להכניס משתני שיחה מובנים ומטא־נתונים שמורים (כגון שפת המבקר או ערכים שנאספו קודם בשיחה) לכל שדה, ולהוסיף כמה פעולות כדי שהסוכן יבחר את המתאימה לכל שאלה. ראו את תיעוד הפעולות לכל האפשרויות.

🎁  בונוס

המדריך שלעיל נכתב על ידי אדם (אני), אבל AI היה יכול לכתוב אותו באותה מידה. למשל, באמצעות הדבקת פרומפט כזה ב-ChatGPT:

I need an API endpoint that allows me to search through my Jira tickets.

Guide me through the process step by step so that it is accessible to a moderately technical person:
- Provide links to documentation describing the endpoint
- Any necessary account creation and initial setup
- If any paid account is needed, indicate that clearly
- If any authentication such as API tokens is needed, guide me through the process of creating them and show me exactly every step needed to be able to use them as an HTTP request header. For example, if base64 encoding is needed, show a script or another way of achieving that.
- Show to me exactly what header keys and values I need for the HTTP request (show me header keys and values in a table)
- Show to me exactly what payload parameters I need for the HTTP request (show me payload parameter name and example values in a table)

בעתיד, אולי במקום לחפש בפניות Jira תרצו:

• לשלוח הודעות לערוץ Slack?
• להביא מידע מדף Notion?
• לבצע פעולה באמצעות Zapier?

ציינו זאת במשפט הראשון והריצו את הפרומפט שוב! תקבלו הוראות טובות להוספת פעולת ה-AI המדויקת הדרושה לכם!