StarDots.io Logo

StarDots

Trang chủ tài liệu

Open API

Chương này sẽ giới thiệu cách tích hợp Open API. Kiến thức dưới đây dành cho các nhà phát triển, và chúng tôi giả định bạn đã có nền tảng lập trình cơ bản.

Bạn là tác nhân AI? Đọc tài liệu Markdown
Nội dung trang

Xác thực

StarDots thực hiện xác thực bằng cách đọc trường header trong yêu cầu HTTP do khách hàng gửi và xác minh các trường liên quan. Do đó, tất cả các yêu cầu Open API đều phải mang theo thông tin xác thực này, và bạn cần lưu ý rằng các trường này phân biệt chữ hoa và chữ thường và tất cả các trường đều phải viết thường.

  • x-stardots-timestamp
    Mô tả
    Dấu thời gian hiện tại tính bằng giây. Sự khác biệt với máy chủ StarDots không được vượt quá 60 giây. Lưu ý: Múi giờ của StarDots là Asia/Singapore, tức là UTC+8.
  • x-stardots-nonce
    Mô tả
    Một chuỗi ngẫu nhiên từ 4 đến 20 ký tự, chỉ có thể chứa chữ cái in hoa, chữ cái in thường và chữ số. Lưu ý rằng giá trị này phải là duy nhất trong vòng 60 giây.
  • x-stardots-key
    Mô tả
    Thông tin khóa được cấp bởi StarDots.
  • x-stardots-sign
    Mô tả
    Trường chữ ký là một chuỗi được tạo ra bằng cách kết hợp các trường trên theo một thuật toán chữ ký nhất định. Thuật toán chữ ký cụ thể sẽ được giới thiệu sau.

Thuật toán chữ ký

Chúng tôi giả định các giá trị trường dưới đây

key
2dcded8e-f231-4d0a-8498-d10ef0639eb3
secret
Ey1JNRCiJOzaIOIilcyJvteTn5YXykFXUwmiHLymK8LHkITfGPo5mTUdLlg0jPHST9fMwMZKxIKUBvSsT5uxrq0lXuerll3eRW2tbMOsvySRY539L8cR6iRFV2DQqdlzbseyq7k9N0U5pZgj6f43e3MngbIttgSDl1G44IBOwqsI2HVXE5H6mf1bHlvWw6Ziuk8Xcw18AioG47SFBLIatrq6E9yEBJgFgcYysCH8JvY659hhqI3Ii1CA5zVtyNp
x-stardots-timestamp
1728958751
x-stardots-nonce
fQvDmMLnKE
x-stardots-key
2dcded8e-f231-4d0a-8498-d10ef0639eb3
Khóa và Secret được cấp bởi StarDots, bạn có thể tìm chúng trong trang cài đặt console.

Sau đó, chúng tôi sẽ ghép các giá trị trường trên lại với nhau

needSignStr = x-stardots-timestamp + "|" + secret + "|" + x-stardots-nonce

Tiếp theo, chúng tôi tính toán MD5 của chuỗi đã ghép trên

signStrAfterMD5 = md5("1728958751|Ey1JNRCiJOzaIOIilcyJvteTn5YXykFXUwmiHLymK8LHkITfGPo5mTUdLlg0jPHST9fMwMZKxIKUBvSsT5uxrq0lXuerll3eRW2tbMOsvySRY539L8cR6iRFV2DQqdlzbseyq7k9N0U5pZgj6f43e3MngbIttgSDl1G44IBOwqsI2HVXE5H6mf1bHlvWw6Ziuk8Xcw18AioG47SFBLIatrq6E9yEBJgFgcYysCH8JvY659hhqI3Ii1CA5zVtyNp|fQvDmMLnKE")
signStrAfterMD5 = "51dabfe4b47e73d4a3b85fe29c4f1e82"

Cuối cùng, chúng tôi chuyển chuỗi tóm tắt sang chữ hoa

sign = signStrAfterMD5.toUpperCase()
sign = "51DABFE4B47E73D4A3B85FE29C4F1E82"

Do đó, giá trị cuối cùng của trường x-stardots-sign là 51DABFE4B47E73D4A3B85FE29C4F1E82

Cấu trúc dữ liệu phản hồi HTTP chung

