さくらのAppRun β APIドキュメント (1.0.0)

Download OpenAPI specification:Download

「さくらのAppRun」が提供するAPIの利用方法とサンプルを公開しております。

基本的な使い方

APIキーの発行

APIを利用するためには、認証のための「APIキー」が必要です。事前にキーを発行しておきます。
APIキーは「ユーザーID」「パスワード」に相当する「トークン」と呼ばれる認証情報で構成されています。

項目名	APIキー発行時の項目名	このドキュメント内での例
ユーザーID	アクセストークン(UUID)	01234567-89ab-cdef-0123-456789abcdef
パスワード	アクセストークンシークレット	SAMPLETOKENSAMPLETOKENSAMPLETOKENSAM

操作マニュアル

APIキー | さくらのクラウドドキュメント

入力パラメータ

APIの入力には送信先URLに対して、いくつかのヘッダーとAPIキーを送信します。

認証方式はHTTP Basic認証です。APIキーのアクセストークンをユーザーID、アクセストークンシークレットをパスワードとして指定します。

# 入力サンプル
curl -u '01234567-89ab-cdef-0123-456789abcdef:SAMPLETOKENSAMPLETOKENSAMPLETOKENSAM' \
     'https://secure.sakura.ad.jp/cloud/api/apprun/1.0/apprun/api/applications'

出力結果と応答コード（HTTPステータスコード）

APIからの結果は、「応答コード（HTTPステータスコード）」と、「JSON形式(UTF-8)の結果」として出力されます。

応答コードは、リクエストが成功したのか、失敗したのか大まかな情報を判断することができるもので、例えば失敗したときには、なぜこのような結果になったのかなど、具体的な情報は応答コードと主に返された本文を見ることで把握することができます。

結果	応答コード/status
成功（要求を受け付けた）	2xx
失敗（要求が受け付けられなかった）	4xx, 5xx

# 出力結果サンプル（レスポンスヘッダー）
HTTP/1.1 200 OK
Server: nginx
Date: Tue, 16 Nov 2021 12:39:48 GMT
Content-Type: application/json; charset=UTF-8
Content-Length: 443
Connection: keep-alive
Status: 200 OK
Pragma: no-cache
Cache-Control: no-cache
X-Sakura-Proxy-Microtime: 66245
X-Sakura-Proxy-Decode-Microtime: 62
X-Sakura-Content-Length: 443
X-Sakura-Serial: 86ab6c743f72aa5ea6f17e254fd5f803
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
X-Frame-Options: DENY
X-Sakura-Encode-Microtime: 260
Vary: Accept-Encoding

# 出力結果サンプル（レスポンスボディー）
{
  "error": {
    "code": 401,
    "message": "Login Required",
    "errors": [
      {
        "domain": "global",
        "reason": "required",
        "message": "Login Required",
        "location_type": "header",
        "location": "Authorization"
      }
    ]
  }
}

利用例

1.ユーザーの作成

AppRunの利用を開始するにはユーザーを作成します。

ユーザーとは、AppRunを利用するための独立したユーザーであり、ユーザー作成および削除による料金の発生はございません。
なお、すでにユーザーを作成済みの場合は、再度ユーザーの作成は不要です。

ユーザーを作成するには以下のような入力を行います。

# 入力サンプル
curl -u '01234567-89ab-cdef-0123-456789abcdef:SAMPLETOKENSAMPLETOKENSAMPLETOKENSAM' \
     -X POST \
     https://secure.sakura.ad.jp/cloud/api/apprun/1.0/apprun/api/user

ユーザーの作成が完了すると、

アプリケーションの作成、更新、削除
バージョンの確認、削除
トラフィック分散の確認、変更

などの操作が可能になります。

2.アプリケーションの作成、取得、更新、削除

ユーザーを作成後、アプリケーションの作成、更新、削除が可能になります。

アプリケーションを作成するには以下のような入力を行います。

