Tài khoản

Nhiều clientKey: hạn mức, IP cho phép và thời gian hết hạn

Trang này được dịch máy từ bản tiếng Trung và có thể có sai sót. Nội dung theo bản tiếng Trung.

Một tài khoản YesCaptcha có tối đa 20 clientKey (gồm cả key ban đầu), quản lý tại trang “Khóa và bảo mật” trong bảng điều khiển yescaptcha.com. Mỗi clientKey đều có thể tạo tác vụ và truy vấn số dư, và đều trừ vào cùng một số dư tài khoản. Mỗi key có thể đặt riêng hạn mức chi tiêu, IP cho phép và thời gian hết hạn, có hiệu lực trong vài giây.

Phù hợp với các trường hợp: tách key cho môi trường thử nghiệm và môi trường production, hoặc cho từng dự án; cấp key cho khách hàng hạ nguồn hoặc đối tác, mỗi bên một hạn mức; khi một clientKey bị lộ, chỉ cần xóa đúng key đó, các chương trình khác không bị ảnh hưởng.

Key chính và Key phụ

	Key chính	Key phụ
Là key nào	`clientKey` ban đầu, mỗi tài khoản có một	Key tạo thêm ngoài Key chính, tối đa 19
Hạn mức, IP cho phép, thời gian hết hạn	Có thể đặt	Có thể đặt
Đặt lại	Có: key cũ mất hiệu lực ngay, số dư chuyển sang key mới	Không thể đặt lại, hãy xóa rồi tạo key khác
Xóa	Không	Có: mất hiệu lực trong vài giây, không thể khôi phục

Định dạng đều giống nhau: 40 ký tự đầu là khóa bí mật, phần sau là ID người dùng của bạn.
Đặt lại Key chính không ảnh hưởng đến Key phụ.
Dùng clientKey nào để tạo tác vụ hay truy vấn số dư thì giao diện API và kết quả trả về đều như nhau, chỉ thêm các bước kiểm tra hạn mức, IP cho phép và thời gian hết hạn.

Tạo clientKey

Đăng nhập yescaptcha.com, mở trang “Khóa và bảo mật” (yescaptcha.com/security).
Trong “Tất cả Key”, bấm “Tạo Key phụ”. Tên (tối đa 40 ký tự), hạn mức, IP cho phép và thời gian hết hạn đều có thể để trống, sau này vẫn sửa được.
Xác minh danh tính thêm một lần theo hướng dẫn. Tạo, sửa và xóa đều cần xác minh.
Sau khi tạo, sao chép clientKey đầy đủ và cấu hình vào chương trình. Sau này cũng có thể bấm biểu tượng con mắt trong danh sách để xem lại.

Hạn mức chi tiêu

Hạn mức giới hạn một clientKey được tiêu tối đa bao nhiêu điểm trong một chu kỳ (1,000 điểm = ¥1), có thể đặt từ 1 đến 10,000,000,000 điểm. Có bốn chu kỳ, đặt lại theo giờ Bắc Kinh (UTC+8):

Chu kỳ	Khi nào đặt lại
Mỗi ngày	0 giờ mỗi ngày
Mỗi tuần	0 giờ thứ Hai hàng tuần
Mỗi tháng	0 giờ ngày 1 hàng tháng
Tổng một lần	Không đặt lại. Dùng hết thì `clientKey` này không thể tạo tác vụ nữa, muốn tiếp tục dùng hãy tăng hạn mức

Tính theo số điểm thực tế đã trừ: điểm được hoàn lại do nhận dạng thất bại hoặc hết thời gian chờ cũng được hoàn lại vào hạn mức.
Khi hạn mức còn lại của chu kỳ hiện tại không đủ để trừ điểm cho tác vụ này, createTask trả về ERROR_KEY_QUOTA_EXCEEDED, không trừ điểm và không tính vào tự động tạm dừng.
Trong danh sách ở bảng điều khiển có thể xem mỗi clientKey đã dùng bao nhiêu trong chu kỳ hiện tại và khi nào đặt lại tiếp theo.
Hạn mức không phải số dư riêng: mọi clientKey đều trừ vào cùng một số dư tài khoản, khi số dư tài khoản không đủ vẫn trả về ERROR_ZERO_BALANCE như bình thường.