Tất cả các phản hồi giao diện đều duy trì một cấu trúc dữ liệu thống nhất

  • code
    Loại dữ liệu
    number
    Bắt buộc
    Yes
    Mô tả
    Mã phản hồi dịch vụ. 200 chỉ ra thành công.
  • message
    Loại dữ liệu
    string
    Bắt buộc
    Yes
    Mô tả
    Thông báo kết quả của thao tác.
  • requestId
    Loại dữ liệu
    string
    Bắt buộc
    Yes
    Mô tả
    Một số duy nhất cho yêu cầu, có thể dùng để khắc phục sự cố.
  • success
    Loại dữ liệu
    boolean
    Bắt buộc
    Yes
    Mô tả
    Chỉ ra liệu thao tác kinh doanh có thành công không.
  • ts
    Loại dữ liệu
    number
    Bắt buộc
    Yes
    Mô tả
    Dấu thời gian tính bằng mili giây từ máy chủ.
  • data
    Loại dữ liệu
    any
    Bắt buộc
    Yes
    Mô tả
    Trường dữ liệu kinh doanh. Trường này có thể có bất kỳ loại dữ liệu nào. Để biết thêm về các loại dữ liệu cụ thể, vui lòng tham khảo giao diện tương ứng.

Giao diện chức năng

Lưu ý rằng tất cả các giao diện sẽ có giới hạn tốc độ yêu cầu, và tất cả các giao diện chia sẻ một bộ quy tắc giới hạn tốc độ. Cho đến nay, giới hạn tốc độ của StarDots là 300 lần mỗi phút.

Điểm cuối yêu cầu

https://api.stardots.io

Danh sách không gian

Lấy dữ liệu danh sách không gian.

Phương thức yêu cầu
GET
Đường dẫn yêu cầu
/openapi/space/list
Loại nội dung yêu cầu
application/json
Loại nội dung phản hồi
application/json

Tham số yêu cầu

  • page
    Loại dữ liệu
    number
    Bắt buộc
    No
    Mô tả
    Số trang, giá trị mặc định là 1.
  • pageSize
    Loại dữ liệu
    number
    Bắt buộc
    No
    Mô tả
    Số mục mỗi trang từ 1 đến 100, giá trị mặc định là 20.

Demo yêu cầu

/openapi/space/list?page=1&pageSize=50

Trường phản hồi

  • name
    Loại dữ liệu
    string
    Bắt buộc
    Yes
    Mô tả
    Tên của không gian.
  • public
    Loại dữ liệu
    boolean
    Bắt buộc
    Yes
    Mô tả
    Liệu quyền truy cập của không gian có phải là sai không.
  • createdAt
    Loại dữ liệu
    number
    Bắt buộc
    Yes
    Mô tả
    Dấu thời gian hệ thống tính bằng giây khi không gian được tạo. Múi giờ là UTC+8.
  • fileCount
    Loại dữ liệu
    number
    Bắt buộc
    Yes
    Mô tả
    Số lượng tệp trong không gian này.

Demo phản hồi

{
    "code": 200,
    "data": [
        {
            "createdAt": 1723789637,
            "fileCount": 2,
            "name": "star",
            "public": true
        }
    ],
    "message": "SUCCESS",
    "requestId": "5686efa5-c747-4f63-8657-e6052f8181a9",
    "success": true,
    "ts": 1670899688591
    }

Tạo không gian

Tạo một không gian mới.

Phương thức yêu cầu
PUT
Đường dẫn yêu cầu
/openapi/space/create
Loại nội dung yêu cầu
application/json
Loại nội dung phản hồi
application/json

Tham số yêu cầu

  • space
    Loại dữ liệu
    string
    Bắt buộc
    Yes
    Mô tả
    Tên của không gian. Nó chỉ có thể là sự kết hợp của chữ cái hoặc số, và độ dài từ 4 đến 15 ký tự.
  • public
    Loại dữ liệu
    boolean
    Bắt buộc
    No
    Mô tả
    Xác định xem không gian có thể truy cập công khai hay không. Giá trị mặc định là false.

Demo yêu cầu

{
    "public": false,
    "space": "stardots"
    }

Trường phản hồi

Không có trường

Demo phản hồi

{
    "code": 200,
    "data": null,
    "message": "SUCCESS",
    "requestId": "5686efa5-c747-4f63-8657-e6052f8181a9",
    "success": true,
    "ts": 1670899688591
    }

Xóa không gian

