StarDots.io Logo

StarDots

ドキュメントトップ

オープンAPI

この章では、オープン API を統合する方法を紹介します。以下の知識は開発者向けであり、一定のプログラミングの基礎知識があることを前提としています。

AI エージェントですか?Markdown ドキュメントを読む
このページの目次

認証

StarDots は、クライアントによって開始された http リクエストのヘッダー フィールドを読み取り、関連するフィールドを検証することで認証を実行します。したがって、すべてのオープン API リクエストにはこれらの認証フィールド情報が含まれている必要があります。また、これらのフィールドは大文字と小文字が区別され、すべてのフィールドは小文字でなければならないことに注意する必要があります。

  • x-stardots-timestamp
    説明
    現在のタイムスタンプ(秒単位)。StarDots サーバーとの差は 60 秒を超えることはできません。注: StarDots のタイムゾーンは Asia/Singapore で、UTC+8 です。
  • x-stardots-nonce
    説明
    4 ~ 20 文字のランダムな文字列。大文字、小文字、数字のみを含めることができます。この値は 60 秒以内に一意である必要があります。
  • x-stardots-key
    説明
    StarDots が発行する重要な情報。
  • x-stardots-sign
    説明
    署名フィールドは、上記のフィールドを特定の署名アルゴリズムに従って組み合わせて生成される文字列です。具体的な署名アルゴリズムについては、次に紹介します。

署名アルゴリズム

以下のフィールド値を仮定します

key
2dcded8e-f231-4d0a-8498-d10ef0639eb3
secret
Ey1JNRCiJOzaIOIilcyJvteTn5YXykFXUwmiHLymK8LHkITfGPo5mTUdLlg0jPHST9fMwMZKxIKUBvSsT5uxrq0lXuerll3eRW2tbMOsvySRY539L8cR6iRFV2DQqdlzbseyq7k9N0U5pZgj6f43e3MngbIttgSDl1G44IBOwqsI2HVXE5H6mf1bHlvWw6Ziuk8Xcw18AioG47SFBLIatrq6E9yEBJgFgcYysCH8JvY659hhqI3Ii1CA5zVtyNp
x-stardots-timestamp
1728958751
x-stardots-nonce
fQvDmMLnKE
x-stardots-key
2dcded8e-f231-4d0a-8498-d10ef0639eb3
キーとシークレットは StarDots によって発行され、コンソールの設定ページで確認できます。

次に、上記のフィールド値を組み立てます

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

次に、上で組み立てた文字列のMD5ダイジェストを計算します。

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

最後に要約文字列を大文字に変換します

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

したがって、x-stardots-signフィールドの最終的な値は 51DABFE4B47E73D4A3B85FE29C4F1E82

共通HTTPレスポンス本文

すべてのインターフェース応答は統一されたデータ構造を維持する

  • code
    データ型
    number
    必須
    はい
    説明
    サービス応答コード。200 は成功を示します。
  • message
    データ型
    string
    必須
    はい
    説明
    操作結果のメッセージプロンプト。
  • requestId
    データ型
    string
    必須
    はい
    説明
    トラブルシューティングに使用できる、リクエストの一意の番号。
  • success
    データ型
    boolean
    必須
    はい
    説明
    ビジネスオペレーションが成功したかどうかを示します。
  • ts
    データ型
    number
    必須
    はい
    説明
    サーバーのミリ秒タイムスタンプ。
  • data
    データ型
    any
    必須
    はい
    説明
    ビジネス データ フィールド。このフィールドには任意のデータ型を指定できます。特定のデータ型については、対応するインターフェイスを参照してください。

機能インターフェース

すべてのインターフェースにリクエスト レート制限があり、すべてのインターフェースがレート制限ルール セットを共有することに注意してください。現在のところ、StarDots のレート制限は 1 分あたり 300 回です。

リクエストエンドポイント

https://api.stardots.io

スペースリスト

スペースリストデータを取得します。

リクエスト方法
GET
リクエストパス
/openapi/space/list
リクエストコンテンツタイプ
application/json
レスポンスコンテンツタイプ
application/json

リクエストパラメータ

  • page
    データ型
    number
    必須
    不
    説明
    ページ番号、デフォルト値は 1 です。
  • pageSize
    データ型
    number
    必須
    不
    説明
    1 ページあたりのエントリ数の範囲は 1 ~ 100 で、デフォルト値は 20 です。

デモをリクエスト

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

回答フィールド

  • name
    データ型
    string
    必須
    はい
    説明
    スペースの名前。
  • public
    データ型
    boolean
    必須
    はい
    説明
    スペースのアクセシビリティが偽であるかどうか。
  • createdAt
    データ型
    number
    必須
    はい
    説明
    スペースが作成された際のシステム タイムスタンプ (秒単位)。タイム ゾーンは UTC+8 です。
  • fileCount
    データ型
    number
    必須
    はい
    説明
    このスペース内のファイルの数。

