高火力 DOK APIドキュメント (1.0.0)

Download OpenAPI specification:Download


はじめに

高火力 DOK」が提供するAPIの利用方法を公開しています。
「高火力 DOK」自体の説明についてはマニュアルをご覧ください。

APIご利用の前に

本APIの利用には、さくらのクラウドの APIキー が必要です。
APIキーの発行についてはマニュアルをご覧ください。

APIキーの「アクセストークン」をユーザーID、「アクセストークンシークレット」をパスワードとした Basic認証 で本APIをご利用ください。

Web API Base URL

https://secure.sakura.ad.jp/cloud/zone/{ゾーンID}/api/managed-container/1.0

ゾーンIDついてはこちら をご覧ください。

リクエスト例

石狩第一ゾーン(ゾーンID: is1a)で、タスク一覧を取得する場合の実行例は下記となります。

$ curl -u "{アクセストークン}:{アクセストークンシークレット}" -X GET https://secure.sakura.ad.jp/cloud/zone/is1a/api/managed-container/1.0/tasks/

認証

認証関連のAPIです。

クラウドアカウント情報の取得

APIキーに紐づく、さくらのクラウドのアカウント情報を取得します。

Authorizations:
BasicAuth

Responses

Response samples

Content type
application/json
{
  • "user": { },
  • "member": {
    },
  • "account": {
    },
  • "notification": {}
}

利用規約への同意

利用規約に同意します。
必ず内容を熟読の上、同意できる場合のみ本APIをコールしてください。

同意するまで(本APIをコールするまで)、本サービスの各種操作は行えません。

Authorizations:
BasicAuth
query Parameters
version
string
Example: version=vXXXXXXX

同意した利用規約のバージョン

Responses

コンテナレジストリー

コンテナレジストリーの認証情報に関するAPIです。

コンテナレジストリー認証情報の一覧を取得

「認証情報登録API」で登録した認証情報の一覧を取得します。

Authorizations:
BasicAuth

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "results": [
    ]
}

コンテナレジストリーの認証情報を登録

認証が必要なコンテナレジストリーの、認証情報を登録します。

プライベートなレジストリーに格納したコンテナイメージを実行する場合、事前にこのAPIで認証情報を登録してください。
公開レジストリーのイメージを実行する場合は本操作は不要です。

Authorizations:
BasicAuth
Request Body schema: application/json
required
hostname
required
string
username
required
string
password
required
string

Responses

Request samples

Content type
application/json
{
  • "hostname": "example.sakuracr.jp",
  • "username": "user01",
  • "password": "p@ssw0rd"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2024-10-10T13:50:40.250+09:00",
  • "updated_at": "2024-10-10T13:50:40.250+09:00",
  • "hostname": "example.sakuracr.jp",
  • "username": "user01"
}

コンテナレジストリーの認証情報を取得

指定IDのコンテナレジストリーの認証情報を取得します。

Authorizations:
BasicAuth
path Parameters
registryId
required
string <uuid>

レジストリーID(登録APIのレスポンス内の id フィールド)

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2024-10-10T13:50:40.250+09:00",
  • "updated_at": "2024-10-10T13:50:40.250+09:00",
  • "hostname": "example.sakuracr.jp",
  • "username": "user01"
}

コンテナレジストリーの認証情報を抹消

登録された認証情報を抹消します。
本APIの呼び出し後は、同じレジストリーIDは本サービスで使えなくなります。

Authorizations:
BasicAuth
path Parameters
registryId
required
string <uuid>

レジストリーID(登録APIのレスポンス内の id フィールド)

Responses

コンテナレジストリーの認証情報を更新

登録済みの認証情報を変更します。
登録時に間違えた場合や、コンテナレジストリーのパスワードを変更した場合などにお使いください。

Authorizations:
BasicAuth
path Parameters
registryId
required
string <uuid>

レジストリーID(登録APIのレスポンス内の id フィールド)

Request Body schema: application/json
required
hostname
required
string
username
required
string
password
required
string

Responses

Request samples

Content type
application/json
{
  • "hostname": "example.sakuracr.jp",
  • "username": "user01",
  • "password": "p@ssw0rd"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2024-10-10T13:50:40.250+09:00",
  • "updated_at": "2024-10-10T13:50:40.250+09:00",
  • "hostname": "example.sakuracr.jp",
  • "username": "user01"
}

