Runbook callの外部関数リファレンス

目次

[更新: 2026年5月18日]

ワークフロー（Runbook）では、ネットワークやシステムを扱う 外部関数 を call のステップで呼び出すことができます。ここでは、callから呼び出せる外部関数についてリファレンス形式で説明します。

参考

Runbookでの記述については、構文リファレンスの「call」の項目を参照してください。

外部関数について

外部関数を呼び出す際には、関数名を指定する call のほか、引数に値を指定する args と、戻り値の変数を指定する result という3つの項目を記述します。

callで指定する関数は、扱う対象によって次のようにグループ分けできます。

• feed

• http

• sakuraCloud

• apprun

• sys

それぞれの関数では引数名とその型が決まっており、argsでその値を指定します。

resultでは、関数からの戻り値を格納する変数を指定します。関数ごとに戻り値の型も決まっています。この変数はその後のステップで使用できます。

以降で、外部関数をグループごとにアルファベット順で説明します。

feedグループ

feedグループの外部関数では、XML形式のAtomフィードを扱います。

feed.parse関数

XML形式のデータ（Atomフィード）を解析して、フィードのタイトルとその中に含まれるエントリー（項目）をJSON形式のデータに変換します。構文は次のようになります。

call: feed.parse
args:
  xml: <xml>
result: <object>

次の引数を受け取ります。

引数	説明
xml	解析するXML形式のデータ

実行例は以下のようになります。

steps:
  get:
    call: http.get
    args:
      url: ${"https://sample-feeds.rowanmanning.com/examples/64968fb0e3685ef07a3e2a27b8d64c01/feed.xml"}
      timeout: 10
      headers:
        "Accept": "application/rss+xml"
    result: feedData
  parse:
    call: feed.parse
    args:
      xml: ${feedData.body}
    result: parsedFeed
  done:
    return: ${parsedFeed.title + " > " + parsedFeed.entries[0].title + " @ " + parsedFeed.entries[0].updated}
    # return "Example Feed > Atom-Powered Robots Run Amok @ 2003-12-13T18:30:02.000Z"

httpグループ

httpグループの外部関数では、ネットワークを介したHTTPリクエストを実行します。

http.get関数

指定されたURLにHTTP GETリクエストを送信します。構文は次のようになります。

call: http.get
args:
  url: <string>
  timeout?: <number>
  headers?:
    <string>: <string>
    ...
  query?:
    <string>: <string>
    ...
result: <object>

次の引数を受け取ります（他のhttpグループの関数の引数と違ってbodyがないことに注意）。

引数	型	説明
url	string	リクエストを送信するURL
timeout	number	リクエストのタイムアウト時間（秒）。最小値は5、最大値は180。省略可。省略時は60秒
headers	object	リクエストヘッダー。省略可
query	object	クエリパラメーター。省略可

戻り値はHTTPリクエストの実行結果で、その型は次の2つのキーからなる連想配列（マップ）です。

キー	説明
status	HTTPステータスコード
body	レスポンスボディー

実行例は以下のようになります。

steps:
  get:
    call: http.get
    args:
      url: ${"https://httpbin.org/get"}
      timeout: 10
      headers:
        "Content-Type": application/json
      query:
        "hl": "ja"
        "q": "q"
    result: response
  done:
    return: ${response}

http.post関数

指定されたURLにHTTP POSTリクエストを送信します。構文は次のようになります。

call: http.post
args:
  url: <string>
  timeout?: <number>
  headers?:
    <string>: <string>
    ...
  query?:
    <string>: <string>
    ...
  body?:
    <string>: <any>
    ...
result: <object>

次の引数を受け取ります。

引数	型	説明
url	string	リクエストを送信するURL
timeout	number	リクエストのタイムアウト時間（秒）。最小値は5、最大値は180。省略可。省略時は60
headers	object	リクエストヘッダー。省略可
query	object	クエリパラメーター。省略可
body	object	リクエストボディー。省略可