# 入力サンプル
vi request_body.json
cat request_body.json
{
  "name": "Application",
  "timeout_seconds": 60,
  "port": 8080,
  "min_scale": 0,
  "max_scale": 1,
  "components": [
    {
      "name": "Component01",
      "max_cpu": "0.1",
      "max_memory": "256Mi",
      "datasource": {
        "container_registry": {
          "image": "my-app.sakuracr.jp/my-app:latest"
        }
      },
      "env": [
        {
          "key": "TARGET",
          "value": "World"
        }
      ],
      "probe": {
        "http_get": {
          "path": "/",
          "port": 8080,
          "headers": [
            {
              "name": "Custom-Header",
              "value": "Awesome"
            }
          ]
        }
      }
    }
  ]
}
curl -u '01234567-89ab-cdef-0123-456789abcdef:SAMPLETOKENSAMPLETOKENSAMPLETOKENSAM' \
     -X POST \
     -d '@request_body.json' \
     https://secure.sakura.ad.jp/cloud/api/apprun/1.0/apprun/api/applications

上記で作成したアプリケーションを取得するには以下のような入力を行います。

# 入力サンプル
curl -u '01234567-89ab-cdef-0123-456789abcdef:SAMPLETOKENSAMPLETOKENSAMPLETOKENSAM' \
     -X GET \
     https://secure.sakura.ad.jp/cloud/api/apprun/1.0/apprun/api/applications/{id}

上記で作成したアプリケーションを更新するには以下のような入力を行います。

# 入力サンプル
vi request_body.json
cat request_body.json
{
  "components": [
    {
      "name": "Component01 updated",
      "max_cpu": "0.1",
      "max_memory": "256Mi",
      "datasource": {
        "container_registry": {
          "image": "my-app.sakuracr.jp/my-app-v2:latest"
        }
      }
    }
  ],
  "all_traffic_available": true
}

curl -u '01234567-89ab-cdef-0123-456789abcdef:SAMPLETOKENSAMPLETOKENSAMPLETOKENSAM' \
     -X PATCH \
     -d '@request_body.json' \
     https://secure.sakura.ad.jp/cloud/api/apprun/1.0/apprun/api/applications/{id}

上記で作成したアプリケーションを削除するには以下のような入力を行います。

# 入力サンプル
curl -u '01234567-89ab-cdef-0123-456789abcdef:SAMPLETOKENSAMPLETOKENSAMPLETOKENSAM' \
     -X DELETE \
     https://secure.sakura.ad.jp/cloud/api/apprun/1.0/apprun/api/applications/{id}

3.バージョンの取得、削除

アプリケーションを作成、更新した際、その設定情報をバージョンとして保存します。

バージョンを取得するには以下のような入力を行います。

# 入力サンプル
curl -u '01234567-89ab-cdef-0123-456789abcdef:SAMPLETOKENSAMPLETOKENSAMPLETOKENSAM' \
     -X GET \
     https://secure.sakura.ad.jp/cloud/api/apprun/1.0/apprun/api/applications/{id}/versions/{version_id}

上記で作成したバージョンを削除するには以下のような入力を行います。

# 入力サンプル
curl -u '01234567-89ab-cdef-0123-456789abcdef:SAMPLETOKENSAMPLETOKENSAMPLETOKENSAM' \
     -X DELETE \
     https://secure.sakura.ad.jp/cloud/api/apprun/1.0/apprun/api/applications/{id}/versions/{version_id}

4.トラフィック分散の確認、変更

アプリケーションは指定のバージョンへトラフィックを分散します。

トラフィック分散を確認するには以下のような入力を行います。

# 入力サンプル
curl -u '01234567-89ab-cdef-0123-456789abcdef:SAMPLETOKENSAMPLETOKENSAMPLETOKENSAM' \
     -X GET \
     https://secure.sakura.ad.jp/cloud/api/apprun/1.0/apprun/api/applications/{id}/traffics

トラフィック分散を変更するには以下のような入力を行います。

# 入力サンプル
vi request_body.json
cat request_body.json
[
  {
    "is_latest_version": true,
    "percent": 50
  },
  {
    "version_name": "Application-861850d6-8240-7c31-9b69-80ea4466918d-1726726814",
    "percent": 50
  }
]
curl -u '01234567-89ab-cdef-0123-456789abcdef:SAMPLETOKENSAMPLETOKENSAMPLETOKENSAM' \
     -X PUT \
     https://secure.sakura.ad.jp/cloud/api/apprun/1.0/apprun/api/applications/{id}/traffics