レスポンスデモ

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

スペースを作成する

新しいスペースを作成します。

リクエスト方法
PUT
リクエストパス
/openapi/space/create
リクエストコンテンツタイプ
application/json
レスポンスコンテンツタイプ
application/json

リクエストパラメータ

  • space
    データ型
    string
    必須
    はい
    説明
    スペースの名前。文字または数字の組み合わせのみで、長さは 4 文字から 15 文字です。
  • public
    データ型
    boolean
    必須
    不
    説明
    スペースがパブリックにアクセス可能かどうかを指定します。デフォルト値は false です。

デモをリクエスト

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

回答フィールド

フィールドなし

レスポンスデモ

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

スペースを削除

既存のスペースを削除します。このスペースにファイルがないことを確認する必要があります。そうでない場合、削除は失敗します。

リクエスト方法
DELETE
リクエストパス
/openapi/space/delete
リクエストコンテンツタイプ
application/json
レスポンスコンテンツタイプ
application/json

リクエストパラメータ

  • space
    データ型
    string
    必須
    はい
    説明
    スペースの名前。文字または数字の組み合わせのみで、長さは 4 文字から 15 文字です。

デモをリクエスト

{
    "space": "stardots"
}

回答フィールド

フィールドなし

レスポンスデモ

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

空間アクセシビリティ

スペースのアクセシビリティを切り替えます。

リクエスト方法
POST
Request path
/openapi/space/accessibility/toggle
リクエストコンテンツタイプ
application/json
レスポンスコンテンツタイプ
application/json

リクエストパラメータ

  • space
    データ型
    string
    必須
    はい
    説明
    スペースの名前。文字または数字の組み合わせのみで、長さは 4 文字から 15 文字です。
  • public
    データ型
    boolean
    必須
    不
    説明
    スペースがパブリックにアクセス可能かどうかを指定します。デフォルト値は false です。

デモをリクエスト

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

回答フィールド

フィールドなし

レスポンスデモ

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

スペース内のファイルリスト

スペース内のファイルのリストを取得します。リストはファイルのアップロード時間の降順で並べ替えられます。

リクエスト方法
GET
リクエストパス
/openapi/file/list
リクエストコンテンツタイプ
application/json
レスポンスコンテンツタイプ
application/json

リクエストパラメータ

  • space
    データ型
    string
    必須
    はい
    説明
    スペースの名前。文字または数字の組み合わせのみで、長さは 4 文字から 15 文字です。
  • page
    データ型
    number
    必須
    不
    説明
    ページ番号、デフォルト値は 1 です。
  • pageSize
    データ型
    number
    必須
    不
    説明
    1 ページあたりのエントリ数の範囲は 1 ~ 100 で、デフォルト値は 20 です。

デモをリクエスト

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

回答フィールド

  • page
    データ型
    number
    必須
    はい
    説明
    ページ番号、デフォルト値は 1 です。
  • pageSize
    データ型
    number
    必須
    はい
    説明
    1 ページあたりのエントリ数の範囲は 1 ~ 100 で、デフォルト値は 20 です。
  • totalCount
    データ型
    number
    必須
    はい
    説明
    エントリの合計数。
  • list
    データ型
    array<object>
    必須
    はい
    説明
    ファイル リスト配列。
  • list.name
    データ型
    string
    必須
    はい
    説明
    ファイルの名前。
  • list.byteSize
    データ型
    number
    必須
    はい
    説明
    ファイルのサイズ(バイト単位)。
  • list.size
    データ型
    string
    必須
    はい
    説明
    読みやすいようにフォーマットされたファイル サイズ。
  • list.uploadedAt
    データ型
    number
    必須
    はい
    説明
    ファイルのアップロードのタイムスタンプ(秒単位)。タイムゾーンは UTC+8 です。
  • list.url
    データ型
    string
    必須
    はい
    説明
    ファイルのアクセス アドレス。スペースのアクセスがプライベートの場合、このフィールド値には 20 秒間有効なアクセス チケットが含まれることに注意してください。

レスポンスデモ

{
    "code": 200,
    "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
}

ファイルアクセスチケット

ファイルのアクセス チケットを取得します。スペースのアクセスが非公開の場合、スペースの下のファイルにアクセスするにはアクセス チケットが必要です。そうでない場合、リクエストは拒否されます。

リクエスト方法
POST
リクエストパス
/openapi/file/ticket
リクエストコンテンツタイプ
application/json
レスポンスコンテンツタイプ
application/json

リクエストパラメータ

  • space
    データ型
    string
    必須
    はい
    説明
    スペースの名前。文字または数字の組み合わせのみで、長さは 4 文字から 15 文字です。
  • filename
    データ型
    string
    必須
    はい
    説明
    ファイルの名前。