戻り値はHTTPリクエストの実行結果で、その型は次の2つのキーからなる連想配列（マップ）です。

キー	説明
status	HTTPステータスコード
body	レスポンスボディー

実行例は以下のようになります。

steps:
  post:
    call: http.post
    args:
      url: ${"https://httpbin.org/post"}
      timeout: 10
      headers:
        "Content-Type": application/json
      body:
        "key": "value"
    result: response
  done:
    return: ${response}

http.put関数

指定されたURLにHTTP PUTリクエストを送信します。構文は次のようになります。

call: http.put
args:
  url: <string>
  timeout?: <number>
  headers?:
    <string>: <string>
    ...
  query?:
    <string>: <string>
    ...
  body?:
    <string>: <any>
    ...
result: <object>

次の引数を受け取ります。

引数	型	説明
url	string	リクエストを送信するURL
timeout	number	リクエストのタイムアウト時間（秒）。最小値は5、最大値は180。省略可。省略時は60
headers	object	リクエストヘッダー。省略可
query	object	クエリパラメーター。省略可
body	object	リクエストボディー。省略可

戻り値はHTTPリクエストの実行結果で、その型は次の2つのキーからなる連想配列（マップ）です。

キー	説明
status	HTTPステータスコード
body	レスポンスボディー

実行例は以下のようになります。

steps:
  put:
    call: http.put
    args:
      url: ${"https://httpbin.org/put"}
      timeout: 10
      headers:
        "Content-Type": application/json
      body:
        "key": "value"
    result: response
  done:
    return: ${response}

http.delete関数

指定されたURLにHTTP DELETEリクエストを送信します。構文は次のようになります。

call: http.delete
args:
  url: <string>
  timeout?: <number>
  headers?:
    <string>: <string>
    ...
  query?:
    <string>: <string>
    ...
  body?:
    <string>: <any>
    ...
result: <object>

次の引数を受け取ります（DELETEリクエストでbodyを送信することはまれですが許可されています）。

引数	型	説明
url	string	リクエストを送信するURL
timeout	number	リクエストのタイムアウト時間（秒）。最小値は5、最大値は180。省略可。省略時は60
headers	object	リクエストヘッダー。省略可
query	object	クエリパラメーター。省略可
body	object	リクエストボディー。省略可

戻り値はHTTPリクエストの実行結果で、その型は次の2つのキーからなる連想配列（マップ）です。

キー	説明
status	HTTPステータスコード
body	レスポンスボディー

実行例は以下のようになります。

steps:
  delete:
    call: http.delete
    args:
      url: ${"https://httpbin.org/delete"}
      timeout: 10
      headers:
        "Content-Type": application/json
      body:
        "key": "value"
    result: response
  done:
    return: ${response}

http.patch関数

指定されたURLにHTTP PATCHリクエストを送信します。構文は次のようになります。

call: http.patch
args:
  url: <string>
  timeout?: <number>
  headers?:
    <string>: <string>
    ...
  query?:
    <string>: <string>
    ...
  body?:
    <string>: <any>
    ...
result: <object>

次の引数を受け取ります。

引数	型	説明
url	string	リクエストを送信するURL
timeout	number	リクエストのタイムアウト時間（秒）。最小値は5、最大値は180。省略可。省略時は60
headers	object	リクエストヘッダー。省略可
query	object	クエリパラメーター。省略可
body	object	リクエストボディー。省略可

戻り値はHTTPリクエストの実行結果で、その型は次の2つのキーからなる連想配列（マップ）です。

キー	説明
status	HTTPステータスコード
body	レスポンスボディー

実行例は以下のようになります。

steps:
  patch:
    call: http.patch
    args:
      url: ${"https://httpbin.org/patch"}
      timeout: 10
      headers:
        "Content-Type": application/json
      body:
        "key": "value"
    result: response
  done:
    return: ${response}

http.request関数

任意のHTTPリクエストを送信する汎用的な関数です。

ヒント

ほとんどの場合、http.getやhttp.postといった特定の関数を使う方が簡単です。