アプリケーション

アプリケーションに関する情報

アプリケーション一覧を取得します。

さくらのAppRunのアプリケーション一覧を取得します。

query Parameters

page_num	integer >= 1 Default: 1 Example: page_num=20 表示したいページ番号
page_size	integer [ 1 .. 100 ] Default: 50 Example: page_size=10 表示したい1ページあたりのサイズ
sort_field	string Default: "created_at" Example: sort_field=created_at ソートしたいフィールド名
sort_order	string Default: "desc" Enum: "asc" "desc" Example: sort_order=asc ソート順（昇順、降順）

Responses

Response samples

200
400
401
403
500

Content type

application/json

{"meta": {"page_num": 1,
"page_size": 100,
"object_total": 1000,
"sort_field": "created_at",
"sort_order": "asc"
},
"data": [{"id": "u8FXIJ2LVM3wXVyzOEi",
"name": "アプリケーション1",
"status": "Success",
"public_url": "https://fq1I4vpQkN1YiGp.apprun.sakura.ne.jp",
"created_at": "2019-08-24T14:15:22Z"
}
]
}

アプリケーションを作成します。

さくらのAppRunにアプリケーションを作成します。

Request Body schema: application/json

作成するアプリケーションの情報を入力します。

name required	string [ 1 .. 255 ] characters アプリケーション名
timeout_seconds required	integer [ 1 .. 300 ] Default: 60 アプリケーションの公開URLにアクセスして、インスタンスが起動してからレスポンスが返るまでの時間制限
port required	integer [ 1 .. 65535 ] アプリケーションがリクエストを待ち受けるポート番号
min_scale required	integer [ 0 .. 0 ] Default: 0 アプリケーション全体の最小スケール数
max_scale required	integer [ 1 .. 10 ] Default: 10 アプリケーション全体の最大スケール数
required	Array of objects アプリケーションのコンポーネント情報

Responses

Request samples

Payload

Content type

application/json

{"name": "アプリケーション1",
"timeout_seconds": 60,
"port": 8080,
"min_scale": 0,
"max_scale": 2,
"components": [{"name": "コンポーネント1",
"max_cpu": "0.1",
"max_memory": "256Mi",
"datasource": {"container_registry": {"image": "apprun-example.sakuracr.jp/helloworld:latest",
"server": "apprun-example.sakuracr.jp",
"username": "apprun",
"password": "apprun"
}
},
"env": [{"key": "MY_ENV",
"value": "my_value"
}
],
"probe": {"http_get": {"path": "/healthz",
"port": 8080,
"headers": [{"name": "Custom-Header",
"value": "Awesome"
}
]
}
}
}
]
}

Response samples

Content type

application/json

{"id": "u8FXIJ2LVM3wXVyzOEi",
"name": "アプリケーション1",
"timeout_seconds": 60,
"port": 8080,
"min_scale": 0,
"max_scale": 2,
"components": [{"name": "コンポーネント1",
"max_cpu": "0.1",
"max_memory": "256Mi",
"datasource": {"container_registry": {"image": "apprun-example.sakuracr.jp/helloworld:latest",
"server": "apprun-example.sakuracr.jp",
"username": "apprun"
}
},
"env": [{"key": "MY_ENV",
"value": "my_value"
}
],
"probe": {"http_get": {"path": "/healthz",
"port": 8080,
"headers": [{"name": "Custom-Header",
"value": "Awesome"
}
]
}
}
}
],
"status": "Success",
"public_url": "https://fq1I4vpQkN1YiGp.apprun.sakura.ne.jp",
"created_at": "2019-08-24T14:15:22Z"
}

アプリケーション詳細を取得します。

さくらのAppRunのアプリケーション詳細を取得します。

path Parameters

id

required

string

Responses

Response samples

Content type

application/json

