ค้นหาทิกเก็ต Jira ด้วย Action ที่กำหนดเอง

Jira ไม่ใช่การเชื่อมต่อที่มีใน Quickchat AI หน้านี้เป็นตัวอย่างการสร้าง API Action ที่กำหนดเอง เพื่อเรียก REST API ของบุคคลที่สาม และใช้แนวทางเดียวกันกับ API อื่นได้

บทความนี้จะแสดงวิธีเชื่อมต่อเอเจนต์ AI กับ Jira โดยเราจะใช้:

• บัญชี Jira (ฟรี)
• เอเจนต์ AI ของ Quickchat (สมัครที่นี่และใช้ได้ฟรี)

สิ่งนี้ทำให้เอเจนต์ Quickchat AI ของคุณ:

• ค้นหาในทิกเก็ต Jira ได้ และ
• ตอบคำถามจากข้อมูลเหล่านั้นได้อย่างชาญฉลาด

เราจะใช้ AI Actions ของ Quickchat (การดำเนินการ HTTP ที่กำหนดเอง) เพื่อให้เอเจนต์เรียก endpoint Enhanced search for issues ของ Jira (Atlassian) API

สร้างเอเจนต์ AI ที่ตีความสิ่งที่ผู้ใช้ป้อนได้อย่างยืดหยุ่น

การตรวจสอบตัวอย่างเพิ่มเติม

• ดูตัวอย่างคำขอ API Action เติมค่าตัวอย่างจำลองในแม่แบบคำขอที่ระบุโดยไม่ส่งคำขอ อย่าใส่ส่วนหัวที่มีข้อมูลรับรอง

• ดูตัวอย่างผลการจับคู่ JSONPath ตรวจสอบพาธราก ฟิลด์ ดัชนีอาร์เรย์ และไวลด์การ์ดกับ JSON ที่ระบุ โดยไม่เรียก Action หรือบันทึกความจำการสนทนา

ในเบราว์เซอร์ที่รองรับ การตรวจสอบเหล่านี้ยังใช้เป็นเครื่องมือของเว็บไซต์ได้ด้วย ลิงก์จะเปิดแบบฟอร์มมาตรฐาน

ดูวิดีโอ

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 Actions คุณต้องเข้ารหัส 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 Action

ในแอป Quickchat AI ไปที่ Actions และ MCPs แล้วเพิ่ม Action:

หน้า AI Action

ตั้งชื่อ AI Action ให้เหมาะสม:

ชื่อ: Search Jira issues

กรอกชื่อ AI Action

ขั้นตอนที่ 3: ตั้งพารามิเตอร์อินพุต

งานหลักของเอเจนต์ AI คือแปลงสิ่งที่ผู้ใช้ถามเป็นคำค้นที่แม่นยำเพื่อค้นหารายการงาน Jira เมื่อไม่นานมานี้ Jira เปลี่ยนการค้นหารายการงานไปใช้ JQL (Jira Query Language) ทั้งหมดเพื่อรองรับการค้นหาซับซ้อนขึ้น ทำให้เอเจนต์ 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 = "..." เมื่อผู้ใช้ระบุชื่อสถานะเฉพาะที่คุณรู้ว่ามีอยู่บนบอร์ด คุณยังใส่ชื่อสถานะจริงของบอร์ดในคำอธิบาย Action (ขั้นตอนที่ 7) เพื่อให้เอเจนต์จับคู่คำขออย่าง “พร้อมให้ QA ทดสอบ” กับสถานะที่ถูกต้องได้

ขั้นตอนที่ 4: ตั้ง URL ของปลายทาง API

1. เลือก GET เป็นวิธีส่งคำขอ API
2. ตั้ง URL เป็น endpoint Jira /rest/api/3/search/jql

ตั้ง URL ของปลายทาง API

ใช้ชื่อโดเมน Atlassian ของคุณ โดยดูได้จาก URL ของบอร์ด Jira

ชื่อโดเมน Atlassian ของคุณ

ขั้นตอนที่ 5: ตั้งส่วนหัวคำขอ API

กำหนดส่วนหัวคำขอ API ดังนี้:

