#การเชื่อมต่อ HTTP Request ในเวิร์กโฟลว์

โหนด HTTP Request ช่วยให้เวิร์กโฟลว์ของ NocoBase สามารถส่งคำขอไปยังบริการ HTTP ใดก็ได้ เพื่อแลกเปลี่ยนข้อมูลและเชื่อมโยงระบบภายนอกเข้าด้วยกันครับ/ค่ะ

#ภาพรวม

โหนด HTTP Request เป็นส่วนประกอบหลักในการเชื่อมต่อระบบในเวิร์กโฟลว์ ช่วยให้คุณสามารถเรียกใช้ API ของบุคคลที่สาม, อินเทอร์เฟซบริการภายใน หรือบริการเว็บอื่นๆ ในระหว่างการทำงานของเวิร์กโฟลว์ เพื่อดึงข้อมูลหรือกระตุ้นการทำงานภายนอกได้ครับ/ค่ะ

#กรณีการใช้งานทั่วไป

#การดึงข้อมูล

• การสอบถามข้อมูลจากภายนอก: ดึงข้อมูลแบบเรียลไทม์จาก API สภาพอากาศ, API อัตราแลกเปลี่ยน เป็นต้น
• การแปลงที่อยู่: เรียกใช้ API บริการแผนที่เพื่อแปลงที่อยู่และระบุพิกัดทางภูมิศาสตร์
• การซิงค์ข้อมูลองค์กร: ดึงข้อมูลลูกค้า, คำสั่งซื้อ ฯลฯ จากระบบ CRM, ERP

#การกระตุ้นการทำงานทางธุรกิจ

• การแจ้งเตือน: เรียกใช้บริการ SMS, อีเมล, WeCom (WeChat Work) เพื่อส่งการแจ้งเตือน
• คำขอชำระเงิน: ส่งคำขอชำระเงิน, คืนเงิน ฯลฯ ไปยัง Payment Gateway
• การจัดการคำสั่งซื้อ: ส่งใบนำส่งสินค้า, สอบถามสถานะการจัดส่งไปยังระบบโลจิสติกส์

#การเชื่อมโยงระบบ

• การเรียกใช้ไมโครเซอร์วิส: เรียกใช้ API ของบริการอื่นๆ ในสถาปัตยกรรมไมโครเซอร์วิส
• การรายงานข้อมูล: รายงานข้อมูลทางธุรกิจไปยังแพลตฟอร์มวิเคราะห์ข้อมูล, ระบบมอนิเตอร์
• บริการจากภายนอก: เชื่อมต่อบริการ AI, การรู้จำ OCR, การสังเคราะห์เสียงพูด ฯลฯ

#การทำงานอัตโนมัติ

• งานตามกำหนดเวลา: เรียกใช้ API ภายนอกเป็นประจำเพื่อซิงค์ข้อมูล
• การตอบสนองต่อเหตุการณ์: เรียกใช้ API ภายนอกโดยอัตโนมัติเมื่อข้อมูลมีการเปลี่ยนแปลงเพื่อแจ้งเตือนระบบที่เกี่ยวข้อง
• เวิร์กโฟลว์การอนุมัติ: ส่งคำขออนุมัติผ่าน API ของระบบอนุมัติ

#คุณสมบัติเด่น

#รองรับ HTTP อย่างสมบูรณ์

• รองรับเมธอด HTTP ทั้งหมด เช่น GET, POST, PUT, PATCH, DELETE
• รองรับการกำหนดค่าส่วนหัว (Headers) ของคำขอเอง
• รองรับรูปแบบข้อมูลหลากหลาย: JSON, Form Data, XML เป็นต้น
• รองรับการส่งพารามิเตอร์หลายรูปแบบ: พารามิเตอร์ URL, พารามิเตอร์ Path, Request Body เป็นต้น

#การประมวลผลข้อมูลที่ยืดหยุ่น