タスク

タスクの実行に関するAPIです。

タスクの一覧を取得

登録済みのタスクの一覧情報を取得します。

Authorizations:
BasicAuth
query Parameters
page
integer
Default: 1

ページ番号(1 origin)

page_size
integer
Default: 100

1ページのサイズ

tasks
string
Example: tasks=task
  • タスク・コンテナでの絞り込み(コンマ区切り・スペース区切りでAND検索可能)
  • 検索対象:
    • タスク
      • ID
      • 名前
    • コンテナ
      • イメージ
      • プラン
include_artifact
boolean

アーティファクトが存在するタスクのみ表示する場合は true

created_after
string <iso8601> (DateTime)
Example: created_after=2024-10-10T13:50:40.250+09:00

作成日時 (開始)

created_before
string <iso8601> (DateTime)
Example: created_before=2024-10-10T13:50:40.250+09:00

作成日時 (終了)

status
Array of strings (TaskStatus)
Items Enum: "waiting" "running" "error" "done" "aborted" "canceled"

ステータスでの絞り込み

plan
Array of strings (PlanID)
Items Enum: "v100-32gb" "h100-80gb"

プランでの絞り込み

tag
string
Example: tag=tag1

タグでの絞り込み

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "results": [
    ]
}

タスクの登録

新しいタスクを登録します。
タスク実行の詳細についてはマニュアルをご覧ください。

Authorizations:
BasicAuth
Request Body schema: application/json
required
name
required
string
required
Array of objects (ContainerDefinition)
tags
required
Array of strings
execution_time_limit_sec
integer or null [ 600 .. 1728000 ]
Default: null

タスクの実行時間上限(秒)。600以上1728000以下(20日)で指定します。nullの場合は上限なしとして扱います。

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "containers": [
    ],
  • "tags": [
    ],
  • "execution_time_limit_sec": null
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2024-10-10T13:50:40.250+09:00",
  • "updated_at": "2024-10-10T13:50:40.250+09:00",
  • "canceled_at": "2024-10-10T13:50:40.250+09:00",
  • "containers": [
    ],
  • "status": "waiting",
  • "tags": [
    ],
  • "error_message": "invalid registry permission",
  • "artifact": {
    },
  • "execution_time_limit_sec": null
}

タスクの情報取得

登録したタスクの情報を取得します。

Authorizations:
BasicAuth
path Parameters
taskId
required
string <uuid>

タスクID(登録APIのレスポンス内の id フィールド)

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2024-10-10T13:50:40.250+09:00",
  • "updated_at": "2024-10-10T13:50:40.250+09:00",
  • "canceled_at": "2024-10-10T13:50:40.250+09:00",
  • "containers": [
    ],
  • "status": "waiting",
  • "tags": [
    ],
  • "error_message": "invalid registry permission",
  • "artifact": {
    },
  • "execution_time_limit_sec": null
}

タスクの情報削除

タスクの情報を削除します。
本APIの呼び出し後は、同じタスクIDは本サービスで使えなくなります。

注)本APIは、実行中のタスクをキャンセルするAPIではありません。
タスクをキャンセルしたい場合は、タスクのキャンセルAPIをコールしてください。

Authorizations:
BasicAuth
path Parameters
taskId
required
string <uuid>

Responses

タスクのキャンセル

実行中のタスクをキャンセルします。

Authorizations:
BasicAuth
path Parameters
taskId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2024-10-10T13:50:40.250+09:00",
  • "updated_at": "2024-10-10T13:50:40.250+09:00",
  • "canceled_at": "2024-10-10T13:50:40.250+09:00",
  • "containers": [
    ],
  • "status": "waiting",
  • "tags": [
    ],
  • "error_message": "invalid registry permission",
  • "artifact": {
    },
  • "execution_time_limit_sec": null
}

タスク関連ファイルのダウンロード用URL取得

タスクに関連するファイル(出力ファイル)のダウンロードURLを取得します。

Authorizations:
BasicAuth
path Parameters
taskId
required
string <uuid>
target
required
string
Value: "output"
query Parameters
filename
string
Example: filename=output.txt

指定するとContentDispositionヘッダーにファイル名として指定されます

Responses

Response samples

Content type
application/json

ログストリームの接続要求

ログストリームを受信するためのWebSocketの接続情報を取得します