Khi gọi getBalance bằng clientKey có đặt hạn mức, balance là giá trị nhỏ hơn giữa số dư tài khoản và hạn mức còn lại của chu kỳ hiện tại, ngoài ra có thêm trường keyQuotaRemaining (hạn mức còn lại, tính bằng điểm). clientKey không đặt hạn mức không có trường này, kết quả trả về giống như trước.

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

IP cho phép

clientKey có đặt IP cho phép chỉ dùng được với các yêu cầu gửi từ IP trong danh sách. Để trống nghĩa là không giới hạn.

Điền IP công khai của máy gọi API YesCaptcha (IP đầu ra), không phải proxy trong tham số tác vụ. Nếu gọi từ nhiều máy, phải thêm IP công khai của từng máy.
Mỗi dòng một địa chỉ IPv4 hoặc IPv6, hoặc dải CIDR, tối đa 50 mục. Một địa chỉ đơn nghĩa là chỉ cho phép đúng IP đó.
Dải mạng phải viết ở dạng địa chỉ mạng: 203.0.113.0/24 được, 203.0.113.5/24 không được (các bit máy chủ không bằng 0).

203.0.113.10
198.51.100.0/24
2001:db8::/32

Khi IP của yêu cầu không có trong danh sách, createTask và getBalance trả về ERROR_KEY_IP_NOT_ALLOWED, không trừ điểm và không tính vào tự động tạm dừng.
Nếu IP đầu ra thay đổi (mạng gia đình, cloud function, đầu ra luân phiên) thì đừng đặt, hoặc đặt thành cả dải mạng.

Thời gian hết hạn

Mọi clientKey (kể cả Key chính) đều có thể đặt thời gian hết hạn, trong vòng mười năm; sau đó có thể sửa hoặc bỏ bất cứ lúc nào.
Sau khi hết hạn, gọi createTask và getBalance bằng key đó sẽ trả về ERROR_KEY_EXPIRED, không trừ điểm. Các tác vụ đã tạo vẫn lấy được kết quả bằng getTaskResult như bình thường.
Với clientKey lâu không sử dụng, hệ thống sẽ đặt thời gian hết hạn để bảo vệ an toàn tài khoản và gửi email nhắc trước khi hết hạn. Thời gian hết hạn này không thể sửa: hãy tạo lại Key chính (số dư tự động chuyển sang key mới) hoặc tạo một clientKey mới, rồi cập nhật vào chương trình.

Số dư, giới hạn đồng thời và tự động tạm dừng

Số dư: mọi clientKey đều trừ vào cùng một số dư tài khoản. Nạp tiền, điểm thưởng khi nạp của VIP, thưởng giới thiệu và chia sẻ doanh thu cho nhà phát triển đều tính theo tài khoản, không phụ thuộc vào việc dùng clientKey nào.
Giới hạn đồng thời: tính theo tài khoản, tất cả clientKey cộng lại chịu chung một mức trần, xem Giới hạn đồng thời và tự động tạm dừng.
Tự động tạm dừng: tính riêng cho từng clientKey, một clientKey gặp quá nhiều lỗi bị tạm dừng thì không ảnh hưởng đến các key khác.

Mã lỗi liên quan

Mã lỗi	Khi nào trả về
`ERROR_KEY_QUOTA_EXCEEDED`	Hạn mức còn lại của chu kỳ hiện tại không đủ cho tác vụ này (`createTask`)
`ERROR_KEY_IP_NOT_ALLOWED`	IP của yêu cầu không có trong danh sách IP cho phép của `clientKey` này (`createTask`, `getBalance`)
`ERROR_KEY_EXPIRED`	`clientKey` đã hết hạn (`createTask`, `getBalance`)

Cả ba mã này đều không trừ điểm. Cách xử lý xem Mã lỗi.