เริ่มต้น
คีย์และการยืนยันตัวตน
ชุดข้อมูลหนึ่งชุดมีคีย์สองดอก — ดอกหนึ่งอยู่ในหน้าเว็บได้ อีกดอกอยู่ที่เซิร์ฟเวอร์
ส่งคีย์ไปยังไง
Authorization: Bearer nsk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxไม่มีพารามิเตอร์บอกว่าชุดข้อมูลไหนใน URL เพราะคีย์บอกแทนแล้ว — ค่าเดียวที่ใส่ลงไปแล้วไม่โดนปฏิเสธคือค่าที่คีย์รู้อยู่แล้ว ซึ่งแปลว่ามันไม่ใช่พารามิเตอร์
สองดอก ได้มาพร้อมชุดข้อมูล
ตอนสร้างชุดข้อมูล ระบบออกคีย์ให้สองดอกทันที ไม่ต้องกดสร้างเอง — เพราะถ้าให้เลือกได้แค่ดอกเดียว คนที่ทำหน้าเว็บจะต้องเลือกระหว่างหน้าเว็บที่ค้นหาไม่ได้ กับหน้าเว็บที่แบกคีย์ซึ่งลบข้อมูลทั้งชุดได้ ทั้งสองทางไม่ควรมีใครต้องเลือก
| ฟิลด์ | ความหมาย |
|---|---|
client | ค้นหา สินค้าใกล้เคียง คำแนะนำ ตัวกรอง และอ่านระเบียนตาม id — วางในหน้าเว็บได้ · จากเบราว์เซอร์ใช้ได้เฉพาะหน้าเว็บที่คุณลงทะเบียนไว้ |
service | ทุกอย่างที่ client ทำได้ บวกกับเขียน ลบ sync ตั้งโครง คำพ้อง ความหมาย และหมวด รวมถึง explain — เก็บไว้ที่เซิร์ฟเวอร์เท่านั้น |
ใช้ client key ในเส้นที่ต้องใช้ service key ได้ 403 ที่บอกว่าต้องใช้ดอกไหน · คีย์ทั้งสองดอกเปิดได้แค่ /v1 — เส้นของคอนโซลใต้ /api ใช้การล็อกอิน คีย์ที่ส่งไปที่นั่นได้ 403 ทุกเส้น
service key ที่ส่งมาจากหน้าเว็บ — คำขอที่มีหัวข้อ Origin ซึ่งเบราว์เซอร์ใส่ให้เสมอ — ยังได้คำตอบตามปกติ หน้า admin ภายในที่ถือ service key จึงไม่พัง แต่คำตอบมีคำเตือน service_key_in_browser ทั้งในหัวข้อ NS-Warning และใน warnings ของ JSON: คีย์นี้แก้และลบชุดข้อมูลได้ และใครเปิดหน้านั้นก็อ่านได้ · ในหน้าเว็บให้ใช้ client key แล้วเพิ่มโดเมนของหน้าด้วย PUT /v1/origins (ดู ข้อผิดพลาดและเพดาน)
สร้างเพิ่มไม่ได้ และไม่จำเป็น — ชุดข้อมูลหนึ่งชุดมีคีย์สองดอกตลอดอายุของมัน ดอกละชนิด สิ่งเดียวที่ทำกับคีย์ได้คือ เพิกถอน ตอนที่มันหลุด แล้วระบบออกใบใหม่มาแทนที่ให้ในจังหวะเดียวกัน
client key ใช้ได้จากโดเมนที่ลงทะเบียนเท่านั้น
client key ถูกพิมพ์อยู่ในหน้าเว็บ ใครเปิดหน้าก็เห็น สิ่งที่บอกว่าใครใช้ได้จึงเป็น ที่อยู่ของหน้าเว็บ — คำขอที่มีหัวข้อ Origin ต้องมาจากที่อยู่ในรายการที่คุณเพิ่มไว้ ไม่งั้นได้ 403 ที่บอกว่าที่อยู่ไหนถูกปฏิเสธ
https://shop.example.com
https://*.example.com # ทุกซับโดเมน
http://localhost:* # ตอนพัฒนา ทุกพอร์ต ต้องใส่เองเทียบกันแบบ origin คือ scheme โฮสต์ และพอร์ต — ตัวพิมพ์เล็กใหญ่ไม่สำคัญ และเครื่องหมาย / ท้ายที่อยู่ไม่นับ เพราะเบราว์เซอร์ส่ง origin ในรูปมาตรฐานเสมอ · Origin: null (iframe แบบ sandbox, ไฟล์ที่เปิดจากเครื่อง) ใช้ไม่ได้ เพราะไม่ได้บอกว่ามาจากที่ไหน
:* แทนพอร์ตไหนก็ได้ รวมถึงไม่มีพอร์ต และใช้ได้หลัง localhost 127.0.0.1 และ [::1] เท่านั้น — dev server ที่เลือกพอร์ตเองจึงไม่ต้องแก้รายการทุกครั้งที่พอร์ตเปลี่ยน แต่หลังโดเมนจริง มันคือทุกบริการบนเครื่องนั้น จึงไม่รับ
ไม่มีที่อยู่ไหนถูกอนุญาตให้อัตโนมัติ รวมถึง localhost — ถ้าอนุญาตอัตโนมัติ มันจะถูกอนุญาตบนทุกชุดข้อมูลในระบบ ซึ่งเท่ากับยื่นค่าที่ใช้ได้ทุกที่ให้คนที่ขโมยคีย์ไป
คำขอที่ไม่มี Origin เลยใช้ client key ได้ — คือ backend ที่อยากค้นด้วยสิทธิ์ต่ำสุด แทนที่จะถือ service key ที่ลบข้อมูลได้ไว้ในเครื่องที่แค่ต้องค้นหา
รายการนี้กันอะไรได้ และกันอะไรไม่ได้
กันไม่ได้: สคริปต์ที่ตั้งใจ — หัวข้อ
Origin เขียนโดยผู้ส่ง และ curl เขียนอะไรก็ได้ สิ่งที่จำกัดความเสียหายของ client key ที่หลุดคือเพดานคำขอต่อวินาที โควตาที่ลดความสามารถแทนการดับ และการที่ client key แก้ข้อมูลไม่ได้เลยเบราว์เซอร์ อัตรา และ CORS
ทุกเส้นของ /v1 ตอบ CORS ด้วย Access-Control-Allow-Origin: * และไม่รับ cookie — คีย์คือสิ่งเดียวที่ยืนยันตัวตน ส่วนการตัดสินว่าหน้าไหนใช้ client key ได้ ทำฝั่งเซิร์ฟเวอร์ด้วย 403 · preflight ของเส้นที่มีอยู่จริงตอบ 204 และถูกจำไว้สองชั่วโมง ส่วนเส้นที่ไม่มีได้ 404
อัตราต่อวินาทีเป็นของคีย์ และ client key แบ่งเป็นถังต่อผู้เข้าชม (ต่อ IP) ถังละหนึ่งในสี่ของอัตราของคีย์ โดยรวมกันไม่เกินอัตราของคีย์ — คนเดียวที่กดค้างหรือสคริปต์หนึ่งตัวจึงใช้โควตาของทั้งร้านหมดไม่ได้ · 429 มี Retry-After ที่ JavaScript ในเบราว์เซอร์อ่านได้
หน้าที่เรนเดอร์บนเซิร์ฟเวอร์ได้ส่วนแบ่งแบบเดียวกันด้วยหัวข้อ X-End-User — id ทึบของผู้เข้าชมหรือ IP ของเขา ส่งพร้อม service key เท่านั้น · client key ที่ส่งหัวข้อนี้ได้ 403 เพราะใครอ่านคีย์จากหน้าเว็บได้ก็ตั้งชื่อใหม่ได้ทุกคำขอ และเบราว์เซอร์ส่งหัวข้อนี้ข้ามโดเมนไม่ได้อยู่แล้ว
ดูคีย์ซ้ำได้
client key แสดงเต็มอยู่ในหน้าคีย์ตลอดเวลา เพราะมันถูกออกแบบมาให้เปิดเผยอยู่แล้ว — ปิดบังไว้มีแต่จะทำให้คุณต้องไปเก็บสำเนาของค่าสาธารณะไว้ที่อื่นที่ปลอดภัยน้อยกว่า
service key ถูกปิดบังไว้ กดปุ่มแสดงคีย์เพื่อดูซ้ำได้ และทุกครั้งที่กดจะถูกบันทึกว่าใครกดเมื่อไหร่ — เราเก็บมันไว้แบบเข้ารหัสด้วยกุญแจที่ไม่ได้อยู่ในฐานข้อมูล แยกจากค่าแฮชที่ใช้ยืนยันคำขอ
เพิกถอนแล้วได้ใบใหม่ทันที ไม่มีช่วงผ่อนผัน
เพิกถอนทีละดอก ดอกที่เหลือไม่สะดุดตาม — และคีย์ใบใหม่ได้ชนิดเดิมเสมอ คีย์ที่หลุดแล้วถูกเปลี่ยน ไม่ควรกลายเป็นคีย์ที่ทำได้มากกว่าเดิม
ดูคีย์ เพิกถอน และจัดการรายการโดเมนได้ที่หน้า คีย์ API ของชุดข้อมูลนั้นในคอนโซล · อ่านเรื่องเพดานและข้อผิดพลาด