{"id": "u8FXIJ2LVM3wXVyzOEi",
"name": "アプリケーション1",
"timeout_seconds": 60,
"port": 8080,
"min_scale": 0,
"max_scale": 2,
"components": [{"name": "コンポーネント1",
"max_cpu": "0.1",
"max_memory": "256Mi",
"datasource": {"container_registry": {"image": "apprun-example.sakuracr.jp/helloworld:latest",
"server": "apprun-example.sakuracr.jp",
"username": "apprun"
}
},
"env": [{"key": "MY_ENV",
"value": "my_value"
}
],
"probe": {"http_get": {"path": "/healthz",
"port": 8080,
"headers": [{"name": "Custom-Header",
"value": "Awesome"
}
]
}
}
}
],
"status": "Success",
"public_url": "https://fq1I4vpQkN1YiGp.apprun.sakura.ne.jp",
"created_at": "2019-08-24T14:15:22Z"
}

アプリケーションを部分的に変更します。

さくらのAppRunのアプリケーションを部分的に変更します。

path Parameters

id

required

string

Request Body schema: application/json

部分的に変更するアプリケーションの情報を入力します。

name	string [ 1 .. 255 ] characters アプリケーション名
timeout_seconds	integer [ 1 .. 300 ] アプリケーションの公開URLにアクセスして、インスタンスが起動してからレスポンスが返るまでの時間制限
port	integer [ 1 .. 65535 ] アプリケーションがリクエストを待ち受けるポート番号
min_scale	integer [ 0 .. 0 ] アプリケーション全体の最小スケール数
max_scale	integer [ 1 .. 10 ] アプリケーション全体の最大スケール数
	Array of objects アプリケーションのコンポーネント情報
all_traffic_available	boolean アプリケーションを最新のバージョンにすべてのトラフィックを割り当てるかどうか

Responses

Request samples

Payload

Content type

application/json

{"name": "アプリケーション1",
"timeout_seconds": 60,
"port": 8080,
"min_scale": 0,
"max_scale": 2,
"components": [{"name": "コンポーネント1",
"max_cpu": "0.1",
"max_memory": "256Mi",
"datasource": {"container_registry": {"image": "apprun-example.sakuracr.jp/helloworld:latest",
"server": "apprun-example.sakuracr.jp",
"username": "apprun",
"password": "apprun"
}
},
"env": [{"key": "MY_ENV",
"value": "my_value"
}
],
"probe": {"http_get": {"path": "/healthz",
"port": 8080,
"headers": [{"name": "Custom-Header",
"value": "Awesome"
}
]
}
}
}
],
"all_traffic_available": true
}

Response samples

Content type

application/json

{"id": "u8FXIJ2LVM3wXVyzOEi",
"name": "アプリケーション1",
"timeout_seconds": 60,
"port": 8080,
"min_scale": 0,
"max_scale": 2,
"components": [{"name": "コンポーネント1",
"max_cpu": "0.1",
"max_memory": "256Mi",
"datasource": {"container_registry": {"image": "apprun-example.sakuracr.jp/helloworld:latest",
"server": "apprun-example.sakuracr.jp",
"username": "apprun"
}
},
"env": [{"key": "MY_ENV",
"value": "my_value"
}
],
"probe": {"http_get": {"path": "/healthz",
"port": 8080,
"headers": [{"name": "Custom-Header",
"value": "Awesome"
}
]
}
}
}
],
"status": "Success",
"public_url": "https://fq1I4vpQkN1YiGp.apprun.sakura.ne.jp",
"updated_at": "2019-08-24T14:15:22Z"
}

アプリケーションを削除します。

さくらのAppRunのアプリケーションを削除します。

path Parameters

id

required

string

Responses

Response samples

400
401
403
404
500

Content type

application/json

{"error": {"code": 401,
"message": "Login Required",
"errors": [{"domain": "global",
"reason": "required",
"message": "Login Required",
"location_type": "header",
"location": "Authorization"
}
]
}
}

アプリケーションステータスを取得します。

さくらのAppRunのアプリケーションステータスを取得します。

path Parameters

id

required

string

Responses

Response samples

Content type

application/json

{"status": "Success",
"message": "Failed to authenticate with the registry"
}

ユーザー

getUser