Authorizations:
BasicAuth
path Parameters
taskId
required
string <uuid>
containerIndex
required
number
Example: 0

Responses

Response samples

Content type
application/json
{
  • "url": "wss://example.com/ws",
  • "token": "xxxx.xxxxxxxxxxxxxxxxxxx.xxxxx"
}

タスク完了通知設定

タスク完了時の通知設定を行います。

  • is_enabled: 通知を有効にするかどうか
  • endpoint_ids: 通知先のエンドポイントIDのリスト

is_enabledtrue の場合、タスクが完了したときに通知イベントが作成されます。

Authorizations:
BasicAuth
path Parameters
taskId
required
string <uuid>
Request Body schema: application/json
required
is_enabled
boolean

通知を有効にするかどうか

endpoint_ids
Array of strings <uuid> [ items <uuid > ]

通知先のエンドポイントIDのリスト

Responses

Request samples

Content type
application/json
{
  • "is_enabled": true,
  • "endpoint_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "ok": true
}

アーティファクト

アーティファクト(タスクの生成物)の操作に関するAPIです。

本APIでアーティファクトを操作するためには、タスク内で所定のディレクトリーにアーティファクトを保存いただく必要があります。
詳しくはSAKURA_ARTIFACT_DIR に関する説明を参照ください。

アーティファクト情報の一覧取得

アーティファクト情報の一覧を取得します。

Authorizations:
BasicAuth
query Parameters
page
integer
Default: 1

ページ番号

page_size
integer
Default: 100

1ページのサイズ

task
string <uuid>

指定するとタスクIDで絞り込みます

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "results": [
    ]
}

アーティファクト情報を取得

アーティファクトの情報を取得します。

Authorizations:
BasicAuth
path Parameters
artifactId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "task": "4879b8a6-fb3e-4a0d-aef8-b0ea469ac85c",
  • "created_at": "2024-10-10T13:50:40.250+09:00",
  • "updated_at": "2024-10-10T13:50:40.250+09:00",
  • "filename": "artifact.tar.gz",
  • "size_bytes": 0
}

アーティファクトのダウンロードURL取得

アーティファクトのダウンロードURLを取得します。

Authorizations:
BasicAuth
path Parameters
artifactId
required
string <uuid>
query Parameters
filename
string
Example: filename=artifact.tar.gz

指定するとContentDispositionヘッダーにファイル名として指定されます

Responses

Response samples

Content type
application/json

プラン

GPUプランに関するAPIです。

GPUプランの一覧を取得

タスク実行時にご利用可能なGPUプランの一覧を取得します。
実行時には id の値をご指定ください。

Authorizations:
BasicAuth

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "results": [
    ]
}

SSH

タスクへのSSH接続に関するAPIです。

SSH公開鍵情報の一覧を取得

登録済みのSSH公開鍵情報情報を取得します。

Authorizations:
BasicAuth
query Parameters
page
integer
Default: 1

ページ番号(1 origin)

page_size
integer
Default: 100

1ページのサイズ

is_active
boolean

有効状態でフィルタリングします。

  • true: 有効な鍵のみ
  • false: 無効な鍵のみ
  • 未指定: すべて

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "results": [
    ]
}

SSH公開鍵情報の登録

新しいSSH公開鍵情報を登録します。

Authorizations:
BasicAuth
Request Body schema: application/json
required

name:
 SSH公開鍵情報の名前を指定します。
pub_key:
 登録するSSH公開鍵を指定します。
is_active:
 登録するSSH公開鍵の有効/無効を設定します。

name
required
string
pub_key
required
string
is_active
required
boolean

Responses

Request samples

Content type
application/json
{
  • "name": "key-001",
  • "pub_key": "ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAuKpK2QW9+3aZJ2vLC4Rk9v2DlHh8ejZ3O8Qp8g7VRVqbgOHRqZL3FoyPb6jl8mUvUeT5LjYKX8cL7ozGnYtFqN2KqzVGpjJ9g+J3MlNhnfM8jGZoIf1nmfpA5gItkX5iLtJ9cPC3nVo4U9qxNT3kNdc7MkPaa2Te9Zz5eQdZbMFeBpjNjfK example-001@example.com",
  • "is_active": true
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "key-001",
  • "pub_key": "ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAuKpK2QW9+3aZJ2vLC4Rk9v2DlHh8ejZ3O8Qp8g7VRVqbgOHRqZL3FoyPb6jl8mUvUeT5LjYKX8cL7ozGnYtFqN2KqzVGpjJ9g+J3MlNhnfM8jGZoIf1nmfpA5gItkX5iLtJ9cPC3nVo4U9qxNT3kNdc7MkPaa2Te9Zz5eQdZbMFeBpjNjfK example-001@example.com",
  • "is_active": true
}