構文は次のようになります。

call: http.get
args:
  method: <string>
  url: <string>
  timeout?: <number>
  headers?:
    <string>: <string>
    ...
  query?:
    <string>: <string>
    ...
  body?:
    <string>: <any>
    ...
result: <object>

次の引数を受け取ります（他のhttpグループの関数の引数にmethodが追加されることに注意）。

引数	型	説明
method	string	リクエストメソッド
url	string	リクエストを送信するURL
timeout	number	リクエストのタイムアウト時間（秒）。最小値は5、最大値は180。省略可。省略時は60
headers	object	リクエストヘッダー。省略可
query	object	クエリパラメーター。省略可
body	object	リクエストボディー。省略可

戻り値はHTTPリクエストの実行結果で、その型は次の2つのキーからなる連想配列（マップ）です。

キー	説明
status	HTTPステータスコード
body	レスポンスボディー

実行例は以下のようになります。

steps:
  request:
    call: http.request
    args:
      method: GET
      url: ${"https://httpbin.org/get"}
      timeout: 10
      headers:
        "Content-Type": application/json
      query:
        "hl": "ja"
        "q": "q"
    result: response
  done:
    return: ${response}

sakuraCloudグループ

sakuraCloudグループの外部関数では、さくらのクラウドの任意のAPIを呼び出して操作できます。

参考

さくらのクラウドのAPIについては、マニュアルの「API」および「APIポータル」を参照してください。

特に「サーバ」に関しては、個別の関数で一覧取得・状態取得・起動・停止・その他の操作ができます。

参考

「サーバ」関連のAPIについては、マニュアル「API」で「サーバ関連API」を参照してください。

このグループの関数を実行するには、呼び出すサービスの権限が適切に付与されたサービスプリンシパルが、適切にワークフローと関連付けられている必要があります。

参考

サービスプリンシパルについてはマニュアルの「サービスプリンシパル」を、ワークフローとの関連づけは「ワークフロー作成画面を操作する」を参照してください。

sakuraCloud.request関数

さくらクラウドのAPIを呼び出します。

構文は次のようになります。

call: sakuraCloud.request
args:
  endpoint: <string>
  method: <string>
  timeout?: <number>
  headers?:
    <string>: <string>
    ...
  query?:
    <string>: <string>
    ...
  body?:
    <string>: <any>
    ...
result: <object>

次の引数を受け取ります。

引数	型	説明
endpoint	string	APIのエンドポイントURI
method	string	リクエストメソッド
timeout	number	リクエストのタイムアウト時間（秒）。最小値は5、最大値は180。省略可。省略時は60
headers	object	リクエストヘッダー。省略可
query	object	クエリパラメーター。省略可
body	object	リクエストボディー。省略可

APIのエンドポイントURI（endpoint）には、例えば次のような文字列を指定します。

https://secure.sakura.ad.jp/cloud/zone/tk1b/api/workflow/1.0/workflows/

戻り値はAPIリクエストの結果で、その型は次の2つのキーからなる連想配列（マップ）です。

キー	説明
status	HTTPステータスコード
body	レスポンスボディー

実行例は以下のようになります。

steps:
  getWorkflows:
    call: sakuraCloud.request
    args:
      endpoint: https://secure.sakura.ad.jp/cloud/zone/tk1b/api/workflow/1.0/workflows/
      method: GET
      headers:
        Accept: "application/json"
      timeout: 30
    result: response
  done:
    return: ${json.decode(response.body)}

sakuraCloud.secret関数

さくらのクラウドのシークレットマネージャー保管庫にあるシークレット情報の取得をすることができます。事前にKMSキーとシークレット保管庫の作成が必要です。

参考

詳しくはマニュアルの「シークレットマネージャ」を参照してください。

構文は次のようになります。

call: sakuraCloud.secret
args:
  vaultResourceId: <number>
  secretName: <string>
  secretVersion?: <string>
result: <string>

次の引数を受け取ります。

