#การใช้งาน API คีย์ใน NocoBase

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

#1 ทำความเข้าใจ API คีย์

API คีย์คือโทเค็นความปลอดภัยที่ใช้ในการยืนยันตัวตนคำขอ API จากผู้ใช้ที่ได้รับอนุญาตครับ/ค่ะ ทำหน้าที่เป็นข้อมูลรับรองเพื่อตรวจสอบยืนยันตัวตนของผู้ร้องขอเมื่อเข้าถึงระบบ NocoBase ผ่านเว็บแอปพลิเคชัน แอปพลิเคชันมือถือ หรือสคริปต์แบ็กเอนด์

ในส่วนหัวคำขอ HTTP จะมีรูปแบบดังนี้:

Authorization: Bearer {API คีย์}

คำนำหน้า "Bearer" บ่งชี้ว่าสตริงที่ตามมาคือ API คีย์ที่ได้รับการยืนยันตัวตนแล้ว ซึ่งใช้เพื่อตรวจสอบสิทธิ์ของผู้ร้องขอครับ/ค่ะ

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

API คีย์มักถูกใช้ในสถานการณ์ต่อไปนี้ครับ/ค่ะ:

1. การเข้าถึงจากแอปพลิเคชันไคลเอนต์: เว็บเบราว์เซอร์และแอปพลิเคชันมือถือใช้ API คีย์เพื่อยืนยันตัวตนผู้ใช้ ทำให้มั่นใจว่าเฉพาะผู้ใช้ที่ได้รับอนุญาตเท่านั้นที่สามารถเข้าถึงข้อมูลได้
2. การทำงานอัตโนมัติ: กระบวนการเบื้องหลังและงานที่ตั้งเวลาไว้ใช้ API คีย์เพื่อดำเนินการอัปเดต การซิงโครไนซ์ข้อมูล และการบันทึกข้อมูลได้อย่างปลอดภัย
3. การพัฒนาและทดสอบ: นักพัฒนาใช้ API คีย์ในระหว่างการดีบักและการทดสอบ เพื่อจำลองคำขอที่ได้รับการยืนยันตัวตนและตรวจสอบการตอบกลับ API

API คีย์มอบประโยชน์ด้านความปลอดภัยหลายประการ เช่น การยืนยันตัวตน การตรวจสอบการใช้งาน การจำกัดอัตราคำขอ และการป้องกันภัยคุกคาม ซึ่งช่วยให้ NocoBase ทำงานได้อย่างเสถียรและปลอดภัยครับ/ค่ะ

#2 การสร้าง API คีย์ใน NocoBase

#2.1 เปิดใช้งานปลั๊กอินการยืนยันตัวตน: API คีย์

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

#2.2 สร้างคอลเลกชันทดสอบ

เพื่อวัตถุประสงค์ในการสาธิต ให้สร้างคอลเลกชันชื่อ todos พร้อมฟิลด์ต่อไปนี้ครับ/ค่ะ:

• id
• title (ชื่อเรื่อง)
• completed (เสร็จสมบูรณ์แล้วหรือไม่)

เพิ่มข้อมูลตัวอย่างบางส่วนลงในคอลเลกชัน:

• กินข้าว
• นอน
• เล่นเกม

#2.3 สร้างและมอบหมายบทบาท

API คีย์จะผูกกับบทบาทผู้ใช้ และระบบจะกำหนดสิทธิ์ในการร้องขอตามบทบาทที่ได้รับมอบหมายครับ/ค่ะ ก่อนสร้าง API คีย์ คุณต้องสร้างบทบาทและกำหนดค่าสิทธิ์ที่เหมาะสมก่อน สร้างบทบาทชื่อ "บทบาท API รายการสิ่งที่ต้องทำ" และให้สิทธิ์เข้าถึงคอลเลกชัน todos ได้อย่างเต็มรูปแบบ

หาก "บทบาท API รายการสิ่งที่ต้องทำ" ไม่ปรากฏขึ้นเมื่อสร้าง API คีย์ โปรดตรวจสอบให้แน่ใจว่าผู้ใช้ปัจจุบันได้รับมอบหมายบทบาทนี้แล้วครับ/ค่ะ:

หลังจากมอบหมายบทบาทแล้ว ให้รีเฟรชหน้าและไปที่หน้าการจัดการ API คีย์ คลิก "เพิ่ม API คีย์" เพื่อตรวจสอบว่า "บทบาท API รายการสิ่งที่ต้องทำ" ปรากฏในการเลือกบทบาทแล้ว

เพื่อการควบคุมการเข้าถึงที่ดีขึ้น คุณอาจพิจารณาสร้างบัญชีผู้ใช้เฉพาะ (เช่น "ผู้ใช้ API รายการสิ่งที่ต้องทำ") สำหรับการจัดการและทดสอบ API คีย์โดยเฉพาะครับ/ค่ะ มอบหมาย "บทบาท API รายการสิ่งที่ต้องทำ" ให้กับผู้ใช้รายนี้

