วิธีตั้งค่าพารามิเตอร์ส่วนกลางใน Apidog (ส่ง Auth Headers ทุกคำขอ)

คุณมี 40 Endpoint ในโปรเจกต์ และทุก Endpoint ต้องส่งเฮดเดอร์ Authorization: Bearer ... กับ X-Api-Version เดียวกัน การเพิ่มเฮดเดอร์ด้วยมือในทุกคำขอทั้งช้าและเสี่ยงต่อข้อผิดพลาด เช่น บาง Endpoint มีโทเค็น ขณะที่บาง Endpoint ถูกลืมจนเกิด 401 เฉพาะบางเส้นทาง

ลองใช้ Apidog วันนี้

Apidog ช่วยให้กำหนดค่าครั้งเดียวแล้วใช้กับคำขอที่เกี่ยวข้องโดยอัตโนมัติ บทความนี้จะแสดง 3 วิธีสำหรับแนบเฮดเดอร์มาตรฐาน:

1. พารามิเตอร์ส่วนกลาง (Global Parameters)
2. ตัวแปรสภาพแวดล้อม (Environment Variables)
3. สคริปต์ก่อนส่งคำขอระดับโฟลเดอร์ (Folder-scoped Pre-request Script)

หากต้องการทำความเข้าใจตัวแปรเพิ่มเติมก่อนเริ่ม ดูคู่มือ การควบคุมตัวแปรใน Apidog

แนวคิดนี้สอดคล้องกับรูปแบบ HTTP header ทั่วไปตาม ข้อมูลอ้างอิง HTTP Headers ของ MDN: เป็นชุดคู่คีย์/ค่าที่เดินทางไปกับคำขอแต่ละครั้ง ความต่างคือ Apidog ช่วยให้คุณตั้งค่าชุดนี้เพียงครั้งเดียว

“พารามิเตอร์ส่วนกลาง” คืออะไร

พารามิเตอร์ส่วนกลางใน Apidog คือพารามิเตอร์คำขอที่ใช้กับทั้งโปรเจกต์ แทนที่จะผูกกับ Endpoint เดียว เมื่อกำหนดแล้ว Apidog จะเพิ่มพารามิเตอร์ให้คำขอที่ตรงกันโดยอัตโนมัติ

พารามิเตอร์ส่วนกลางรองรับ 4 ตำแหน่ง:

• Headers — สำหรับ Authorization, X-Api-Version และเฮดเดอร์อื่น
• Cookies — สำหรับคุกกี้เซสชัน
• Query — สำหรับค่า URL เช่น ?api_key=...
• Body — สำหรับฟิลด์ที่ทุก request body ต้องมี

ในกรณีนี้ให้เลือก Headers

พารามิเตอร์ระดับ Endpoint มีลำดับความสำคัญสูงกว่าพารามิเตอร์ส่วนกลาง

หาก Endpoint กำหนด Authorization ของตัวเอง ค่านั้นจะถูกใช้แทนค่าส่วนกลาง

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

ตั้งค่าเฮดเดอร์ส่วนกลางสำหรับทุกคำขอ

เป้าหมายคือเพิ่ม Authorization และ X-Api-Version ให้ทุก Endpoint โดยไม่ต้องแก้ไขแต่ละ Endpoint

ขั้นตอนที่ 1: เปิด Environment Management

เปิด Environment Management จากมุมขวาบนของหน้าโปรเจกต์

ส่วนนี้ใช้จัดการพารามิเตอร์ที่ใช้กับทั้งโปรเจกต์ และมีรายละเอียดเพิ่มเติมในเอกสาร Apidog

ขั้นตอนที่ 2: เลือก Headers

เลือกตำแหน่ง Headers หรือ Request Header

หากต้องการตั้งค่ากลางสำหรับคุกกี้, query string หรือ body field ให้เลือก Cookies, Query หรือ Body ตามลำดับ โดยกลไกการทำงานเหมือนกัน

ขั้นตอนที่ 3: เพิ่ม Authorization

สร้างพารามิเตอร์ส่วนกลางรายการแรก:

ฟิลด์	ค่า
Name	Authorization
Type	string
Default Value	Bearer {{token}}
Description	โทเค็น Bearer สำหรับทุก Endpoint ที่ต้องยืนยันตัวตน

จากนั้นเพิ่มเฮดเดอร์เวอร์ชัน:

ฟิลด์	ค่า
Name	X-Api-Version
Type	string
Default Value	2024-08-01
Description	เวอร์ชัน API ที่กำหนดไว้สำหรับทุกคำขอ

ขั้นตอนที่ 4: เปิดใช้งานพารามิเตอร์

เปิดสวิตช์ทางด้านขวาของแต่ละพารามิเตอร์