• การอ้างอิงตัวแปร: สร้างคำขอแบบไดนามิกโดยใช้ตัวแปรในเวิร์กโฟลว์
• การแยกวิเคราะห์การตอบกลับ: แยกวิเคราะห์การตอบกลับแบบ JSON โดยอัตโนมัติและดึงข้อมูลที่ต้องการ
• การแปลงข้อมูล: แปลงรูปแบบข้อมูลทั้งคำขอและการตอบกลับ
• การจัดการข้อผิดพลาด: กำหนดค่ากลยุทธ์การลองใหม่ (Retry), การตั้งค่า Timeout, และตรรกะการจัดการข้อผิดพลาด

#การยืนยันตัวตนเพื่อความปลอดภัย

• Basic Auth: การยืนยันตัวตนแบบ HTTP Basic
• Bearer Token: การยืนยันตัวตนด้วยโทเค็น
• API Key: การยืนยันตัวตนด้วย API Key ที่กำหนดเอง
• Custom Headers: รองรับวิธีการยืนยันตัวตนแบบใดก็ได้ผ่านส่วนหัวที่กำหนดเอง

#ขั้นตอนการใช้งาน

#1. ตรวจสอบว่าปลั๊กอินเปิดใช้งานอยู่

โหนด HTTP Request เป็นคุณสมบัติในตัวของปลั๊กอิน เวิร์กโฟลว์ ครับ/ค่ะ โปรดตรวจสอบให้แน่ใจว่าได้เปิดใช้งานปลั๊กอิน เวิร์กโฟลว์ แล้ว

#2. เพิ่มโหนด HTTP Request ลงในเวิร์กโฟลว์

1. สร้างหรือแก้ไขเวิร์กโฟลว์
2. เพิ่มโหนด HTTP Request ในตำแหน่งที่ต้องการ

3. กำหนดค่าพารามิเตอร์ของคำขอ

#3. กำหนดค่าพารามิเตอร์ของคำขอ

#การตั้งค่าพื้นฐาน

• Request URL: ที่อยู่ API เป้าหมาย, รองรับการใช้ตัวแปร

  https://api.example.com/users/{{$context.userId}}

• Request Method: เลือก GET, POST, PUT, DELETE เป็นต้น

• Request Headers: กำหนดค่า HTTP Headers

  {
    "Content-Type": "application/json",
    "Authorization": "Bearer {{$context.apiKey}}"
  }

• Request Parameters:

  • Query Parameters: พารามิเตอร์สำหรับ URL Query
  • Body Parameters: ข้อมูลใน Request Body (สำหรับ POST/PUT)

#การตั้งค่าขั้นสูง

• Timeout: กำหนดเวลาหมดอายุของคำขอ (ค่าเริ่มต้น 30 วินาที)
• Retry on Failure: กำหนดจำนวนครั้งที่ลองใหม่และช่วงเวลาการลองใหม่
• Ignore Failure: เวิร์กโฟลว์จะยังคงทำงานต่อไปแม้ว่าคำขอจะล้มเหลว
• Proxy Settings: กำหนดค่า HTTP Proxy (หากจำเป็น)

#4. การใช้ข้อมูลจากการตอบกลับ

หลังจากที่โหนด HTTP Request ทำงานเสร็จสิ้น ข้อมูลจากการตอบกลับสามารถนำไปใช้ในโหนดถัดไปได้ครับ/ค่ะ

• {{$node.data.status}}: รหัสสถานะ HTTP
• {{$node.data.headers}}: ส่วนหัวของการตอบกลับ
• {{$node.data.data}}: ข้อมูลใน Response Body
• {{$node.data.error}}: ข้อความแสดงข้อผิดพลาด (หากคำขอล้มเหลว)

#ตัวอย่างสถานการณ์

#ตัวอย่างที่ 1: การดึงข้อมูลสภาพอากาศ

// การตั้งค่า
URL: https://api.weather.com/v1/current
Method: GET
Query Parameters:
  city: {{$context.city}}
  key: your-api-key