引数	型	説明
vaultResourceId	number	シークレット保管庫のリソースID
secretName	string	取得するシークレット名
secretVersion	string	取得するシークレットのバージョン。省略可

戻り値の型は string です。シークレットの値を返します。

実行例は以下のようになります。

steps:
  getSecret:
    call: sakuraCloud.secret
    args:
      vaultResourceId: 123456789012 # 任意のシークレット保管庫のリソースIDに変更
      secretName: "your-secret-name" # 任意のシークレット名に変更
    result: secretValue

sakuraCloud.listServers関数

指定された条件で「サーバ」の一覧を取得します。

構文は次のようになります。

call: sakuraCloud.listServers
args:
  zone: <string>
result: <object>

次の引数を受け取ります。

引数	型	説明
zone	string	サーバが存在するゾーン名

戻り値はAPIリクエストの結果で、その型は次の2つのキーからなる連想配列（マップ）です。

キー	説明
status	HTTPステータスコード
body	レスポンスボディー

実行例は以下のようになります。

steps:
  listServers:
    call: sakuraCloud.listServers
    args:
      zone: is1a # 任意のゾーンに変更
    result: response
  done:
    return: ${response}

sakuraCloud.serverStatus関数

指定された「サーバ」の起動状態を取得します。

構文は次のようになります。

call: sakuraCloud.serverStatus
args:
  zone: <string>
  serverId: <number>
result: <object>

次の引数を受け取ります。

引数	型	説明
zone	string	サーバが存在するゾーン名
serverId	number	状態を取得するサーバのID

戻り値はAPIリクエストの結果で、その型は次の2つのキーからなる連想配列（マップ）です。

キー	説明
status	HTTPステータスコード
body	レスポンスボディー

実行例は以下のようになります。

steps:
  serverStatus:
    call: sakuraCloud.serverStatus
    args:
      zone: is1a # 任意のゾーンに変更
      serverId: 123456789012 # 任意のサーバIDに変更
    result: response
  done:
    return: ${response}

sakuraCloud.startServer関数

指定された「サーバ」を起動します。

構文は次のようになります。

call: sakuraCloud.startServer
args:
  zone: <string>
  serverId: <number>
result: <object>

次の引数を受け取ります。

引数	型	説明
zone	string	サーバが存在するゾーン名
serverId	number	起動するサーバのID

戻り値はAPIリクエストの結果で、その型は次の2つのキーからなる連想配列（マップ）です。

キー	説明
status	HTTPステータスコード
body	レスポンスボディー

実行例は以下のようになります。

steps:
  startServer:
    call: sakuraCloud.startServer
    args:
      zone: is1a # 任意のゾーンに変更
      serverId: 123456789012 # 任意のサーバIDに変更
    result: response
  done:
    return: ${response}

sakuraCloud.stopServer関数

指定された「サーバ」を停止します。

構文は次のようになります。

call: sakuraCloud.stopServer
args:
  zone: <string>
  serverId: <number>
result: <object>

次の引数を受け取ります。

引数	型	説明
zone	string	サーバが存在するゾーン名
serverId	number	停止するサーバのID

戻り値はAPIリクエストの結果で、その型は次の2つのキーからなる連想配列（マップ）です。

キー	説明
status	HTTPステータスコード
body	レスポンスボディー

実行例は以下のようになります。

steps:
  stopServer:
    call: sakuraCloud.stopServer
    args:
      zone: is1a # 任意のゾーンに変更
      serverId: 123456789012 # 任意のサーバIDに変更
    result: response
  done:
    return: ${response}

sakuraCloud.server関数

さくらのクラウドの「サーバ」に関連したAPIを操作します。構文は次のようになります。

call: sakuraCloud.server
args:
  path: <string>
  method: <string>
  zone: <string>
  serverId?: <number>
  timeout?: <number>
  headers?:
    <string>: <string>
    ...
  query?:
    <string>: <string>
    ...
  body?:
    <string>: <any>
    ...
result: <object>

次の引数を受け取ります。

