開発者オープン API

オープン API

Zeabur の API は主に GraphQL で構築されており、Zeabur Dashboard、Zeabur CLI などの一連の Zeabur 製品の基盤となっています。私たちはオープン API を提供しており、コードを通じて Zeabur を制御することができます。 また、Zeabur は Schema Repository に GraphQL API 以外の JSON schema と OpenAPI specification の一部を配置しています。

認証

Zeabur API を使用するには、Authorization に API キー を含める必要があります。API キーの生成方法については、こちらのドキュメント をお読みください。

入力例は以下の通りです：

curl --request POST \
  --url https://api.zeabur.com/graphql \
  --header 'Authorization: Bearer {YOUR_API_TOKEN}' \
  --header 'Content-Type: application/json' \
  --data '{"query":"query { me { username } }"}'

GraphQL API

Apollo Explorer にアクセスして、利用可能なすべての Zeabur API GraphQL メソッドを確認し、テストしたり、cURL コマンドにコピーしたりすることができます。

IDE で GraphQL を記述することを好む場合や、型のヒントが必要な場合は、Explorer の「Schema」→「SDL」に移動して、Zeabur API の完全な Schema をダウンロードすることができます。

必要な API がこの Schema に含まれていない場合は、Discord で私たちにお知らせください。

ローカルプロジェクトのアップロード API

Git Repository からのデプロイが主流な方法ですが、場合によっては、事前にパッケージ化されたアプリケーションを直接デプロイする必要があるかもしれません。一般的な状況としては以下が挙げられます：

  • CI/CD パイプラインが、.zip ファイルなどのビルド済みの成果物 (artifact) を生成する場合。
  • プロジェクトを手動でアップロードしたいが、それを Git Repository と関連付けたくない場合。

そのため、Zeabur Upload API は、ZIP ファイルを直接アップロードできる API を提供しています。Zeabur は、アップロードされた ZIP を自動的に解凍し、あなたのプロジェクトにデプロイします。

コアコンセプト：プリサイン付き URL (Pre-signed URL) を使用した安全なアップロード

Zeabur Upload API は、プリサイン付き URL (Pre-signed URL) を発行します。この URL は、一時的で安全なリンクであり、Zeabur のコードステージングスペースにファイルを直接アップロードするための一時的な権限を付与します。

ワークフロー全体は、以下のシーケンス図で表すことができます：

アップロードフロー

アップロードを開始する前に、ファイルに関する以下の2つの情報を取得する必要があります：

  • content_length：ファイルのサイズ（単位：バイト）。
  • content_hash：ファイルコンテンツの SHA256 ハッシュ値を Base64 エンコードしたもの。

次に、アップロードステージを作成できます。まず、Zeabur にファイルをアップロードする準備ができていることを通知する必要があります。

POST /v2/upload
Content-Type: application/json
 
{
  "content_hash": "あなたが計算した BASE64 エンコードされた SHA256 ハッシュ値",
  "content_hash_algorithm": "sha256",
  "content_length": 12345678
}

成功した場合 (201 Created)、Zeabur はプリサイン付き URL の詳細と、このアップロードステージを追跡するための upload_id を返します。

{
    "presign_header": { "Content-Type": "application/zip" },
    "presign_method": "PUT",
    "presign_url": "https://zeabur-uploads.s3.ap-east-1.amazonaws.com/...",
    "upload_id": "一意の UPLOAD_ID"
}

次に、前のステップで取得した情報を使用してファイルをアップロードします。このリクエストは presign_url に送信されるものであり、Zeabur API ではないことに注意してください。

  • Method: PUT (または、前のステップの presign_method で返されたメソッド)
  • URL: 前のステップのレスポンスに含まれる presign_url。
  • Headers: presign_header で返されたヘッダー (Content-Type: application/zip など) を含める必要があります。
  • Body: ZIP ファイルの生のバイナリデータ。

このリクエストが 200 OK のレスポンスを受け取ったら、ファイルは安全に保存されました。最後に、ファイルが準備できたことと、それをどのように処理するかを Zeabur に伝える必要があります。以前取得した upload_id を使用して、POST /v2/upload/{upload_id}/prepare エンドポイントを呼び出します。

POST /v2/upload/{upload_id}/prepare
Content-Type: application/json
Authorization: Bearer {YOUR_API_TOKEN}

あなたの目的に応じて、Request Body には2つの選択肢があります。既存のプロジェクトにアップロードする場合、service_id と environment_id を提供する必要があります。このタイプは、進行中のデプロイへの url を返します。ユーザーをこの URL にリダイレクトすることで、デプロイステータスを確認させることができます。

{
  "upload_type": "existing_service",
  "service_id": "あなたの既存サービスの ID",
  "environment_id": "あなたのサービス環境の ID"
}