SSH公開鍵情報の取得

登録したSSH公開鍵の情報を取得します。

Authorizations:
BasicAuth
path Parameters
keyID
required
string <uuid>

SSH公開鍵情報ID

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "key-001",
  • "pub_key": "ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAuKpK2QW9+3aZJ2vLC4Rk9v2DlHh8ejZ3O8Qp8g7VRVqbgOHRqZL3FoyPb6jl8mUvUeT5LjYKX8cL7ozGnYtFqN2KqzVGpjJ9g+J3MlNhnfM8jGZoIf1nmfpA5gItkX5iLtJ9cPC3nVo4U9qxNT3kNdc7MkPaa2Te9Zz5eQdZbMFeBpjNjfK example-001@example.com",
  • "is_active": true
}

SSH公開鍵情報の更新

SSH公開鍵情報を更新します。

SSH公開鍵(pub_key)の変更はできません。
変更が必要な場合はSSH公開鍵情報の削除APIで削除の後、SSH公開鍵情報の登録APIで作成し直してください。

Authorizations:
BasicAuth
path Parameters
keyID
required
string <uuid>

SSH公開鍵情報ID

Request Body schema: application/json
required

name:
 SSH公開鍵情報の名前を指定します。
is_active:
 SSH公開鍵の有効/無効を設定します。

name
required
string
is_active
required
boolean

Responses

Request samples

Content type
application/json
{
  • "name": "key-001",
  • "is_active": true
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "key-001",
  • "pub_key": "ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAuKpK2QW9+3aZJ2vLC4Rk9v2DlHh8ejZ3O8Qp8g7VRVqbgOHRqZL3FoyPb6jl8mUvUeT5LjYKX8cL7ozGnYtFqN2KqzVGpjJ9g+J3MlNhnfM8jGZoIf1nmfpA5gItkX5iLtJ9cPC3nVo4U9qxNT3kNdc7MkPaa2Te9Zz5eQdZbMFeBpjNjfK example-001@example.com",
  • "is_active": true
}

SSH公開鍵情報の削除

SSH公開鍵情報を削除します。

Authorizations:
BasicAuth
path Parameters
keyID
required
string <uuid>

SSH公開鍵情報ID

Responses

料金

料金および、お支払いに関するAPIです。

請求情報取得

指定年月の請求情報を取得します。

Authorizations:
BasicAuth
query Parameters
year
integer
Example: year=2024

取得対象の年

month
integer
Example: month=6

取得対象の月

day
integer
Example: day=1

取得対象の日

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "results": [
    ]
}

プラン別の単価一覧取得

指定年月のプラン別単価(実行時間1秒あたりの金額)一覧を取得します。

Authorizations:
BasicAuth
query Parameters
year
integer
Example: year=2024

取得対象の年

month
integer
Example: month=6

取得対象の月

day
integer
Example: day=10

取得対象の日

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "results": [
    ]
}

通知

通知設定および通知エンドポイントに関するAPIです。

通知エンドポイント一覧取得

登録済みの通知エンドポイントの一覧を取得します。

Authorizations:
BasicAuth
query Parameters
page
integer
Default: 1

ページ番号(1 origin)

page_size
integer
Default: 100

1ページのサイズ

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "results": [
    ]
}

通知エンドポイント登録

新しい通知エンドポイントを登録します。

現在サポートしているエンドポイントタイプは以下の通りです:

  • webhook: Webhook URL
Authorizations:
BasicAuth
Request Body schema: application/json
required
endpoint_type
required
string
Value: "webhook"

エンドポイントの種類

address
required
string

Webhook URL またはメールアドレス

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2024-10-10T13:50:40.250+09:00",
  • "updated_at": "2024-10-10T13:50:40.250+09:00",
  • "endpoint_type": "webhook",
  • "is_verified": true
}

通知エンドポイント取得

指定IDの通知エンドポイントを取得します。