// การใช้ข้อมูลตอบกลับ
Temperature: {{$node.data.data.temperature}}
Weather: {{$node.data.data.condition}}

#ตัวอย่างที่ 2: การส่งข้อความ WeCom (WeChat Work)

// การตั้งค่า
URL: https://qyapi.weixin.qq.com/cgi-bin/message/send
Method: POST
Headers:
  Content-Type: application/json
Body:
{
  "touser": "{{$context.userId}}",
  "msgtype": "text",
  "agentid": 1000001,
  "text": {
    "content": "คำสั่งซื้อ {{$context.orderId}} ได้ถูกจัดส่งแล้ว"
  }
}

#ตัวอย่างที่ 3: การสอบถามสถานะการชำระเงิน

// การตั้งค่า
URL: https://api.payment.com/v1/orders/{{$context.orderId}}/status
Method: GET
Headers:
  Authorization: Bearer {{$context.apiKey}}
  Content-Type: application/json

// การตรวจสอบเงื่อนไข
ถ้า {{$node.data.data.status}} เท่ากับ "paid"
  - อัปเดตสถานะคำสั่งซื้อเป็น "ชำระเงินแล้ว"
  - ส่งการแจ้งเตือนการชำระเงินสำเร็จ
มิฉะนั้น ถ้า {{$node.data.data.status}} เท่ากับ "pending"
  - คงสถานะคำสั่งซื้อเป็น "รอการชำระเงิน"
มิฉะนั้น
  - บันทึก Log การชำระเงินล้มเหลว
  - แจ้งผู้ดูแลระบบเพื่อจัดการความผิดปกติ

#ตัวอย่างที่ 4: การซิงค์ข้อมูลไปยัง CRM

// การตั้งค่า
URL: https://api.crm.com/v1/customers
Method: POST
Headers:
  X-API-Key: {{$context.crmApiKey}}
  Content-Type: application/json
Body:
{
  "name": "{{$context.customerName}}",
  "email": "{{$context.email}}",
  "phone": "{{$context.phone}}",
  "source": "NocoBase",
  "created_at": "{{$context.createdAt}}"
}

#การตั้งค่าการยืนยันตัวตน

#Basic Authentication

Headers:
  Authorization: Basic base64(username:password)

#Bearer Token

Headers:
  Authorization: Bearer your-access-token

#API Key

// ในส่วนหัว (Header)
Headers:
  X-API-Key: your-api-key

// หรือใน Query
Query Parameters:
  api_key: your-api-key

#OAuth 2.0

ต้องได้รับ access_token ก่อน จากนั้นจึงนำมาใช้ดังนี้ครับ/ค่ะ

Headers:
  Authorization: Bearer {{$context.accessToken}}

#การจัดการข้อผิดพลาดและการดีบัก

#ข้อผิดพลาดที่พบบ่อย

1. Connection Timeout: ตรวจสอบการเชื่อมต่อเครือข่าย, เพิ่มเวลา Timeout
2. 401 Unauthorized: ตรวจสอบข้อมูลการยืนยันตัวตนว่าถูกต้องหรือไม่
3. 404 Not Found: ตรวจสอบ URL ว่าถูกต้องหรือไม่
4. 500 Server Error: ตรวจสอบสถานะบริการของผู้ให้บริการ API

#เคล็ดลับการดีบัก

1. ใช้โหนด Log: เพิ่มโหนด Log ก่อนและหลัง HTTP Request เพื่อบันทึกข้อมูลคำขอและการตอบกลับ

2. ตรวจสอบ Log การทำงาน: Log การทำงานของเวิร์กโฟลว์จะแสดงข้อมูลคำขอและการตอบกลับโดยละเอียด

3. เครื่องมือทดสอบ: ใช้เครื่องมืออย่าง Postman, cURL เพื่อทดสอบ API ก่อน

4. การจัดการข้อผิดพลาด: เพิ่มเงื่อนไขเพื่อจัดการสถานะการตอบกลับที่แตกต่างกัน

