17. API สำหรับการเชื่อมต่อและคีย์ API
API สำหรับการเชื่อมต่อ ช่วยให้โปรแกรม สเปรดชีต หรือสคริปต์ของคุณอ่านข้อมูลโปรเจกต์ของคุณได้โดยอัตโนมัติ ได้แก่ รายการโปรเจกต์ รายการสายเคเบิลและวัสดุ ตารางวงจรและรายการเทอร์มินัลของตู้จ่ายไฟ ใบถอดปริมาณงาน และการจัดชุดเอกสารแบบแปลน API นี้ อ่านได้อย่างเดียว โดยจะไม่แก้ไขแบบหรือโปรเจกต์เลย
ใครขอคีย์ API ได้
ผู้ดูแลระบบเป็นผู้เปิดสิทธิ์ API ให้ทีละบัญชี เมื่อบัญชีของคุณได้รับสิทธิ์แล้ว การ์ด คีย์ API จะปรากฏในหน้า โปรไฟล์ หากไม่มีสิทธิ์จะไม่เห็นการ์ดนี้ แต่ละบัญชีมีคีย์ที่ใช้งานอยู่ได้พร้อมกันสูงสุด 5 คีย์
คีย์มองเห็นโปรเจกต์เดียวกับที่คุณมองเห็น คือโปรเจกต์ของคุณเอง และตามคำขอ รวมถึงโปรเจกต์ที่แชร์ให้คุณ สำหรับโปรเจกต์ที่แชร์ รายการและใบถอดปริมาณงานจะส่งคืนก็ต่อเมื่อการแชร์อนุญาตให้ส่งออกด้วย
การสร้างคีย์
- ในการ์ด คีย์ API ของหน้า โปรไฟล์ คลิก คีย์ใหม่
- ตั้งชื่อให้คีย์ (เช่น ชื่อของโปรแกรมที่จะใช้คีย์นี้)
- เลือกขอบเขต: อ่านโปรเจกต์ ให้รายการโปรเจกต์และข้อมูลโปรเจกต์ ส่วน อ่านเอกสาร ให้รายการต่าง ๆ ใบถอดปริมาณงาน และชุดเอกสารแบบแปลน เลือกเฉพาะสิ่งที่โปรแกรมต้องใช้จริง ๆ
- เลือกวันหมดอายุ: 30, 90 หรือ 365 วัน คีย์ที่หมดอายุจะใช้ไม่ได้อีก ให้สร้างคีย์ใหม่แทน
- กรอกรหัสผ่านปัจจุบันของคุณ (บัญชีที่ไม่มีรหัสผ่านต้องเข้าสู่ระบบใหม่ล่าสุด) สำหรับคีย์แรก ให้ยอมรับเงื่อนไขการใช้งาน API
หลังสร้างแล้ว คีย์จะแสดงเพียงครั้งเดียว ให้คัดลอกแล้วเก็บไว้ในที่ปลอดภัย ภายหลังรายการจะแสดงเฉพาะส่วนนำหน้า (avk_…) พร้อมวันที่สร้างและวันหมดอายุ การใช้งานล่าสุด และจำนวนการเรียก เรายังส่งอีเมลแจ้งเตือนเกี่ยวกับคีย์ใหม่ด้วย (โดยไม่มีตัวคีย์)
การเพิกถอนคีย์
ปุ่ม เพิกถอน ข้างคีย์ในการ์ดจะทำให้คีย์ใช้ไม่ได้ทันที และย้อนกลับไม่ได้ ให้เพิกถอนคีย์เมื่อคุณไม่ใช้แล้ว เมื่อเลิกใช้โปรแกรมที่ใช้คีย์นั้น หรือเมื่อสงสัยว่าคีย์รั่วไหล
คำแนะนำด้านความปลอดภัย
- ปฏิบัติต่อคีย์เหมือนรหัสผ่านของคุณ ใครที่รู้คีย์ก็อ่านโปรเจกต์ของคุณได้ภายในขอบเขตที่กำหนด
- เก็บไว้ในที่เก็บความลับ (ตัวจัดการรหัสผ่าน ตัวแปรสภาพแวดล้อมของเซิร์ฟเวอร์ หรือตัวแปรลับของ CI) ไม่ใช่ในซอร์สโค้ด: ห้ามใส่ในที่เก็บ git สเปรดชีตที่แชร์ หรืออีเมล
- อย่าใช้ในโค้ดที่รันในเบราว์เซอร์ (หน้าเว็บ ส่วนขยายเบราว์เซอร์) เพราะใครก็อ่านได้ที่นั่น คีย์ควรอยู่บนเซิร์ฟเวอร์ ในสคริปต์ หรือในโปรแกรมเดสก์ท็อป
- ให้แต่ละโปรแกรมมีคีย์ของตัวเองที่มีขอบเขตแคบที่สุดและอายุสั้น เพื่อไม่ให้การเพิกถอนคีย์หนึ่งทำให้อย่างอื่นหยุดทำงาน
การใช้งานจากโปรแกรม
คีย์ถูกส่งในส่วนหัวของคำขอเป็น Bearer token: Authorization: Bearer avk_… เอนด์พอยต์อยู่ภายใต้ /api/v1/ (เช่น GET /api/v1/projects) และตอบกลับเป็น JSON คำอธิบายฉบับเต็มในรูปแบบ OpenAPI มีที่ /api/v1/openapi.json เครื่องมือสำหรับนักพัฒนาส่วนใหญ่นำเข้าได้
จำนวนการเรียกถูกจำกัดต่อคีย์และต่อบัญชี (ค่าเริ่มต้น 60 ครั้งต่อนาทีและ 10,000 ครั้งต่อวัน) หากเกิน เซิร์ฟเวอร์จะตอบ 429 ให้รอสักครู่ การเข้าสู่ระบบบนเว็บไซต์ (คุกกี้) ไม่ได้เปิดสิทธิ์ API และคีย์ไม่ได้ให้คุณเข้าสู่ระบบอินเทอร์เฟซเว็บ