引数	型	説明
path	string	APIのエンドポイントURI
method	string	リクエストメソッド
zone	string	サーバが存在するゾーン名
serverId	number	操作するサーバのID。pathに直接値を埋め込むことも可能
timeout	number	リクエストのタイムアウト時間（秒）。最小値は5、最大値は180。省略可。省略時は60
headers	object	リクエストヘッダー。省略可
query	object	クエリパラメーター。省略可
body	object	リクエストボディー。省略可

APIのエンドポイントURI（path）には、例えば次のような文字列を指定します。

/:serverId/power

参考

指定できるエンドポイントURIについては、さくらのクラウドのAPIドキュメントで「サーバ関連API」を参照してください。

戻り値はAPIリクエストの結果で、その型は次の2つのキーからなる連想配列（マップ）です。

キー	説明
status	HTTPステータスコード
body	レスポンスボディー

実行例は以下のようになります。

steps:
  getServer:
    call: sakuraCloud.server
    args:
      path: /123456789012/power # :serverIdまたは任意のサーバIDを指定
      method: GET
      zone: is1a # 任意のゾーンに変更
    result: response
  done:
    return: ${response}

apprunグループ

apprunグループの外部関数では、さくらのクラウドの「AppRun共有型」アプライアンスのAPIを呼び出して実行します。

参考

AppRunについては、マニュアルの「AppRun」を参照してください。また、APIの詳細は、さくらのクラウドAPIポータルの「AppRun共用型 APIドキュメント」を参照してください。

このグループの関数を実行するには、AppRunの権限が付与されてたサービスプリンシパルが、適切にワークフローと関連付けられている必要があります。

参考

サービスプリンシパルについてはマニュアルの「サービスプリンシパル」を、ワークフローとの関連づけは「ワークフロー作成画面を操作する」を参照してください。

apprun.create関数

アプリケーションを起動します。「コンテナレジストリ」にイメージがプッシュされている必要があります。

参考

AppRunのマニュアル「クイックスタート」の「コンテナレジストリでの作業」を参照してください。

構文は次のようになります。

call: apprun.create
args:
  polling?: <boolean>
  pollingInterval?: <number>
  name: <string>
  timeout_seconds?: <number>
  port: <number>
  min_scale?: <number>
  max_scale?: <number>
  components:
    - name: <string>
      max_cpu: <string>
      max_memory: <string>
      deploy_source:
        container_registry:
          image: <string>
          server: <string>
          username: <string>
          password: <string>
    - ...
result: <object>

次の引数を受け取ります。

引数	型	説明
polling	boolean	作成したアプリがHealthyになるまで待つかどうか。省略可。省略時はtrue（待つ）
pollingInterval	number	最小の待ち時間（秒）。指数バックオフで増加。最小値は2、最大値は10。省略可。省略時は5
name	string	アプリケーション名（必須）
timeout_seconds	number	タイムアウト（秒）。省略可。省略時は60
port	number	公開ポート番号（必須）
min_scale	number	最小スケール数。省略可。省略時は0
max_scale	number	最大スケール数。省略可。省略時は10
components[]	array	コンポーネント定義（必須）

コンポーネント定義（components）は、次の要素を持ちます。

引数	型	説明
name	string	コンポーネント名（必須）
max_cpu	string	割り当てCPU（必須）
max_memory	string	割り当てメモリ（必須）
deploy_source	object	デプロイ元情報（必須）

デプロイ元情報（components.deploy_source）は、次の情報を持ちます。

引数	型	説明
container_registry	object	コンテナレジストリ情報（必須）

コンテナレジストリ情報（components.deploy_source.container_registry）は、次の要素を持ちます。

引数	型	説明
image	string	イメージ名（必須）
server	string	レジストリサーバー
username	string	レジストリユーザー名
password	string	レジストリパスワード

参考

詳細は、さくらのクラウドAPIポータルの「AppRun共用型 APIドキュメント」で「アプリケーションを作成します。」も参照してください。