Xóa một không gian hiện có. Lưu ý rằng bạn phải đảm bảo không có tệp nào trong không gian này, nếu không việc xóa sẽ thất bại.

Phương thức yêu cầu
DELETE
Đường dẫn yêu cầu
/openapi/space/delete
Loại nội dung yêu cầu
application/json
Loại nội dung phản hồi
application/json

Tham số yêu cầu

  • space
    Loại dữ liệu
    string
    Bắt buộc
    Yes
    Mô tả
    Tên của không gian. Nó chỉ có thể là sự kết hợp của chữ cái hoặc số, và độ dài từ 4 đến 15 ký tự.

Demo yêu cầu

{
    "space": "stardots"
    }

Trường phản hồi

Không có trường

Demo phản hồi

{
    "code": 200,
    "data": null,
    "message": "SUCCESS",
    "requestId": "5686efa5-c747-4f63-8657-e6052f8181a9",
    "success": true,
    "ts": 1670899688591
    }

Quyền truy cập không gian

Chuyển đổi quyền truy cập của một không gian.

Phương thức yêu cầu
POST
Đường dẫn yêu cầu
/openapi/space/accessibility/toggle
Loại nội dung yêu cầu
application/json
Loại nội dung phản hồi
application/json

Tham số yêu cầu

  • space
    Loại dữ liệu
    string
    Bắt buộc
    Yes
    Mô tả
    Tên của không gian. Nó chỉ có thể là sự kết hợp của chữ cái hoặc số, và độ dài từ 4 đến 15 ký tự.
  • public
    Loại dữ liệu
    boolean
    Bắt buộc
    No
    Mô tả
    Chỉ định liệu không gian có thể truy cập công khai hay không. Giá trị mặc định là false.

Demo yêu cầu

{
    "public": false,
    "space": "stardots"
    }

Trường phản hồi

Không có trường

Demo phản hồi

{
    "code": 200,
    "data": null,
    "message": "SUCCESS",
    "requestId": "5686efa5-c747-4f63-8657-e6052f8181a9",
    "success": true,
    "ts": 1670899688591
    }

Danh sách tệp trong không gian

Lấy danh sách các tệp trong không gian. Danh sách được sắp xếp theo thứ tự giảm dần theo thời gian tải lên tệp.

Phương thức yêu cầu
GET
Đường dẫn yêu cầu
/openapi/file/list
Loại nội dung yêu cầu
application/json
Loại nội dung phản hồi
application/json

Tham số yêu cầu

  • space
    Loại dữ liệu
    string
    Bắt buộc
    Yes
    Mô tả
    Tên của không gian. Nó chỉ có thể là sự kết hợp của chữ cái hoặc số, và độ dài từ 4 đến 15 ký tự.
  • page
    Loại dữ liệu
    number
    Bắt buộc
    No
    Mô tả
    Số trang, giá trị mặc định là 1.
  • pageSize
    Loại dữ liệu
    number
    Bắt buộc
    No
    Mô tả
    Số mục mỗi trang dao động từ 1 đến 100, và giá trị mặc định là 20.

Demo yêu cầu

{
    "space": "stardots",
    "page": 1,
    "pageSize": 20,
    }

Trường phản hồi

  • page
    Loại dữ liệu
    number
    Bắt buộc
    Yes
    Mô tả
    Số trang, giá trị mặc định là 1.
  • pageSize
    Loại dữ liệu
    number
    Bắt buộc
    Yes
    Mô tả
    Số mục mỗi trang dao động từ 1 đến 100, và giá trị mặc định là 20.
  • totalCount
    Loại dữ liệu
    number
    Bắt buộc
    Yes
    Mô tả
    Tổng số mục.
  • list
    Loại dữ liệu
    array<object>
    Bắt buộc
    Yes
    Mô tả
    Mảng danh sách tệp.
  • list.name
    Loại dữ liệu
    string
    Bắt buộc
    Yes
    Mô tả
    Tên của tệp.
  • list.byteSize
    Loại dữ liệu
    number
    Bắt buộc
    Yes
    Mô tả
    Kích thước của tệp tính theo byte.
  • list.size
    Loại dữ liệu
    string
    Bắt buộc
    Yes
    Mô tả
    Kích thước tệp, được định dạng để dễ đọc.
  • list.uploadedAt
    Loại dữ liệu
    number
    Bắt buộc
    Yes
    Mô tả
    Dấu thời gian tải lên tệp tính bằng giây. Múi giờ là UTC+8.
  • list.url
    Loại dữ liệu
    string
    Bắt buộc
    Yes
    Mô tả
    Địa chỉ truy cập của tệp. Lưu ý rằng nếu quyền truy cập của không gian là riêng tư, giá trị trường này sẽ mang theo vé truy cập, có hiệu lực trong 20 giây.