สวิตช์นี้มีประโยชน์ระหว่างการ debug เพราะคุณสามารถปิดเฮดเดอร์ชั่วคราวได้โดยไม่ต้องลบค่าเดิม

ขั้นตอนที่ 5: บันทึก

บันทึกการตั้งค่า หลังจากนี้ทุกคำขอในโปรเจกต์จะส่ง:

• Authorization
• X-Api-Version

ยกเว้น Endpoint ที่กำหนดเฮดเดอร์ชื่อเดียวกันไว้เอง

ขั้นตอนที่ 6: ตรวจสอบ Actual Request

อย่าเดาว่าเฮดเดอร์ถูกส่งแล้ว ให้ตรวจสอบจากคำขอจริง:

1. ส่ง request ใดก็ได้ในโปรเจกต์
2. เปิดแท็บ Actual Request ใน response console
3. ตรวจสอบว่าเฮดเดอร์ปรากฏในคำขอที่ส่งออกจริง

ตัวอย่าง:

GET /v1/orders/8842 HTTP/1.1
Host: api.yourservice.com
Authorization: Bearer sk_live_7f3a9c2e1b8d4056
X-Api-Version: 2024-08-01

หากเห็นเฮดเดอร์ในแท็บ Actual Request แปลว่า Apidog ส่งค่าออกไปแล้วจริง

เก็บความลับออกจากเฮดเดอร์ด้วยตัวแปร

อย่าใส่ secret โดยตรงในค่า Default เช่น:

Bearer sk_live_7f3a9c2e1b8d4056

ให้ใช้ตัวแปรแทน:

Bearer {{token}}

รูปแบบ Bearer token ถูกกำหนดไว้ใน RFC 6750 และสามารถดูรายละเอียดการใช้ Authorization header ได้จากเอกสาร MDN

สร้างตัวแปร token

1. คลิกไอคอนสภาพแวดล้อม ≡ ที่มุมขวาบน
2. ไปที่ส่วน Global Variables
3. สร้างตัวแปรชื่อ token
4. กำหนดค่าเป็น bearer token จริง
5. คลิก Save

เมื่อส่งคำขอ Apidog จะแทนที่:

Bearer {{token}}

ด้วย:

Bearer <your-real-secret>

ตรวจสอบค่าที่ถูกแทนที่แล้วได้จากแท็บ Actual Request

แนวทางที่แนะนำคือ:

• พารามิเตอร์ส่วนกลาง รับผิดชอบชื่อและโครงสร้างของเฮดเดอร์
• ตัวแปร รับผิดชอบ secret เช่น token หรือ API key

ดูรายละเอียดเพิ่มเติมได้จากบทความ การจัดการสภาพแวดล้อมและข้อมูลลับของ API client

สลับค่าตามสภาพแวดล้อม

โปรเจกต์จริงมักมีหลาย environment เช่น Development, Testing และ Production ซึ่งใช้ server และ token คนละชุด

จัดกลุ่มค่าตัวแปรในแต่ละ environment แล้วสลับผ่าน Environments dropdown ที่อยู่ข้างไอคอน ≡

ตัวอย่างแนวคิด:

Authorization: Bearer {{token}}

Environment	ค่า token
Development	token สำหรับ dev server
Testing	token สำหรับ test server
Production	token สำหรับ production server

ค่า header ยังคงเหมือนเดิม แต่ค่าที่ {{token}} อ้างถึงจะเปลี่ยนตาม environment ที่เลือก

หากกำลังออกแบบ authentication flow เพิ่มเติม ดู คู่มือ Security schemes

เมื่อต้องการเฮดเดอร์เฉพาะโฟลเดอร์

พารามิเตอร์ส่วนกลางใช้กับทั้งโปรเจกต์ ซึ่งอาจกว้างเกินไปในบางกรณี

ตัวอย่าง: มีเพียง Endpoint ภายใต้โฟลเดอร์ /admin ที่ต้องส่ง X-Admin-Scope ขณะที่ Endpoint อื่นไม่ควรส่งเฮดเดอร์นี้

Apidog ไม่มีช่องตั้งค่าเฮดเดอร์ระดับโฟลเดอร์โดยตรง แต่สามารถใช้ pre-request script ที่ระดับโฟลเดอร์ได้:

pm.request.headers.add({
  key: 'X-Admin-Scope',
  value: 'full'
});

เพิ่มสคริปต์นี้ในโฟลเดอร์ที่ต้องการ แล้วทุก request ภายในโฟลเดอร์จะได้รับเฮดเดอร์ดังกล่าว

ใช้วิธีนี้เมื่อ:

• เฮดเดอร์ไม่ควรถูกส่งไปทั้งโปรเจกต์
• ต้องการกำหนดขอบเขตเฉพาะกลุ่ม Endpoint
• ต้องการใช้ logic ก่อนส่งคำขอ