Accept	Autorization
application/json	Basic cGlvdHJAcXVpY2tjaGF0LmFpOkFUQVRUM3hGZkdGMGlQOVNacEhVZ1o5YUJfWGhmQjZJWjJId3MyaHlsMzEtTlNpYW90Z2tZVzRxQXEwQ3R4UVY1OXFTZkpWWVZNcXlxem42MWRkR0VobmJWNzdzaWtrb19ZWkhtLUgwazFOZGh4WlpQMnltYmZ1SzhBRmlFMnJEUmdqd182N1hkSFFUelFQY2I2U1lrNUFPRlRuVnZvaGxkZUd3djVpM2VrcEFyMVJ4QnJWRncyYz04MEZGQTcyMA==

ใส่ใจรูปแบบส่วนหัว Authorization ให้ถูกต้อง: Basic <base64-encoded email:api token>

ตั้งส่วนหัวคำขอ API

ขั้นตอนที่ 6: ตั้งพารามิเตอร์ query ของคำขอ API

ตั้งพารามิเตอร์ query สองตัวสำหรับคำขอ AI:

• jql รับค่าแบบไดนามิกที่กำหนดก่อนหน้าในส่วน ข้อมูลที่ต้องถามผู้ใช้ก่อน เอเจนต์ AI มีหน้าที่เติมค่าพารามิเตอร์นี้จากสิ่งที่ผู้ใช้พูดในการสนทนา
• fields รับค่าคงที่ สำหรับรายการงาน Jira แต่ละรายการ เราสนใจเพียง summary, description และ status

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

ตั้งพารามิเตอร์ query ของคำขอ API

ตรวจสอบว่าพารามิเตอร์ jql ชี้ไปยังค่าที่กำหนดไว้ก่อนหน้าอย่างถูกต้อง คุณเลือกได้จากเมนู เพิ่มข้อมูล AI

เลือกพารามิเตอร์ไดนามิก jql จากเมนู

ขั้นตอนที่ 7: ตั้งคำอธิบาย API Action

ส่วนสำคัญสุดท้ายของ AI Action ที่ตั้งค่าได้ดีคือคำอธิบาย แม้เอเจนต์ AI จะเข้าใจ endpoint API จาก URL และพารามิเตอร์ได้ดี แต่ยังต้องปรับพฤติกรรมให้ตรงกรณีใช้งานของคุณ

สามประเด็นสำคัญที่สุดในพรอมป์ต์คือ:

• เมื่อใดควรเรียก Action: ระบุทุกสำนวนที่ผู้ใช้อาจเลือก (หา / ค้นหา / มองหา รวมถึงอธิบาย / บอกเกี่ยวกับ / บรรยาย / คืออะไร / สถานะเป็นอย่างไร) เพื่อไม่ให้เอเจนต์ข้ามการเรียกเมื่อผู้ใช้ไม่ได้พูดว่า “ค้นหา”
• คำแนะนำการใช้ไวยากรณ์ JQL ขั้นสูง เพื่อค้นหารายการงาน Jira
• วิธีจัดการผลลัพธ์ว่าง: เอเจนต์ต้องบอกชัดเจน แทนการอ้างว่าไม่มีสิทธิ์เข้าถึง

นี่คือคำอธิบาย API Actionที่ได้:

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 Action

ก่อนทดสอบ AI Action ในการสนทนา เราทดสอบวิธีเรียก API ได้ในแท็บ ทดสอบการตอบกลับ เริ่มจากคำค้นนี้ซึ่งควรคืนทุกรายการงานในโปรเจกต์: project = "Solar System"

ค้นหาทุกรายการงานในโปรเจกต์ Solar System

ด้านล่างคือผลการทดสอบ ตามคาด ระบบแสดงฟิลด์ summary, description และ status ของรายการงานทั้ง 6 รายการบนบอร์ด Jira

ผลลัพธ์แสดงทุกรายการงานในโปรเจกต์ Solar System

ลองอีกคำค้น ครั้งนี้ค้นหารายการงานทั้งหมดที่กล่าวถึง “mercury”: text ~ "mercury"

ค้นหารายการงานที่กล่าวถึง mercury

เรายืนยันแล้วว่า AI Action เรียก endpoint API ถูกต้อง ต่อไปทดสอบการสนทนาทั้งหมดกับเอเจนต์ AI ได้!