プロジェクトの作成をユーザーに誘導したい場合は、upload_type に new_project を渡すだけです。このタイプは、ユーザーにプロジェクト作成を誘導できる url を返します。ユーザーをこの URL にリダイレクトすることで、ユーザーにプロジェクトを作成させることができます。

{
  "upload_type": "new_project"
}

ドキュメントとスキーマ

完全なドキュメントと OpenAPI スキーマは、Upload API ドキュメントを参照してください。

テンプレートデプロイ API

テンプレート仕様 YAML ファイル がある場合、以下の GraphQL mutation を使用して指定したプロジェクトにデプロイできます：

mutation DeployTemplate($rawSpecYaml: String, $projectId: ObjectID) {
  deployTemplate(rawSpecYaml: $rawSpecYaml, projectID: $projectId) {
    _id  # String!
  }
}

この API は大量デプロイに適しています。

コンテナ操作 API

ここでの API を使用すると、Zeabur の指定されたサービスにファイルをアップロードしたり、ダウンロードしたり、指定されたサービスにコマンドを送信したりできます。

ファイルのアップロード

💡

現在、アップロードには 100MB のファイルサイズ制限があります。

POST https://api.zeabur.com/projects/project-id/services/service-id/files
Content-Type: multipart/form-data
Authorization: Bearer <YOUR_API_TOKEN>
  • Payload（フォーム内容）
    • file (Blob)：ファイル内容
    • path (string)：ファイルパス
    • environment (string)：environment ID のこと、Dashboard の URL の envID から取得可能
  • Response
    • 200 OK
    • 500 Internal Server Error、例： {"code": "INTERNAL_SERVER_ERROR", "error": "failed to upload file"}

ファイルのダウンロード

GET https://api.zeabur.com/projects/project-id/services/service-id/files?path=[PATH]&environment=[ENVIRONMENT]
Authorization: Bearer <YOUR_API_TOKEN>
  • Query
    • path (string)：ファイルパス
    • environment (string)：environment ID のこと、Dashboard の URL の envID から取得可能
  • Response
    • 200 OK, application/octet-stream
    • 500 Internal Server Error、例： {"code": "INTERNAL_SERVER_ERROR", "error": "failed to download file"}

ファイルの一覧表示

「単一コマンドの実行」API を使用して実行してください：

$ ls -A -a -F -1 /

ファイルの削除

「単一コマンドの実行」API を使用して実行してください：

$ rm -r FILENAME

単一コマンドの実行

GraphQL API を使用して実行：

mutation ExecuteCommand($serviceId: ObjectID!, $environmentId: ObjectID!, $command: [String!]!) {
  executeCommand(serviceID: $serviceId, environmentID: $environmentId, command: $command) {
    exitCode  # Int!
    output    # String!
  }
}

WebSocket を使用したサービスターミナルの取得

  • WebSocket endpoint: wss://api.zeabur.com/exec/<service-id>
  • WebSocket に書き込まれた内容が実際の入力となります
  • Resize Control Controls：[RESIZE_CONTROL, COLS_LSB, COLS_MSB, ROWS_LSB, ROWS_MSB] 
    const buffer = new Uint8Array([
  RESIZE_CONTROL,
  dims.cols & 0xFF,
  dims.cols >> 8,
  dims.rows & 0xFF,
  dims.rows >> 8
]);

ビルド時ログの取得

GraphQL API を使用して実行：

query BuildLogs($projectId: ObjectID!, $deploymentId: ObjectID!, $timestampCursor: Time) {
  buildLogs(projectID: $projectId, deploymentID: $deploymentId, timestampCursor: $timestampCursor) {
    message    # String!
    timestamp  # Time!
  }
}

ランタイムログの取得

GraphQL API を使用して実行：

query RuntimeLogs($projectId: ObjectID!, $serviceId: ObjectID!, $environmentId: ObjectID!, $timestampCursor: Time) {
  runtimeLogs(projectID: $projectId, serviceID: $serviceId, environmentID: $environmentId, timestampCursor: $timestampCursor) {
    message    # String!
    timestamp  # Time!
  }
}

ビルド時ログのサブスクリプション

GraphQL API を使用して実行：

subscription BuildLogReceived($projectId: ObjectID!, $deploymentId: ObjectID!) {
  buildLogReceived(projectID: $projectId, deploymentID: $deploymentId) {
    message    # String!
    timestamp  # Time!
  }
}

ランタイムログのサブスクリプション

GraphQL API を使用して実行：

subscription RuntimeLogReceived($projectId: ObjectID!, $serviceId: ObjectID!, $environmentId: ObjectID!) {
  runtimeLogReceived(projectID: $projectId, serviceID: $serviceId, environmentID: $environmentId) {
    message    # String!
    timestamp  # Time!
  }
}
API キーの作成と使用専用サーバー