戻り値の型は、キーを string 型、値を any 型とする連想配列（object）です。AppRun APIのレスポンスのボディー（JSON）をそのまま返します。

実行例は以下のようになります。

steps:
  createApp:
    call: apprun.create
    args:
      name: "my-app"
      timeout_seconds: 60
      port: 8080
      min_scale: 0
      max_scale: 10
      components:
        - name: "my-component"
          max_cpu: "0.5"
          max_memory: "1Gi"
          deploy_source:
            container_registry:
              image: "xxx.sakuracr.jp/my-app:latest"
              server: "xxx.sakuracr.jp"
              username: "xxx"
              password: "xxx"
    result: response
  done:
    return: ${response}

apprun.delete関数

アプリケーションを削除します。構文は次のようになります。

call: apprun.delete
args:
  appId: <string>
result: <object>

次の引数を受け取ります。

引数	型	説明
appId	string	削除するアプリケーションのID

参考

詳細は、さくらのクラウドAPIポータルの「AppRun共用型 APIドキュメント」で「アプリケーションを削除します。」も参照してください。

戻り値はAPIリクエストの結果で、その型は次の2つのキーからなる連想配列（マップ）です。

キー	説明
status	HTTPステータスコード
body	レスポンスボディー

実行例は以下のようになります。

steps:
  deleteApp:
    call: apprun.delete
    args:
      appId: "your-app-id" # 削除するアプリケーションIDに変更
    result: response
  done:
    return: ${response}

apprun.request関数

さくらのAppRunのAPIを呼び出します。構文は次のようになります。

call: apprun.request
args:
  path: <string>
  method: <string>
  timeout?: <number>
  headers?:
    <string>: <string>
    ...
  query?
    <string>: <string>
    ...
  body?
    <string>: <any>
    ...
result: <object>

次の引数を受け取ります。

引数	型	説明
path	string	APIのエンドポイントURI
method	string	リクエストメソッド
timeout	number	リクエストのタイムアウト時間（秒）。最小値は5、最大値は180。省略可。省略時は60
headers	object	リクエストヘッダー。省略可
query	object	クエリパラメーター。省略可
body	object	リクエストボディー。省略可

APIのエンドポイントURI（path）には、例えば次のような文字列を指定します。

/applications

参考

詳細は、さくらのクラウドAPIポータルの「AppRun共用型 APIドキュメント」を参照してください。

戻り値はAPIリクエストの結果で、その型は次の2つのキーからなる連想配列（マップ）です。

キー	説明
status	HTTPステータスコード
body	レスポンスボディー

実行例は以下のようになります。

steps:
  request:
    call: apprun.request
    args:
      path: "/applications"
      method: GET
    result: response
  done:
    return: ${response}

sysグループ

sysグループの外部関数では、主にシステム時計に関連した処理を実施します。

sys.sleep関数

指定した秒数分、実行を一時停止します。構文は次のようになります。

call: sys.sleep
args:
  seconds: <number>

次の引数を受け取ります。

引数	型	説明
seconds	number	実行を一時停止する秒数を指定する。0以下の数が指定された場合は即座に終了する

実行例は以下のようになります。

meta:
  description: 秒数ループ
steps:
  seconds:
    for:
      in: '${array.range(10)}'
      as: i
      steps:
        push:
          assign:
            message: "loop ${i}"
        sleep:
          call: sys.sleep
          args:
            seconds: 1

sys.sleepUntil関数

指定された時間まで待機します。構文は次のようになります。

call: sys.sleepUntil
args:
  date: <string>

次の引数を受け取ります。

引数	型	説明
date	string	実行を再開する日時をISO 8601フォーマットで指定する。実行時のサーバー時刻で、最大1年後まで設定できる

実行例は以下のようになります。

meta:
  description: 時間指定待機
steps:
  set:
    assign:
      setDate: ${"2030-01-01T00:00:00+09:00"} # 任意の未来の時間に変更
  sleepUntil:
    call: sys.sleepUntil
    args:
      date: ${setDate}
  done:
    return: "done"