ขั้นตอนที่ 9: ทดสอบเอเจนต์ AI ในการสนทนา

กลับไปที่แอป Quickchat AI แล้วทดสอบเอเจนต์ AI ในตัวอย่างการสนทนา

การสนทนาที่ 1

เอเจนต์ AI สรุปรายการงานทั้งหมดในโปรเจกต์

ในการสนทนาง่ายๆ นี้ เอเจนต์ AI ให้ภาพรวมรายการงานทั้งหมดในโปรเจกต์ เมื่อตรวจสอบเบื้องหลังจะพบว่าคำค้นที่เรียก endpoint API คือ: 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 Action ทำงานไม่ว่าผู้ใช้ปลายทางจะใช้สำนวนใด ให้ลองแต่ละพรอมป์ต์ด้านล่างกับ scenario ทดสอบ เอเจนต์ควรเรียก Jira ทุกครั้ง ไม่ใช่เฉพาะคำขอที่ดูเป็นการค้นหา:

• “ค้นหารายการงานที่ยังเปิดทั้งหมดเกี่ยวกับคะแนนสด”
• “ค้นหารายการงานที่มี mercury”
• “อธิบายโปรเจกต์ Solar System”
• “บอกเกี่ยวกับรายการงานที่ยังเปิดในสปรินต์นี้”
• “บรรยายสิ่งที่กำลังดำเนินการอยู่”
• “pluto มีสถานะเป็นอย่างไร”

หากสำนวนใดไม่เรียก AI Action ตรวจสอบว่าคำอธิบาย API Action (ขั้นตอนที่ 7) ระบุคำกริยาเหล่านั้นอย่างชัดเจน

สิ่งที่ควรเกิดขึ้นเมื่อ Jira ไม่มีรายการงานตรงเงื่อนไข

เมื่อ Jira ไม่คืนผลลัพธ์ เอเจนต์ AI ควรบอกชัดเจน เช่น “ฉันตรวจสอบ Jira แล้วแต่ไม่พบรายการงานที่ตรงคำค้น ลองใช้สำนวนที่กว้างขึ้นหรือนำตัวกรองสถานะออก”

หากเอเจนต์กลับตอบว่า “ฉันไม่มีสิทธิ์เข้าถึง Jira ของคุณโดยตรง” แสดงว่า AI Action ไม่ได้ทำงานเลย ตรวจสอบคำอธิบายในขั้นตอนที่ 7 อีกครั้ง และยืนยันว่าระบุคำกริยาที่ไม่ใช่การค้นหาไว้อย่างชัดเจน (explain, tell me about, describe, what is)

สรุป

บทความนี้แสดงวิธีตั้งค่าเอเจนต์ AI ให้ใช้ endpoint API เฉพาะอย่างยืดหยุ่นในการสนทนา การตั้งค่าที่ถูกต้องไม่ได้พร้อมใช้ทันที คุณต้องเพิ่มรายละเอียดกรณีใช้งานที่ต้องการ นำพรอมป์ต์และคำอธิบายในบทความนี้ไปใช้สร้างเอเจนต์ AI ลักษณะเดียวกันได้เลย!

ชอบคู่มือแบบยาวที่มีคำบรรยายหรือไม่ การตั้งค่าเดียวกันมีในบทความบล็อก quickchat.ai ด้วย หน้าคู่มือนี้เป็นแหล่งอ้างอิงหลักที่อัปเดตต่อเนื่อง

ต่อยอด

Action Jira ไม่จำเป็นต้องเป็นคำขอคงที่เพียงแบบเดียว คุณแทรกตัวแปรการสนทนาในตัวและ metadata ที่บันทึกไว้ (เช่น ภาษาผู้เข้าชมหรือค่าที่เก็บไว้ก่อนหน้า) ในฟิลด์ใดก็ได้ และเพิ่มหลาย Actions เพื่อให้เอเจนต์เลือกให้ตรงคำถาม ดูตัวเลือกทั้งหมดในเอกสาร Actions

🎁  เนื้อหาพิเศษ

บทความด้านบนเขียนโดย_มนุษย์_ (ฉันเอง) แต่ 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 Action ที่ต้องการ!