Demo phản hồi

{
    "code": 0,
    "data": {
        "list": [
            {
                "byteSize": 3600000,
                "name": "star",
                "size": "35KB",
                "uploadedAt": 1723789637,
                "url": "https://....."
            }
        ],
        "page": 1,
        "pageSize": 10,
        "totalCount": 1
    },
    "message": "SUCCESS",
    "requestId": "5686efa5-c747-4f63-8657-e6052f8181a9",
    "success": true,
    "ts": 1670899688591
    }

Vé truy cập tệp

Lấy vé truy cập cho tệp. Khi quyền truy cập của không gian là riêng tư, bạn cần mang theo vé truy cập để truy cập các tệp trong không gian đó, nếu không yêu cầu sẽ bị từ chối.

Phương thức yêu cầu
POST
Đường dẫn yêu cầu
/openapi/file/ticket
Loại nội dung yêu cầu
application/json
Loại nội dung phản hồi
application/json

Tham số yêu cầu

  • space
    Loại dữ liệu
    string
    Bắt buộc
    Yes
    Mô tả
    Tên của không gian. Nó chỉ có thể là sự kết hợp của chữ cái hoặc số, và độ dài từ 4 đến 15 ký tự.
  • filename
    Loại dữ liệu
    string
    Bắt buộc
    Yes
    Mô tả
    Tên của tệp.

Demo yêu cầu

{
    "filename": "1.jpg",
    "space": "stardots"
    }

Trường phản hồi

  • ticket
    Loại dữ liệu
    string
    Bắt buộc
    Yes
    Mô tả
    Vé truy cập.

Demo phản hồi

{
    "code": 200,
    "data": {
        "ticket": "a312.."
    },
    "message": "SUCCESS",
    "requestId": "5686efa5-c747-4f63-8657-e6052f8181a9",
    "success": true,
    "ts": 1670899688591
    }

Tải lên tệp

Tải tệp lên không gian. Lưu ý rằng yêu cầu này yêu cầu bạn khởi tạo yêu cầu dưới dạng một biểu mẫu.

Phương thức yêu cầu
PUT
Đường dẫn yêu cầu
/openapi/file/upload
Loại nội dung yêu cầu
multipart/form-data
Loại nội dung phản hồi
application/json

Tham số yêu cầu

  • space
    Loại dữ liệu
    string
    Bắt buộc
    Yes
    Mô tả
    Tên của không gian. Nó chỉ có thể là sự kết hợp của chữ cái hoặc số, và độ dài từ 4 đến 15 ký tự.
  • file
    Loại dữ liệu
    binary
    Bắt buộc
    Yes
    Mô tả
    Dòng nhị phân của tệp. Lưu ý rằng tên tệp không được vượt quá 170 ký tự. Kích thước tệp không được vượt quá 10MB.

Trường phản hồi

  • space
    Loại dữ liệu
    string
    Bắt buộc
    Yes
    Mô tả
    Tên của không gian. Nó chỉ có thể là sự kết hợp của chữ cái hoặc số, và độ dài từ 4 đến 15 ký tự.
  • filename
    Loại dữ liệu
    string
    Bắt buộc
    Yes
    Mô tả
    Tên của tệp.
  • url
    Loại dữ liệu
    string
    Bắt buộc
    Yes
    Mô tả
    Liên kết truy cập của tệp. Nếu quyền truy cập của không gian là riêng tư, liên kết truy cập sẽ mang theo vé truy cập.

Demo phản hồi

{
    "code": 200,
    "data": {
        "filename": "1.png",
        "space": "space",
        "url": "https://i.stardots.io/space/1.png"
    },
    "message": "SUCCESS",
    "requestId": "5686efa5-c747-4f63-8657-e6052f8181a9",
    "success": true,
    "ts": 1670899688591
    }

Xóa tệp

Xóa các tệp trong không gian. Giao diện này hỗ trợ các thao tác theo lô.

