หลาย ClientKey: ขีดจำกัด, IP allowlist และเวลาหมดอายุ

บัญชี YesCaptcha หนึ่งบัญชีมี clientKey ได้สูงสุด 20 รายการ (รวมรายการเดิม) จัดการได้ที่หน้า「คีย์และความปลอดภัย」ในแดชบอร์ด yescaptcha.com ทุก clientKey สร้างงานและตรวจสอบยอดคงเหลือได้ และหักจากยอดคงเหลือของบัญชีเดียวกัน แต่ละรายการตั้งขีดจำกัดการใช้จ่าย IP allowlist และเวลาหมดอายุแยกกันได้ และมีผลภายในไม่กี่วินาที

เหมาะกับกรณีเหล่านี้: แยกใช้ระหว่างสภาพแวดล้อมทดสอบกับ production หรือแยกตามโปรเจกต์; แจกให้ลูกค้าปลายทางหรือพันธมิตรโดยกำหนดขีดจำกัดของแต่ละราย; หาก clientKey ใดรั่วไหล ก็ลบเฉพาะรายการนั้น โปรแกรมอื่นไม่ได้รับผลกระทบ

Key หลักและ Key ย่อย

	Key หลัก	Key ย่อย
คืออะไร	clientKey เดิม มีบัญชีละหนึ่งรายการ	สร้างเพิ่มนอกเหนือจาก Key หลัก ได้สูงสุด 19 รายการ
ขีดจำกัด, IP allowlist, เวลาหมดอายุ	ตั้งได้	ตั้งได้
รีเซ็ต	ได้: รายการเก่าใช้ไม่ได้ทันที และยอดคงเหลือย้ายไปที่รายการใหม่	รีเซ็ตไม่ได้ ให้ลบแล้วสร้างใหม่
ลบ	ไม่ได้	ได้: ใช้ไม่ได้ภายในไม่กี่วินาที และกู้คืนไม่ได้

• รูปแบบเหมือนกันทั้งหมด: 40 ตัวอักษรแรกเป็นคีย์ลับ ตามด้วย ID ผู้ใช้ของคุณ
• การรีเซ็ต Key หลักไม่กระทบ Key ย่อย
• ไม่ว่าจะใช้ clientKey ใดสร้างงานหรือตรวจสอบยอดคงเหลือ ก็ใช้อินเทอร์เฟซและได้ผลลัพธ์เหมือนกัน ต่างกันเพียงมีการตรวจสอบขีดจำกัด IP allowlist และเวลาหมดอายุเพิ่ม

สร้าง ClientKey ใหม่

1. เข้าสู่ระบบที่ yescaptcha.com แล้วเปิดหน้า「คีย์และความปลอดภัย」(yescaptcha.com/security)
2. ใน “Key ทั้งหมด” คลิก “สร้าง Key ย่อย” ชื่อ (ไม่เกิน 40 ตัวอักษร) ขีดจำกัด IP allowlist และเวลาหมดอายุไม่ต้องกรอกก็ได้ และแก้ไขภายหลังได้
3. ยืนยันตัวตนอีกครั้งตามที่ระบบแจ้ง การสร้าง แก้ไข และลบต้องยืนยันตัวตนทุกครั้ง
4. หลังสร้างแล้วให้คัดลอก clientKey แบบเต็มไปตั้งค่าในโปรแกรม ภายหลังสามารถคลิกไอคอนรูปตาในรายการเพื่อดูอีกครั้งได้

หมายเหตุ

การสร้าง แก้ไข และลบมีผลภายในไม่กี่วินาที หากเรียกใช้ทันทีหลังสร้าง อาจได้รับ ERROR_KEY_DOES_NOT_EXIST ให้รอสักครู่แล้วลองใหม่ ภายในไม่กี่วินาทีหลังลบหรือเข้มงวดการตั้งค่าขึ้น คำขอที่กำลังส่งอยู่อาจยังถูกประมวลผลตามการตั้งค่าเดิม

ขีดจำกัดการใช้จ่าย

ขีดจำกัดกำหนดว่า clientKey หนึ่งใช้จ่ายได้สูงสุดกี่พอยต์ในหนึ่งรอบ (1,000 พอยต์ = ¥1) ตั้งได้ตั้งแต่ 1 ถึง 10,000,000,000 พอยต์ มีสี่รอบ รีเซ็ตตามเวลาปักกิ่ง (UTC+8):

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

• คำนวณตามพอยต์ที่หักจริง: พอยต์ที่คืนจากการจดจำล้มเหลวหรือหมดเวลา จะคืนเข้าขีดจำกัดด้วย
• เมื่อขีดจำกัดที่เหลือในรอบนี้ไม่พอสำหรับการหักพอยต์ของงานนี้ createTask จะคืนค่า ERROR_KEY_QUOTA_EXCEEDED ไม่หักพอยต์ และไม่นับรวมในการหยุดชั่วคราวอัตโนมัติ
• รายการในแดชบอร์ดแสดงว่าแต่ละ clientKey ใช้ไปเท่าไรในรอบนี้ และจะรีเซ็ตครั้งถัดไปเมื่อใด
• ขีดจำกัดไม่ใช่ยอดคงเหลือแยกต่างหาก: ทุก clientKey หักจากยอดคงเหลือของบัญชีเดียวกัน เมื่อยอดคงเหลือของบัญชีไม่พอจะคืนค่า ERROR_ZERO_BALANCE ตามปกติ