デモをリクエスト

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

回答フィールド

  • ticket
    データ型
    string
    必須
    はい
    説明
    アクセスチケット。

レスポンスデモ

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

ファイルのアップロード

ファイルをスペースにアップロードします。このリクエストでは、フォームの形式でリクエストを開始する必要があることに注意してください。

リクエスト方法
PUT
リクエストパス
/openapi/file/upload
リクエストコンテンツタイプ
multipart/form-data
レスポンスコンテンツタイプ
application/json

リクエストパラメータ

  • space
    データ型
    string
    必須
    はい
    説明
    スペースの名前。文字または数字の組み合わせのみで、長さは 4 文字から 15 文字です。
  • file
    データ型
    binary
    必須
    はい
    説明
    ファイルのバイナリ ストリーム。ファイル名は 170 文字を超えてはならないことに注意してください。ファイルサイズは10MBを超えることはできません。

回答フィールド

  • space
    データ型
    string
    必須
    はい
    説明
    スペースの名前。文字または数字の組み合わせのみで、長さは 4 文字から 15 文字です。
  • filename
    データ型
    string
    必須
    はい
    説明
    ファイルの名前。
  • url
    データ型
    string
    必須
    はい
    説明
    ファイルのアクセス リンク。スペースのアクセスが非公開の場合、アクセス リンクにはアクセス チケットが含まれます。

レスポンスデモ

{
    "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
}

ファイルを削除する

スペース内のファイルを削除します。このインターフェースはバッチ操作をサポートしています。

リクエスト方法
DELETE
リクエストパス
/openapi/file/delete
リクエストコンテンツタイプ
application/json
レスポンスコンテンツタイプ
application/json

リクエストパラメータ

  • space
    データ型
    string
    必須
    はい
    説明
    スペースの名前。文字または数字の組み合わせのみで、長さは 4 文字から 15 文字です。
  • filenameList
    データ型
    array<string>
    必須
    はい
    説明
    ファイル名の配列。

デモをリクエスト

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

回答フィールド

フィールドなし

レスポンスデモ

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

サーバーレスポンスコード

サーバーのレスポンスコードは、サーバーがクライアントに返すレスポンスコードで、サーバーがリクエストを処理した結果を表します。

  • 200
    説明
    成功しました
  • 504
    説明
    リクエストタイムアウト
  • 999999
    説明
    サーバー内部エラー
  • 100000
    説明
    リクエストパラメータエラー
  • 100001
    説明
    アクセストークンが無効
  • 100002
    説明
    人間認証に失敗しました
  • 100003
    説明
    検証コードが正しくありません
  • 100004
    説明
    アカウントが存在しません
  • 100005
    説明
    アカウントパスワードが一致しません
  • 100006
    説明
    サブスクリプションプランが存在しません
  • 100007
    説明
    SMS/メールの送信が頻繁すぎます
  • 100008
    説明
    SMS/メールの送信回数が制限を超えました
  • 100009
    説明
    スペース/ストレージバケットが存在しません
  • 100010
    説明
    スペース/ストレージバケットが既に存在します
  • 100011
    説明
    スペース/ストレージバケットが空ではありません
  • 100012
    説明
    操作が頻繁すぎます
  • 100013
    説明
    スペース/ストレージバケットの数量配额が達しました
  • 100014
    説明
    ファイルの数量配额が達しました
  • 100015
    説明
    流量転送配額が枯渇しました
  • 100016
    説明
    サブスクリプションプランが一致しません
  • 100017
    説明
    スペース/ストレージバケットのファイルアクセスが制限されています
  • 100018
    説明
    ファイルがサイズの上限を超えています
  • 100019
    説明
    ファイル形式がサポートされていません
  • 100020
    説明
    Refererが許可されていません
  • 100021
    説明
    機能はProまたはPremiumユーザーにのみ開放されています
  • 100022
    説明
    機能はPremiumユーザーにのみ開放されています
  • 100023
    説明
    証明書の内容が無効です
  • 100024
    説明
    証明書と秘密鍵が一致しません
  • 100025
    説明
    無効な画像MIMEタイプ
  • 100026
    説明
    ファイルアクセスリンクが失効しました
  • 100027
    説明
    APIの呼び出し回数が上限に達しました
  • 100028
    説明
    バッチ操作は有料ユーザーにのみ開放されています
  • 100029
    説明
    画像リンクが無効です
  • 100030
    説明
    アカウントが違反を犯していると疑われています

SDK

StarDots は、API との迅速な統合を支援するために、さまざまなプログラミング言語用の SDK を提供しています。以下のリンクから SDK を入手できます:

問題が発生した場合はご連絡ください