ดูตัวอย่างการเขียนสคริปต์เพิ่มเติมได้จาก สคริปต์ก่อนและหลังคำขอใน Apidog

เลือกใช้วิธีไหนดี

วิธี	ขอบเขต	เหมาะสำหรับ
Global Parameters: Headers	ทั้งโปรเจกต์	Authorization, X-Api-Version หรือเฮดเดอร์มาตรฐานร่วมกัน
Environment Variables	เปลี่ยนตาม environment	token, API key, base URL และข้อมูลลับ
Folder Pre-request Script	เฉพาะโฟลเดอร์	เฮดเดอร์สำหรับกลุ่ม Endpoint เช่น /admin

ข้อควรตรวจสอบ:

• อย่าสร้างพารามิเตอร์ส่วนกลางชื่อซ้ำกัน
• ตรวจสอบ Type ให้ตรงกับรูปแบบข้อมูลที่ใช้
• จำกฎลำดับความสำคัญ: ค่าในระดับ Endpoint จะแทนที่ค่าส่วนกลาง
• ตรวจสอบผลลัพธ์จาก Actual Request ทุกครั้งหลังตั้งค่า

เอกสารสำหรับทั้งสามฟีเจอร์ไม่ได้ระบุข้อจำกัดตามระดับแพ็กเกจ

ใช้งานกับ CI ผ่าน Apidog CLI

พารามิเตอร์ส่วนกลางและ environment variables ใช้ได้กับการรันอัตโนมัติผ่าน Apidog CLI ด้วย

เมื่อรัน scenario ที่บันทึกไว้ผ่าน CLI และระบุ environment ID การรันจะใช้ค่าตัวแปรของ environment นั้น รวมถึง {{token}} และค่า X-Api-Version

ติดตั้ง CLI โดยต้องใช้ Node.js v16+:

npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>

รัน scenario ด้วย environment ที่ต้องการ:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli

ความหมายของ flag หลัก:

• -t — ID ของ test scenario
• -e — ID ของ environment ที่ต้องการใช้
• -r — รูปแบบรายงาน เช่น cli, html หรือ junit

ด้วยรูปแบบนี้ คุณกำหนด header และตัวแปรเพียงครั้งเดียว แล้วการรันผ่าน CI จะใช้ค่าชุดเดียวกับใน GUI

ดูรายละเอียดเพิ่มเติม:

• คู่มือการติดตั้ง Apidog CLI
• คู่มือ Apidog CLI ใน GitHub Actions

คำถามที่พบบ่อย

พารามิเตอร์ส่วนกลางจะแทนที่เฮดเดอร์ของ Endpoint หรือไม่

ไม่ ค่าในระดับ Endpoint มีลำดับความสำคัญสูงกว่า

หาก Endpoint มี Authorization ของตัวเอง ค่านั้นจะถูกส่งแทนค่าจาก global parameter

ควรเก็บ token ไว้ที่ใด

ใช้ environment variable หรือ global variable แทนการใส่ token เป็นข้อความธรรมดาใน header

ตัวอย่าง:

Authorization: Bearer {{token}}

หากต้องการดึง token จาก login response แล้วนำกลับมาใช้ ดู การดึงตัวแปรด้วย JSONPath

จะยืนยันได้อย่างไรว่าเฮดเดอร์ถูกส่งจริง

ส่ง request แล้วเปิดแท็บ Actual Request

แท็บนี้แสดง request ที่ถูกส่งจริง รวมถึงค่าตัวแปรที่ถูกแทนที่แล้ว

เพิ่มเฮดเดอร์เฉพาะโฟลเดอร์ได้หรือไม่

ได้ โดยเพิ่ม pre-request script ในโฟลเดอร์:

pm.request.headers.add({
  key: 'X-Admin-Scope',
  value: 'full'
});

ต้องใช้แพ็กเกจแบบชำระเงินหรือไม่

เอกสารของฟีเจอร์ global parameters, environment variables และ folder-level pre-request scripts ไม่ได้ระบุข้อจำกัดตาม tier

สรุป

การตั้งค่าเฮดเดอร์ร่วมกันใน Apidog ทำได้โดย:

1. สร้าง header เป็น Global Parameter ใน Environment Management
2. ใช้ตัวแปร เช่น {{token}} สำหรับเก็บ secret
3. ตรวจสอบคำขอจริงจากแท็บ Actual Request
4. ใช้ pre-request script เมื่อเฮดเดอร์ต้องมีเฉพาะบางโฟลเดอร์
5. ระบุ environment ผ่าน CLI เมื่อต้องรัน scenario ใน CI

เริ่มตั้งค่า header ส่วนกลางในโปรเจกต์ของคุณได้ด้วยการดาวน์โหลด Apidog