Authorizations:
BasicAuth
path Parameters
endpointId
required
integer

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2024-10-10T13:50:40.250+09:00",
  • "updated_at": "2024-10-10T13:50:40.250+09:00",
  • "endpoint_type": "webhook",
  • "is_verified": true
}

通知エンドポイント更新

通知エンドポイントを更新します。

Authorizations:
BasicAuth
path Parameters
endpointId
required
integer
Request Body schema: application/json
required
endpoint_type
string
Value: "webhook"

エンドポイントの種類

address
string

Webhook URL またはメールアドレス

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2024-10-10T13:50:40.250+09:00",
  • "updated_at": "2024-10-10T13:50:40.250+09:00",
  • "endpoint_type": "webhook",
  • "is_verified": true
}

通知エンドポイント削除

通知エンドポイントを削除します。

Authorizations:
BasicAuth
path Parameters
endpointId
required
integer

Responses

通知設定一覧取得

登録済みの通知設定の一覧を取得します。

Authorizations:
BasicAuth
query Parameters
page
integer
Default: 1

ページ番号(1 origin)

page_size
integer
Default: 100

1ページのサイズ

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "results": [
    ]
}

通知設定登録

新しい通知設定を登録します。

Authorizations:
BasicAuth
Request Body schema: application/json
required
event_type
required
string

通知イベントの種類

is_enabled
required
boolean

通知設定を有効にするかどうか

endpoint_ids
required
Array of strings <uuid> [ items <uuid > ]

通知先のエンドポイントIDのリスト

Responses

Request samples

Content type
application/json
{
  • "event_type": "task_completed",
  • "is_enabled": true,
  • "endpoint_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2024-10-10T13:50:40.250+09:00",
  • "updated_at": "2024-10-10T13:50:40.250+09:00",
  • "event_type": "task_completed",
  • "is_enabled": true,
  • "endpoints": [
    ]
}

通知設定取得

指定IDの通知設定を取得します。

Authorizations:
BasicAuth
path Parameters
settingId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2024-10-10T13:50:40.250+09:00",
  • "updated_at": "2024-10-10T13:50:40.250+09:00",
  • "event_type": "task_completed",
  • "is_enabled": true,
  • "endpoints": [
    ]
}

通知設定更新

通知設定を更新します。

Authorizations:
BasicAuth
path Parameters
settingId
required
string <uuid>
Request Body schema: application/json
required
event_type
required
string

通知イベントの種類

is_enabled
required
boolean

通知設定を有効にするかどうか

endpoint_ids
required
Array of strings <uuid> [ items <uuid > ]

通知先のエンドポイントIDのリスト

Responses

Request samples

Content type
application/json
{
  • "event_type": "task_completed",
  • "is_enabled": true,
  • "endpoint_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2024-10-10T13:50:40.250+09:00",
  • "updated_at": "2024-10-10T13:50:40.250+09:00",
  • "event_type": "task_completed",
  • "is_enabled": true,
  • "endpoints": [
    ]
}

通知設定部分更新

通知設定を部分的に更新します。

Authorizations:
BasicAuth
path Parameters
settingId
required
string <uuid>
Request Body schema: application/json
required
event_type
string

通知イベントの種類

is_enabled
boolean

通知設定を有効にするかどうか

endpoint_ids
Array of strings <uuid> [ items <uuid > ]

通知先のエンドポイントIDのリスト

Responses

Request samples

Content type
application/json
{
  • "event_type": "task_completed",
  • "is_enabled": true,
  • "endpoint_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2024-10-10T13:50:40.250+09:00",
  • "updated_at": "2024-10-10T13:50:40.250+09:00",
  • "event_type": "task_completed",
  • "is_enabled": true,
  • "endpoints": [
    ]
}

通知設定削除

通知設定を削除します。

Authorizations:
BasicAuth
path Parameters
settingId
required
string <uuid>

Responses

Webhook通知設定テスト

登録したWebhook通知設定に対してテスト送信を行います。

このAPIはブラウザから直接Webhook URLにテスト送信する機能です。

Authorizations:
BasicAuth
Request Body schema: application/json
required
url
required
string

テスト送信先のWebhook URL

Responses

Request samples

Content type
application/json

Response samples

Content type
application/json
{
  • "ok": true,
  • "webhook_status_code": 200,
  • "response_body": "{\"status\": \"ok\"}"
}