ログイン中のユーザー情報を取得します。

Responses

Response samples

401
403
404
500

Content type

application/json

{"error": {"code": 401,
"message": "Login Required",
"errors": [{"domain": "global",
"reason": "required",
"message": "Login Required",
"location_type": "header",
"location": "Authorization"
}
]
}
}

postUser

さくらのAppRunにサインアップします。

Responses

Response samples

401
403
409
500

Content type

application/json

{"error": {"code": 401,
"message": "Login Required",
"errors": [{"domain": "global",
"reason": "required",
"message": "Login Required",
"location_type": "header",
"location": "Authorization"
}
]
}
}

トラフィック

アプリケーショントラフィック分散を取得します。

さくらのAppRunのアプリケーショントラフィック分散を取得します。

path Parameters

id

required

string

Responses

Response samples

Content type

application/json

{"meta": null,
"data": [{"version_name": "Version1",
"is_latest_version": true,
"percent": 100
}
]
}

アプリケーショントラフィック分散を変更します。

さくらのAppRunのアプリケーショントラフィック分散を変更します。

path Parameters

id

required

string

Request Body schema: application/json

トラフィック分散の割合を入力します。 version_nameまたはis_latest_versionのどちらかを指定して何％の割合でトラフィックを転送するかを入力します。

Array

version_name	string バージョン名
is_latest_version	boolean 最新バージョンかどうか
percent	integer トラフィック分散の割合

Responses

Request samples

Payload

Content type

application/json

[{"version_name": "Version1",
"is_latest_version": true,
"percent": 0
}
]

Response samples

Content type

application/json

{"meta": null,
"data": [{"version_name": "Version1",
"is_latest_version": true,
"percent": 100
}
]
}

バージョン

アプリケーションバージョン一覧を取得します。

さくらのAppRunのアプリケーションバージョン一覧を取得します。

path Parameters

id

required

string

query Parameters

page_num	integer >= 1 Default: 1 Example: page_num=20 表示したいページ番号
page_size	integer [ 1 .. 100 ] Default: 50 Example: page_size=10 表示したい1ページあたりのサイズ
sort_field	string Default: "created_at" Example: sort_field=created_at ソートしたいフィールド名
sort_order	string Default: "desc" Enum: "asc" "desc" Example: sort_order=asc ソート順（昇順、降順）

Responses

Response samples

Content type

application/json

{"meta": {"page_num": 1,
"page_size": 100,
"object_total": 1000,
"sort_field": "created_at",
"sort_order": "asc"
},
"data": [{"id": "BIi7jHVWGjg7NaxcK",
"name": "version-001",
"status": "Success",
"created_at": "2019-08-24T14:15:22Z"
}
]
}

アプリケーションバージョン詳細を取得します。

さくらのAppRunのアプリケーションバージョン詳細を取得します。

path Parameters

id required	string
version_id required	string

Responses

Response samples

Content type

application/json

{"id": "BIi7jHVWGjg7NaxcK",
"name": "version-001",
"status": "Success",
"timeout_seconds": 60,
"port": 8080,
"min_scale": 0,
"max_scale": 2,
"components": [{"name": "コンポーネント1",
"max_cpu": "0.1",
"max_memory": "256Mi",
"datasource": {"container_registry": {"image": "apprun-example.sakuracr.jp/helloworld:latest",
"server": "apprun-example.sakuracr.jp",
"username": "apprun"
}
},
"env": [{"key": "MY_ENV",
"value": "my_value"
}
],
"probe": {"http_get": {"path": "/healthz",
"port": 8080,
"headers": [{"name": "Custom-Header",
"value": "Awesome"
}
]
}
}
}
],
"created_at": "2019-08-24T14:15:22Z"
}

アプリケーションバージョンを削除します。

さくらのAppRunのアプリケーションバージョンを削除します。

path Parameters

id required	string
version_id required	string

Responses

Response samples

400
401
403
404
500

Content type

application/json

{"error": {"code": 401,
"message": "Login Required",
"errors": [{"domain": "global",
"reason": "required",
"message": "Login Required",
"location_type": "header",
"location": "Authorization"
}
]
}
}