#2.4 สร้างและบันทึก API คีย์

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

ตัวอย่าง API คีย์:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOjEsInJvbGVOYW1lIjoidG9kb3MiLCJpYXQiOjE3NDA5OTY1ODAsImV4cCI6MzMyOTg1OTY1ODB9.tXF2FCAzFNgZFPXqSBbWAfEvWkQwz0-mtKnmOTZT-5M

#2.5 ข้อควรทราบที่สำคัญ

• ระยะเวลาที่ API คีย์ใช้งานได้จะถูกกำหนดโดยการตั้งค่าการหมดอายุที่กำหนดค่าไว้ในขณะที่สร้างครับ/ค่ะ
• การสร้างและการตรวจสอบ API คีย์ขึ้นอยู่กับตัวแปรสภาพแวดล้อม APP_KEY ห้ามแก้ไขตัวแปรนี้เด็ดขาด เพราะจะทำให้ API คีย์ที่มีอยู่ทั้งหมดในระบบไม่ถูกต้องครับ/ค่ะ

#3 การทดสอบการยืนยันตัวตนด้วย API คีย์

#3.1 การใช้งานปลั๊กอินเอกสาร API

เปิดปลั๊กอินเอกสาร API เพื่อดูเมธอดคำขอ, URL, พารามิเตอร์ และส่วนหัวสำหรับปลายทาง API แต่ละรายการครับ/ค่ะ

#3.2 ทำความเข้าใจการดำเนินการ CRUD พื้นฐาน

NocoBase มี API สำหรับการดำเนินการ CRUD (Create, Read, Update, Delete) มาตรฐานสำหรับการจัดการข้อมูลดังนี้ครับ/ค่ะ:

• การสอบถามรายการ (list API):

  GET {baseURL}/{collectionName}:list
  ส่วนหัวคำขอ:
  - Authorization: Bearer <API คีย์>
  

• การสร้างบันทึก (create API):

  POST {baseURL}/{collectionName}:create
  
  ส่วนหัวคำขอ:
  - Authorization: Bearer <API คีย์>
  
  เนื้อหาคำขอ (ในรูปแบบ JSON) ตัวอย่างเช่น:
      {
          "title": "123"
      }

• การอัปเดตบันทึก (update API):

  POST {baseURL}/{collectionName}:update?filterByTk={id}
  ส่วนหัวคำขอ:
  - Authorization: Bearer <API คีย์>
  
  เนื้อหาคำขอ (ในรูปแบบ JSON) ตัวอย่างเช่น:
      {
          "title": "123",
          "completed": true
      }

• การลบบันทึก (delete API):

  POST {baseURL}/{collectionName}:destroy?filterByTk={id}
  ส่วนหัวคำขอ:
  - Authorization: Bearer <API คีย์>

โดยที่:

• {baseURL}: URL ระบบ NocoBase ของคุณ
• {collectionName}: ชื่อคอลเลกชัน

ตัวอย่าง: สำหรับอินสแตนซ์ภายในเครื่องที่ localhost:13000 พร้อมคอลเลกชันชื่อ todos:

http://localhost:13000/api/todos:list

#3.3 การทดสอบด้วย Postman

สร้างคำขอ GET ใน Postman ด้วยการกำหนดค่าดังนี้ครับ/ค่ะ:

• URL: ปลายทางคำขอ (เช่น http://localhost:13000/api/todos:list)
• Headers: เพิ่มส่วนหัว Authorization ด้วยค่า:

Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOjEsInJvbGVOYW1lIjoidG9kb3MiLCJpYXQiOjE3NDA5OTY1ODAsImV4cCI6MzMyOTg1OTY1ODB9.tXF2FCAzFNgZFPXqSBbWAfEvWkQwz0-mtKnmOTZT-5M

การตอบกลับที่สำเร็จ:

{
    "data": [
        {
            "createdAt": "2025-03-03T09:57:36.728Z",
            "updatedAt": "2025-03-03T09:57:36.728Z",
            "completed": null,
            "createdById": 1,
            "id": 1,
            "title": "eat food",
            "updatedById": 1
        }
    ],
    "meta": {
        "count": 1,
        "page": 1,
        "pageSize": 20,
        "totalPage": 1
    }
}

การตอบกลับข้อผิดพลาด (API คีย์ไม่ถูกต้อง/หมดอายุ):

{
    "errors": [
        {
            "message": "Your session has expired. Please sign in again.",
            "code": "INVALID_TOKEN"
        }
    ]
}

การแก้ไขปัญหา: หากการยืนยันตัวตนล้มเหลว โปรดตรวจสอบสิทธิ์บทบาท, การผูก API คีย์ และรูปแบบโทเค็นอีกครั้งครับ/ค่ะ

#3.4 ส่งออกโค้ดคำขอ

Postman ช่วยให้คุณสามารถส่งออกคำขอในรูปแบบต่างๆ ได้ครับ/ค่ะ ตัวอย่างคำสั่ง cURL:

curl --location 'http://localhost:13000/api/todos:list' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOjEsInJvbGVOYW1lIjoidG9kb3MiLCJpYXQiOjE3NDA5OTY1ODAsImV4cCI6MzMyOTg1OTY1ODB9.tXF2FCAzFNgZFPXqSBbWAfEvWkQwz0-mtKnmOTZT-5M'

#4 การใช้งาน API คีย์ในบล็อก JS

NocoBase 2.0 รองรับการเขียนโค้ด JavaScript ดั้งเดิมโดยตรงในหน้าต่างๆ โดยใช้บล็อก JS ครับ/ค่ะ ตัวอย่างนี้จะสาธิตวิธีการดึงข้อมูล API ภายนอกโดยใช้ API คีย์

#การสร้างบล็อก JS

ในหน้า NocoBase ของคุณ ให้เพิ่มบล็อก JS และใช้โค้ดต่อไปนี้เพื่อดึงข้อมูลรายการสิ่งที่ต้องทำครับ/ค่ะ:

// ใช้ API คีย์เพื่อดึงข้อมูลรายการสิ่งที่ต้องทำ
async function fetchTodos() {
  try {
    // แสดงข้อความกำลังโหลด
    ctx.message.loading('กำลังดึงข้อมูล...');

    // โหลดไลบรารี axios สำหรับคำขอ HTTP
    const axios = await ctx.requireAsync('https://cdn.jsdelivr.net/npm/axios@1.6.0/dist/axios.min.js');

    if (!axios) {
      ctx.message.error('ไม่สามารถโหลดไลบรารี HTTP ได้');
      return;
    }

    // API คีย์ (แทนที่ด้วย API คีย์จริงของคุณ)
    const apiKey = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOjEsInJvbGVOYW1lIjoidG9kb3MiLCJpYXQiOjE3NDA5OTY1ODAsImV4cCI6MzMyOTg1OTY1ODB9.tXF2FCAzFNgZFPXqSBbWAfEvWkQwz0-mtKnmOTZT-5M';

    // ทำการร้องขอ API
    const response = await axios.get('http://localhost:13000/api/todos:list', {
      headers: {
        'Authorization': `Bearer ${apiKey}`
      }
    });

    // แสดงผลลัพธ์
    console.log('รายการสิ่งที่ต้องทำ:', response.data);
    ctx.message.success(`ดึงข้อมูลสำเร็จ ${response.data.data.length} รายการ`);

    // คุณสามารถประมวลผลข้อมูลได้ที่นี่
    // ตัวอย่างเช่น: แสดงในตาราง, อัปเดตฟิลด์ฟอร์ม ฯลฯ

  } catch (error) {
    console.error('เกิดข้อผิดพลาดในการดึงข้อมูล:', error);
    ctx.message.error('ไม่สามารถดึงข้อมูลได้: ' + error.message);
  }
}

// เรียกใช้ฟังก์ชัน
fetchTodos();

#ประเด็นสำคัญ

• ctx.requireAsync(): โหลดไลบรารีภายนอก (เช่น axios) แบบไดนามิกสำหรับคำขอ HTTP
• ctx.message: แสดงการแจ้งเตือนผู้ใช้ (กำลังโหลด, สำเร็จ, ข้อความข้อผิดพลาด)
• การยืนยันตัวตนด้วย API คีย์: ส่ง API คีย์ในส่วนหัว Authorization โดยใช้คำนำหน้า Bearer
• การจัดการการตอบกลับ: ประมวลผลข้อมูลที่ส่งกลับมาตามความจำเป็น (แสดง, แปลง ฯลฯ)

#5 สรุป

คู่มือนี้ครอบคลุมเวิร์กโฟลว์ที่สมบูรณ์สำหรับการใช้งาน API คีย์ใน NocoBase ดังนี้ครับ/ค่ะ:

1. การตั้งค่า: เปิดใช้งานปลั๊กอิน API คีย์และสร้างคอลเลกชันทดสอบ
2. การกำหนดค่า: สร้างบทบาทพร้อมสิทธิ์ที่เหมาะสมและสร้าง API คีย์
3. การทดสอบ: ตรวจสอบการยืนยันตัวตนด้วย API คีย์โดยใช้ Postman และปลั๊กอินเอกสาร API
4. การผสานรวม: ใช้งาน API คีย์ในบล็อก JS

แหล่งข้อมูลเพิ่มเติม:

• เอกสารปลั๊กอิน API คีย์
• ปลั๊กอินเอกสาร API