เมื่อเรียก getBalance ด้วย clientKey ที่ตั้งขีดจำกัดไว้ balance จะเป็นค่าที่น้อยกว่าระหว่างยอดคงเหลือของบัญชีกับขีดจำกัดที่เหลือในรอบนี้ และมีฟิลด์ keyQuotaRemaining เพิ่มเข้ามา (ขีดจำกัดที่เหลือ หน่วยพอยต์) clientKey ที่ไม่ได้ตั้งขีดจำกัดจะไม่มีฟิลด์นี้ และผลลัพธ์เหมือนเดิม

{
  "errorId": 0,
  "balance": 20000,
  "softBalance": 0,
  "inviteBalance": 0,
  "inviteBy": 0,
  "keyQuotaRemaining": 20000
}

IP allowlist

clientKey ที่ตั้ง IP allowlist ไว้ จะใช้ได้เฉพาะคำขอที่ส่งจาก IP ในรายการเท่านั้น หากเว้นว่างไว้คือไม่จำกัด

• ให้กรอก IP สาธารณะของเครื่องที่เรียกใช้ API ของ YesCaptcha (IP ขาออก) ไม่ใช่พร็อกซีในพารามิเตอร์ของงาน หากเรียกจากหลายเครื่อง ต้องเพิ่ม IP สาธารณะของทุกเครื่อง
• หนึ่งบรรทัดต่อหนึ่งที่อยู่ IPv4 หรือ IPv6 หรือช่วง CIDR ได้สูงสุด 50 รายการ ที่อยู่เดี่ยวหมายถึงอนุญาตเฉพาะ IP นั้น
• ช่วง IP ต้องเขียนเป็นที่อยู่เครือข่าย: 203.0.113.0/24 ใช้ได้ แต่ 203.0.113.5/24 ใช้ไม่ได้ (บิตโฮสต์ไม่เป็น 0)

203.0.113.10
198.51.100.0/24
2001:db8::/32

• เมื่อ IP ของคำขอไม่อยู่ในรายการ createTask และ getBalance จะคืนค่า ERROR_KEY_IP_NOT_ALLOWED ไม่หักพอยต์ และไม่นับรวมในการหยุดชั่วคราวอัตโนมัติ
• หาก IP ขาออกเปลี่ยนได้ (อินเทอร์เน็ตบ้าน, cloud function, egress ที่หมุนเวียน) อย่าตั้งค่า หรือตั้งเป็นทั้งช่วง

เวลาหมดอายุ

• clientKey ใดก็ได้ (รวม Key หลัก) ตั้งเวลาหมดอายุได้ ต้องอยู่ภายในสิบปี และแก้ไขหรือลบออกได้ทุกเมื่อ
• หลังหมดอายุ การเรียก createTask และ getBalance ด้วยรายการนั้นจะคืนค่า ERROR_KEY_EXPIRED และไม่หักพอยต์ งานที่สร้างไว้แล้วยังใช้ getTaskResult ดึงผลได้ตามปกติ
• clientKey ที่ไม่ได้ใช้งานเป็นเวลานาน ระบบจะตั้งเวลาหมดอายุให้เพื่อความปลอดภัยของบัญชี และส่งอีเมลแจ้งเตือนก่อนหมดอายุ เวลาหมดอายุแบบนี้แก้ไขไม่ได้: ให้สร้าง Key หลักใหม่ (ยอดคงเหลือย้ายไปที่รายการใหม่โดยอัตโนมัติ) หรือสร้าง clientKey ใหม่ แล้วอัปเดตในโปรแกรม

ยอดคงเหลือ ขีดจำกัดงานพร้อมกัน และการหยุดชั่วคราวอัตโนมัติ

• ยอดคงเหลือ: ทุก clientKey หักจากยอดคงเหลือของบัญชีเดียวกัน การเติมเงิน โบนัส VIP รางวัลแนะนำเพื่อน และส่วนแบ่งรายได้นักพัฒนา ล้วนคิดตามบัญชี ไม่เกี่ยวกับว่าใช้ clientKey ใด
• ขีดจำกัดงานพร้อมกัน: คิดตามบัญชี ทุก clientKey ใช้เพดานเดียวกันรวมกัน ดูขีดจำกัดงานพร้อมกันและการหยุดชั่วคราวอัตโนมัติ
• การหยุดชั่วคราวอัตโนมัติ: คิดแยกตาม clientKey หาก clientKey หนึ่งมีข้อผิดพลาดมากเกินไปจนถูกหยุดชั่วคราว รายการอื่นไม่ได้รับผลกระทบ

รหัสข้อผิดพลาดที่เกี่ยวข้อง

รหัสข้อผิดพลาด	คืนค่าเมื่อใด
ERROR_KEY_QUOTA_EXCEEDED	ขีดจำกัดที่เหลือในรอบนี้ไม่พอสำหรับงานนี้ (createTask)
ERROR_KEY_IP_NOT_ALLOWED	IP ของคำขอไม่อยู่ใน IP allowlist ของ clientKey นี้ (createTask, getBalance)
ERROR_KEY_EXPIRED	clientKey หมดอายุแล้ว (createTask, getBalance)

ทั้งสามรายการไม่หักพอยต์ วิธีจัดการดูรหัสข้อผิดพลาด