Phương thức yêu cầu
DELETE
Đường dẫn yêu cầu
/openapi/file/delete
Loại nội dung yêu cầu
application/json
Loại nội dung phản hồi
application/json

Tham số yêu cầu

  • space
    Loại dữ liệu
    string
    Bắt buộc
    Yes
    Mô tả
    Tên của không gian. Nó chỉ có thể là sự kết hợp của chữ cái hoặc số, và độ dài từ 4 đến 15 ký tự.
  • filenameList
    Loại dữ liệu
    array<string>
    Bắt buộc
    Yes
    Mô tả
    Mảng tên các tệp.

Demo yêu cầu

{
    "filenameList": ["1.jpg", "2.jpg"],
    "space": "stardots"
    }

Trường phản hồi

Không có trường

Demo phản hồi

{
    "code": 0,
    "data": null,
    "message": "SUCCESS",
    "requestId": "5686efa5-c747-4f63-8657-e6052f8181a9",
    "success": true,
    "ts": 1670899688591
    }

Mã phản hồi máy chủ

Mã phản hồi máy chủ là mã phản hồi mà máy chủ trả về cho khách hàng để biểu thị kết quả xử lý yêu cầu của máy chủ.

  • 200
    Mô tả
    Thành công
  • 504
    Mô tả
    Yêu cầu vượt quá thời gian
  • 999999
    Mô tả
    Lỗi nội bộ máy chủ
  • 100000
    Mô tả
    Tham số yêu cầu không chính xác
  • 100001
    Mô tả
    Chứng chỉ truy cập hết hạn
  • 100002
    Mô tả
    Người dùng và máy không được xác minh
  • 100003
    Mô tả
    Mã xác minh không chính xác
  • 100004
    Mô tả
    Tài khoản không tồn tại
  • 100005
    Mô tả
    Mật khẩu tài khoản không khớp
  • 100006
    Mô tả
    Chương trình đăng ký không tồn tại
  • 100007
    Mô tả
    Gửi SMS/email quá thường xuyên
  • 100008
    Mô tả
    Gửi SMS/email quá nhiều lần
  • 100009
    Mô tả
    Không gian/tài khoản lưu trữ không tồn tại
  • 100010
    Mô tả
    Không gian/tài khoản lưu trữ đã tồn tại
  • 100011
    Mô tả
    Không gian/tài khoản lưu trữ không trống
  • 100012
    Mô tả
    Thao tác quá thường xuyên
  • 100013
    Mô tả
    Không gian/tài khoản lưu trữ số lượng kuota đã đạt giới hạn
  • 100014
    Mô tả
    Số lượng tệp đã đạt giới hạn số lượng kuota
  • 100015
    Mô tả
    Không gian/tài khoản lưu trữ số lượng kuota đã đạt giới hạn
  • 100016
    Mô tả
    Chương trình đăng ký không khớp
  • 100017
    Mô tả
    Không gian/tài khoản lưu trữ tệp truy cập bị hạn chế
  • 100018
    Mô tả
    Tệp vượt quá giới hạn kích thước
  • 100019
    Mô tả
    Định dạng tệp không được hỗ trợ
  • 100020
    Mô tả
    Referer không được phép
  • 100021
    Mô tả
    Chức năng chỉ được mở cho người dùng Pro hoặc Premium
  • 100022
    Mô tả
    Chức năng chỉ được mở cho người dùng Premium
  • 100023
    Mô tả
    Nội dung chứng chỉ không hợp lệ
  • 100024
    Mô tả
    Chứng chỉ và khóa riêng không khớp
  • 100025
    Mô tả
    Loại MIME hình ảnh không hợp lệ
  • 100026
    Mô tả
    Liên kết truy cập tệp đã hết hạn
  • 100027
    Mô tả
    Số lần gọi API đã đạt giới hạn
  • 100028
    Mô tả
    Thao tác lô chỉ được mở cho người dùng trả phí
  • 100029
    Mô tả
    Liên kết hình ảnh không hợp lệ
  • 100030
    Mô tả
    Tài khoản bị đề xuất vi phạm, đã bị cấm đăng nhập

SDK

StarDots cung cấp SDK cho nhiều ngôn ngữ lập trình khác nhau để giúp bạn tích hợp nhanh chóng với API của chúng tôi. Bạn có thể tìm thấy các SDK trong các liên kết sau:

Nếu bạn gặp bất kỳ vấn đề nào, vui lòng liên hệ với chúng tôi