البحث في تذاكر Jira بإجراء مخصص

Jira ليس تكاملًا مدمجًا في Quickchat AI. توضح هذه الصفحة مثالًا عمليًا لإنشاء إجراء API مخصص يتصل بـ REST API خارجي، وينطبق النمط نفسه على أي API آخر.

في هذا الشرح سأبين كيفية ربط وكيل AI بـ Jira. سنستخدم:

• حساب Jira (مجاني)
• وكيل Quickchat AI (سجل هنا واستخدمه مجانًا)

سيتيح ذلك لوكيل Quickchat AI:

• البحث في تذاكر Jira، و
• الإجابة بذكاء عن الأسئلة بناءً عليها

سنستخدم إجراءات AI من Quickchat (إجراءات HTTP مخصصة) ليتمكن الوكيل من استدعاء نقطة نهاية البحث المحسن عن المشكلات في Jira (Atlassian) API.

أنشئ وكيل AI يفسر مدخلات المستخدم بإبداع

فحوص أمثلة اختيارية

• عاين طلب إجراء API. اعرض قالب طلب تقدمه بقيم تجريبية اصطناعية دون إرساله. احذف ترويسات بيانات الاعتماد.

• عاين مطابقات JSONPath. افحص مسارات الجذر والحقول وفهارس المصفوفات ومحارف البدل باستخدام JSON تقدمه. لا يشغّل هذا إجراء ولا يحفظ ذاكرة المحادثة.

تتوفر هذه الفحوص أيضًا كأدوات للموقع في المتصفحات المتوافقة. تفتح الروابط النماذج العادية.

شاهد الفيديو

Play

كيف يعمل

هكذا سيعمل وكيل AI أثناء المحادثات:

1. يسأل المستخدم سؤالًا مثل “ما أخبار المشكلات المتعلقة بعطارد؟”
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) للبحث في المشكلات وإتاحة عمليات بحث أعقد. يجعل ذلك وكيل AI أقوى بكثير. اضبط معاملات الإدخال كما يلي:

التنسيق	الاسم	الوصف	القيمة الافتراضية	مطلوب
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 يستدعي نقطة نهاية API بشكل صحيح. يمكننا الانتقال إلى اختبار محادثات كاملة مع وكيل AI!

الخطوة 9: اختبار وكيل AI في المحادثات

عد إلى تطبيق Quickchat AI واختبر وكيل AI في معاينة المحادثة.

المحادثة الأولى

يقدم وكيل AI ملخصًا لكل مشكلات المشروع

في هذه المحادثة البسيطة، يقدم وكيل AI نظرة عامة على كل مشكلات المشروع. بالنظر إلى ما وراء الكواليس، نجد أن الاستعلام الذي شغله على نقطة النهاية هو: project = "Solar System"

المحادثة الثانية

يجيب وكيل 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"

المحادثة الثالثة

يجيب وكيل 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 الذي تحتاجه بالضبط!