Chuyển tới nội dung chính

2.1 Tổng quan

2.1.1 Địa chỉ truy cập​

Môi trường kiểm thử
Môi trường thực tếhttps://api.racent.com/

2.1.2 Xác thực chữ ký giao diện​

Giao diện sử dụng cơ chế xác thực danh tính dựa trên chữ ký API, có thể đảm bảo tính toàn vẹn và bảo mật của yêu cầu. Mỗi lần gọi giao diện, đều phải mang theo tham số chữ ký, phía máy chủ sẽ xác minh tính đúng đắn của chữ ký.

Tham số công khai​

Các tham số sau bắt buộc phải được bao gồm trong Query String của mỗi yêu cầu giao diện:

Tên tham sốKiểu tham sốMô tảGiá trị mẫu
access_keyStringID tài khoản, dùng để định danh người gọi1000000059
signature_nonceStringSố ngẫu nhiên duy nhất của chữ ký, dùng để chống tấn công phát lại,
mỗi yêu cầu phải dùng giá trị ngẫu nhiên khác nhau		2206561-6450-430e-8b0a-26980754c0de
timestampStringDấu thời gian khi yêu cầu được khởi tạo (đơn vị: giây)1673418729
signature_versionStringPhiên bản thuật toán chữ ký, cố định là 1.01.0
signature_methodStringThuật toán chữ ký, cố định là md5md5
signatureStringGiá trị chữ ký của yêu cầu này, được tính từ các tham số khác và khóa bí mật85ef54421c69edeb098c7b557c6c5cd5
Giải thích:
  • access_key và AccessSecret (khóa bí mật) có thể lấy được sau khi đăng nhập tại mục Quản lý giao diện-Chứng chỉ truy cập API.
  • signature_nonce Nên sử dụng UUID hoặc chuỗi đủ ngẫu nhiên để đảm bảo mỗi yêu cầu là duy nhất.
  • timestamp Các yêu cầu có chênh lệch với thời gian máy chủ vượt quá một khoảng nhất định (ví dụ 5 phút) sẽ bị từ chối. :::

Cơ chế chữ ký​

Bước 1: Tạo chuỗi yêu cầu chuẩn hóa​

1. Sắp xếp tham số​

Sắp xếp tất cả tham số chung (ngoại trừ signature) và các tham số tùy chỉnh của giao diện theo thứ tự từ điển tăng dần của tên tham số.

2. Mã hóa tham số​

Mã hóa tên và giá trị của từng tham số bằng UTF-8, đồng thời mã hóa URL theo quy tắc RFC3986:

  • Ký tự không mã hóa: A-Z a-z 0-9 - _ . ~
  • Các ký tự khác (như dấu cách, /, ?, =, v.v.) cần được mã hóa thành định dạng %XX, ví dụ dấu cách mã hóa thành %20
3. Ghép nối tham số​
  • Dùng = để nối tên tham số và giá trị tham số sau khi mã hóa
  • Dùng & để nối tất cả các cặp tham số, giữ nguyên thứ tự từ điển

Chuỗi cuối cùng thu được gọi là stringToSign.

Bước 2: Tạo chuỗi chữ ký và tính toán chữ ký​

Tùy theo loại yêu cầu khác nhau, cách tính chữ ký như sau:

GET 请求
signature = md5(AccessSecret + md5( HTTPMethod + stringToSign ))
POST / PUT 请求（含 Body 参数）
signature = md5(AccessSecret + md5( HTTPMethod + stringToSign ) + md5( jsonStringToBody ))
Lưu ý:
  • HTTPMethod phải viết hoa, ví dụ GET, POST
  • jsonStringToBody là chuỗi JSON thô của Body yêu cầu (cần loại bỏ khoảng trắng và dấu xuống dòng, đồng thời các trường phải được sắp xếp)
  • Dấu + trong công thức biểu thị phép nối chuỗi, không tham gia tính toán

Quy tắc mã hóa tham số (RFC3986)​

Loại ký tựCách xử lýVí dụ
A-Z, a-z, 0-9, -, _, ., ~Không mã hóaabc123 → abc123
Dấu cáchMã hóa thành %20a b → a%20b
Ký tự ASCII khácMã hóa thành %XX (hệ thập lục phân)" → %22

Ví dụ yêu cầu GET​

Giả sử:

  • access_key = "1000000059"
  • AccessSecret = "19938c89c13ddf5da7636333a5aa4c0e"
  • signature_nonce = "iobzx72w63"
  • timestamp = "1755597512"

Bước 1: Tạo stringToSign​

access_key=1000000059&signature_method=md5&signature_nonce=iobzx72w63&signature_version=1.0&timestamp=1755597512

Bước 2: Tính chữ ký​

temp = md5("GET" + stringToSign)  // 结果为"9bc92e0f3e239dc628ebc416294422ba"
signature = md5(AccessSecret + temp)  // 结果为"a33bdb81ea79eb4ebbac9da043309c00"

URL yêu cầu cuối cùng:​

https://api.racent.com/api/v1/domain/tld?access_key=1000000059&signature_nonce=iobzx72w63&timestamp=1755597512&signature_version=1.0&signature_method=md5&signature=a33bdb81ea79eb4ebbac9da043309c00

Ví dụ yêu cầu POST (bao gồm Body)​

Giả sử Body là:

{"domain":"example.com"}

Giá trị MD5 của nó là: 640c69595341436be9b0d1516d3d37ac

Step1: Tạo stringToSign​

access_key=1000000059&signature_method=md5&signature_nonce=abjipo5ar5a&signature_version=1.0&timestamp=1755598851

Bước 2: Tính chữ ký​

temp = md5("POST" + stringToSign)  // 结果为 "5aba63e4af1b7a4080eaf47d0fc56efe"
signature = md5(AccessSecret + temp + "640c69595341436be9b0d1516d3d37ac")  // 结果为 "29487fd8ae5b828415d05b691caf015c"

URL yêu cầu cuối cùng:​

https://api.racent.com/v1/domain/query-domain?access_key=1000000059&signature_nonce=abjipo5ar5a&timestamp=1755598851&signature_version=1.0&signature_method=md5&signature=29487fd8ae5b828415d05b691caf015c

2.1.3 Giới hạn tốc độ API​

Quy tắc giới hạn tốc độ mặc định, đối với cùng một người dùng truy cập cùng một API, giới hạn số lần như sau:

  • 60 lần mỗi phút
  • 500 lần mỗi giờ
  • 1000 lần mỗi ngày

2.1.4 Tham số trả về của API​

Giải thích tham số​

Tên tham sốLoại tham sốMô tảGiá trị mẫu
dataObjectDữ liệu nghiệp vụ, nếu API báo lỗi, giá trị trả về là null
codeIntMã lỗi, thành công trả về 0, báo lỗi trả về mã lỗi tương ứng0，1000，1001
messageStringThông tin mô tả lỗi, API thành công trả về "Success"over-rate-limit
errorsObjectMột số lỗi sẽ cung cấp mô tả lỗi cụ thể hơn qua trường này
request_idStringID yêu cầu, chủ yếu dùng để hỗ trợ điều tra sự cố039ecdca-44d5-430f-8521-020f4953bcc5
Cập nhật lần cuối vào