ถ้า {{$node.data.status}} >= 200 และ {{$node.data.status}} < 300
  - ดำเนินการตามตรรกะเมื่อสำเร็จ
มิฉะนั้น
  - ดำเนินการตามตรรกะเมื่อล้มเหลว
  - บันทึกข้อผิดพลาด: {{$node.data.error}}

#ข้อแนะนำในการปรับปรุงประสิทธิภาพ

#1. ใช้การประมวลผลแบบอะซิงโครนัส (Asynchronous)

สำหรับคำขอที่ไม่ต้องการผลลัพธ์ทันที ลองพิจารณาใช้เวิร์กโฟลว์แบบอะซิงโครนัสครับ/ค่ะ

#2. กำหนดค่า Timeout ให้เหมาะสม

กำหนดค่า Timeout ตามเวลาตอบสนองจริงของ API เพื่อหลีกเลี่ยงการรอนานเกินไป

#3. ใช้กลยุทธ์การแคช (Caching)

สำหรับข้อมูลที่ไม่ค่อยเปลี่ยนแปลง (เช่น การตั้งค่า, พจนานุกรม) ลองพิจารณาแคชผลลัพธ์การตอบกลับไว้ครับ/ค่ะ

#4. การประมวลผลแบบกลุ่ม (Batch Processing)

หากจำเป็นต้องเรียกใช้ API เดียวกันหลายครั้ง ลองพิจารณาใช้ Batch API (หาก API นั้นรองรับ)

#5. การลองใหม่เมื่อเกิดข้อผิดพลาด (Error Retry)

กำหนดกลยุทธ์การลองใหม่ที่เหมาะสม แต่หลีกเลี่ยงการลองใหม่มากเกินไปซึ่งอาจทำให้เกิดการจำกัดอัตราการเรียกใช้ API (Rate Limiting)

#แนวทางปฏิบัติที่ดีที่สุดด้านความปลอดภัย

#1. ปกป้องข้อมูลที่ละเอียดอ่อน

• อย่าเปิดเผยข้อมูลที่ละเอียดอ่อนใน URL
• ใช้ HTTPS เพื่อเข้ารหัสการส่งข้อมูล
• ใช้ตัวแปรสภาพแวดล้อม (Environment Variables) หรือระบบจัดการการตั้งค่าสำหรับข้อมูลที่ละเอียดอ่อน เช่น API Key

#2. ตรวจสอบความถูกต้องของข้อมูลตอบกลับ

// ตรวจสอบสถานะการตอบกลับ
if (![200, 201].includes($node.data.status)) {
  throw new Error('API request failed');
}

// ตรวจสอบรูปแบบข้อมูล
if (!$node.data.data || !$node.data.data.id) {
  throw new Error('Invalid response data');
}

#3. จำกัดความถี่ในการส่งคำขอ (Rate Limiting)

ปฏิบัติตามข้อจำกัดอัตราการเรียกใช้ (Rate Limit) ของ API ภายนอก เพื่อหลีกเลี่ยงการถูกบล็อก

#4. การปกปิดข้อมูลที่ละเอียดอ่อนใน Log (Log Sanitization)

เมื่อบันทึก Log ควรระมัดระวังในการปกปิดข้อมูลที่ละเอียดอ่อน (เช่น รหัสผ่าน, คีย์)

#การเปรียบเทียบกับ Webhook

คุณสมบัติทั้งสองนี้ทำงานเสริมกัน เพื่อสร้างโซลูชันการเชื่อมโยงระบบที่สมบูรณ์แบบครับ/ค่ะ

#แหล่งข้อมูลที่เกี่ยวข้อง

• เอกสารปลั๊กอินเวิร์กโฟลว์
• เวิร์กโฟลว์: โหนด HTTP Request
• เวิร์กโฟลว์: Webhook Trigger
• การยืนยันตัวตนด้วย API Key
• ปลั๊กอินเอกสาร API