Script

最終更新: 2026年7月23日

服屋のショッピングモールを運営していると考えてみてください。商品を登録するたびに、魅力的な詳細説明を一つひとつ書くのは手間のかかる作業です。そこで、商品名とキーワードを入れるだけで、AI が詳細説明を代わりに書いてくれるようにしたいと思います。ところが、その AI 文章作成サービスを呼ぶには、秘密の鍵(access token、外部のサービスが「料金を払ったユーザーかどうか」を確認するための鍵)が必要です。この鍵を、お客さんが見るウェブサイト(ブラウザ)に入れておくと、誰でも取り出して見られるので漏れてしまいます。漏れた鍵で他人がこのサービスを勝手に使い、その料金がこちらに請求されることもあります。

そこで、鍵をお客さんの目に触れない場所に隠したまま、ウェブサイトの代わりに AI を呼んで、その結果を商品に埋めてくれる何かが必要です。Script がそれです。Script は「この鍵で AI を呼び、受け取った文章をこの商品の詳細説明に入れて」のように、やることを順番に書いておくものです。コードではなく、決められた様式(JSON、項目と値を波かっこで書くデータの表記方法)で書きます。ウェブサイトは、この Script をインターネットから呼ぶだけでよく、鍵は Script の中に隠されていて、お客さんには見えません。

あらかじめ書いておいたレシピを厨房に貼っておくことにたとえられます。お客さんがそのメニューを注文すると(ウェブサイトが Script を呼ぶと)、厨房(WEEGLOO)がレシピに書かれた順番どおりに作り、出来上がった料理を出してくれます。店主はレシピを書いて貼っておいただけで、注文が入るたびに自分で料理をするわけではありません。このページでは、Script が何であり、どんな形をしているのか、呼ぶと何を返すのかを見たうえで、服屋の「商品説明の入力」Script を例に、その形を確認します。最後に、この Script を、商品が登録されるときにひとりでに実行されるようつなぐ方法も見ます。

Script が代わりにしてくれること

商品説明を一つ埋めるという作業にも、裏側でやるべきことはいくつもあります。呼ぶ側に権限があるかを確認し、送られた値が正しいかを検査し、隠しておいた鍵で外部の AI サービスを呼び、受け取った結果を望みの場所(商品の詳細説明)に入れ、応答を返します。以前は、こうした作業をこなす中間のプログラムを自分で作り、サーバーに載せて管理しなければなりませんでした。Script は、これらの作業をコードなしで一か所に書いておいて代わりに行わせることを目指しています。

  • 一つの Script は一つの呼び出し窓口です。 ウェブサイトがインターネットから呼べる窓口一つが Script 一つです。呼ぶときに使う方式(method)で、どの Script を実行するかを見分けます。
  • やることは上から下へ並べます。 Script の中には、実行する動作を順番に書きます。上から順に実行され、前の動作の結果を次の動作が受け継ぎます。
  • 決められた動作を選んで組み合わせます。 どんなコードでも入れられるわけではなく、あらかじめ用意された動作(リソースの作成・読み取り・修正・削除、外部サービスの呼び出し、値の保持、条件チェック、繰り返しなど)を選んで並べます。

何をするかを書いておく定義

Script 一つは、四つのことを定めた「定義」で成り立ちます。

  • 呼ぶ方式(method): この Script を呼ぶときに使う方式です。Get・Post・Put・Patch・Delete のいずれかで、呼ぶときにこの値でどの Script かを見分けます。
  • 実行の場所(executionMode): 呼んだその場ですぐに実行するか(Sync)、裏側で実行するか(Async)です。下の 即時実行とバックグラウンド実行 で扱います。
  • やること(statements): 上から下へ実行する動作の一覧です。少なくとも一つは必要です。
  • 入力チェック(payloadSchema、任意): 呼ぶときに一緒に送る入力を、実行前に確認するための形式です。定めておくと、形式に合わない入力は実行せずに差し戻します。

服屋の「商品説明の入力」Script を例に見ていきます。この Script が扱うのは、商品名とキーワードが入った商品一つです。ウェブサイトから渡される入力(後で見る自動実行のときは、登録された商品がそのまま渡されます)は、このような形です。

{
  "sys": { "id": "3trmXRMKq7bd0Prbef1... (商品番号)" },
  "fields": {
    "productName": { "ja-JP": "ステンレスタンブラー500ml" },
    "keywords":    { "ja-JP": "保温、軽量、キャンプ" }
  }
}

この商品を受け取り、外部の AI で詳細説明を作り、その商品の詳細説明(body)を埋める Script の定義です。

{
  "method": "Post",
  "executionMode": "Async",
  "statements": [
    { "type": "Http", "method": "POST",
      "url": "https://api.ai-writer.example.com/v1/generate",
      "headers": [
        { "key": "Authorization", "value": "Bearer <秘密の access token>", "secret": true }
      ],
      "body": {
        "product":  "{ /payload/fields/productName/ja-JP }",
        "keywords": "{ /payload/fields/keywords/ja-JP }"
      },
      "name": "gen" },
 
    { "type": "ResourcePatch", "resource": "Content",
      "target": { "sys": { "id": "{ /payload/sys/id }" } },
      "fields": { "body": { "ja-JP": "{ /gen/body/text }" } },
      "publish": true },
 
    { "type": "Return", "value": { "id": "{ /payload/sys/id }" }, "statusCode": 200 }
  ]
}
  • 最初の動作(Http)が、隠しておいた鍵で外部の AI サービスを呼びます。鍵を入れたヘッダーに secret: true を付けると、その値はお客さんには見えず、呼ぶ直前にだけ展開されます。受け取った結果は gen という名前に入れておきます。
  • 二つ目の動作(ResourcePatch)が、先ほど受け取った文章({ /gen/body/text })で、その商品の詳細説明(body)だけを埋めます。商品のほかの値には手を付けません。
  • 値を次の段階へ流していくプレースホルダー { /… } を使います。{ /payload/fields/productName/ja-JP } は渡された商品の名前を、{ /payload/sys/id } はその商品の番号を、{ /gen/body/text } は AI が返した文章を指します。
  • 最後の動作(Return)が、説明を埋めた商品の番号を返します。
  • Content の値を { "ja-JP": … } のように言語別に書く理由、statements に入れられる動作の全種類、プレースホルダーと条件・計算の文法は、値式 と Statement カタログ で扱います。

呼ぶと何を返すか

Script は、最後に Return 動作の値を呼んだ側に返します。返される応答には、次のものが入ります。

  • requestId: 今回の実行を指す識別番号です。
  • durationMs: 実行にかかった時間(ミリ秒)です。
  • statusCode: 到達した Return の状態コードです(別途定めなければ 200)。
  • return または error: Return が返した値です。ふつうは return に入り、その値をエラーとして示しておくと error に入ります。二つが一緒に出ることはありません。

ただし「商品説明の入力」は外部の AI を呼ぶため、バックグラウンドで実行されます(下の 即時実行とバックグラウンド実行 を参照)。そのため、呼ぶとまず「受け付けた」という意味で 202 と requestId だけがすぐに返り、上の応答は、少し後にその requestId で問い合わせ直して(ポーリングして)受け取ります。すべて終わった応答は、このような形です。

{
  "requestId": "3trmXRMZ8kqLb2Prdf1eYc0axWnKv",
  "durationMs": 1840,
  "statusCode": 200,
  "return": { "id": "3trmXRMKq7bd0Prbef1... (商品番号)" }
}

ウェブサイトは、この return の id で、たった今説明が埋められた商品を指し示し、新しい詳細説明をお客さんに見せることができます。

Return に届かないまま Script が終わると、return も error もなく、statusCode だけが 200 で返ります。Return で応答本文と状態コードを定める詳しい規則は、Statement カタログの Return で扱います。

即時実行とバックグラウンド実行

Script は二つの方式で実行でき、定義の executionMode で決めます。

  • 即時実行(Sync): 呼んだその場ですぐに実行し、出来上がった応答をそのまま返します。外部の呼び出しがなく、すぐ終わる作業に向いています。
  • バックグラウンド実行(Async): 裏側で実行します。呼ぶと、まず「受け付けた」という意味で 202 と requestId だけをすぐに返し、実際の結果は後でその requestId で問い合わせ直して(ポーリングして)取得します。

一つ規則があります。外部のサービスを呼ぶ動作や、ファイルを受け取って Media として取り込む動作が一つでも入っていると、その Script は 必ずバックグラウンド実行でなければなりません。「商品説明の入力」も外部の AI を呼ぶため、バックグラウンド実行です。即時実行で保存しようとすると、保存のときに差し戻されます。外部の応答が遅れても、呼んだ側を待たせ続けないためです。

実行に使える時間にも予算があります。即時実行は既定で10秒、バックグラウンド実行は既定で60秒です。ポーリングの方法や、どの動作がバックグラウンド実行を必要とするのかといった詳しい規則は、実行セマンティクス、制約、セキュリティ で扱います。

Script は誰が作るのか

複雑な動作を人が手で一つひとつ書くよりも、Script は AI エージェントやプログラムが作るように設計されています。AI エージェントに「商品説明を埋めてくれる窓口を作って」と言葉で頼むと、エージェントが上で見たような定義を代わりに作ってくれます。ひとことで、ウェブサイトの裏で働く窓口が一つできるわけです。

AI エージェントで Script を作る詳しい流れは、一言でバックエンドを作る で扱います。

作られた Script は、管理画面(コンテンツスタジオ)で人が見て管理します。名前と定義を確認し、必要なら直したり消したりします。実際に Script を呼ぶ側は、お客さんが見るウェブサイトやアプリ(フロントエンド)です。製品に登録した会員(ServiceUser)の身元では、Script の実行だけができ、作成や修正はできません。

Webhook とどう違うのか

Script と Webhook はどちらも外部とつなぐ仕組みですが、呼ぶ方向が反対です。

  • Webhook は、決めておいた変化が起きると(商品が登録されるように)、ひとりでに反応します。人が呼ばなくても、出来事が起きればひとりでに動きます。ただし、呼んだ側に結果を返すことはありません。
  • Script は、ウェブサイトが必要なときに自分で呼ぶ窓口です。呼んではじめて実行され、その実行の結果を、即時に、またはバックグラウンド実行ならポーリングで受け取ります。

「店主が『説明の入力』を押すと AI を呼んで詳細説明を受け取り、埋める」は、呼ぶ側が結果を待つ作業なので Script が、「商品が登録されると自動で何かが起こる」は、出来事に反応する作業なので Webhook が向いています。そして、この二つは一緒に使えます。すぐ次で見ていきます。

登録するだけで説明がひとりでに埋まるように

ここまでは、店主が「説明の入力」ボタンを押して Script を 自分で 呼んでいました。一歩進んで、ボタンを押さなくても、商品を登録した瞬間に Script が ひとりでに 実行されるようにできます。Webhook がその出来事をとらえて、こちらの Script を代わりに呼んでくれるからです。

流れは、次のとおりです。

  1. 店主が商品を登録します。このとき、商品名とキーワードだけを埋め、詳細説明は空けておきます。
  2. 商品が新しく登録される出来事を Webhook が察知します。
  3. Webhook が、たった今登録された商品をそのまま、こちらの「商品説明の入力」Script に渡して実行します。
  4. Script が外部の AI で詳細説明を作り、その商品の詳細説明(body)を埋めます。
  5. 少し後には、商品の詳細説明がひとりでに埋まっています。

ここで使う Script は、先ほどとまったく同じものです。変わるのは、呼ぶきっかけだけです。ボタンの代わりに「商品が登録された」という出来事が呼ぶのです。登録された商品がそのまま Script の入力になるので、Script は { /payload/sys/id } でその商品をつかみ、詳細説明を埋めます。

Webhook の側で定めることは、三つです。どの出来事に反応するか(商品が新しく登録されるとき)、どの商品にだけ反応するか(商品の種類で限定)、そして何をするか(外部のアドレスへ知らせる代わりに、こちらの Script を呼ぶこと)です。

Script が埋めた詳細説明が、また「商品が変わった」という出来事を引き起こして、いつまでも繰り返されるのではないかと心配になるかもしれません。そうはなりません。Script の書き込みは、別途オンにしない限り新しい出来事を引き起こさず、プラットフォームも果てしない繰り返しを防ぎます。

このようにつなぐ詳しい設定は、Webhook で扱います。

Script が特に役立つ場合

外部に「こういうことが起きた」と知らせるだけで済む作業なら、Webhook 一つで十分です。しかし、外部のサービスを呼んだあと、その結果を見て続けて判断し、処理しなければならないなら、その流れ全体を一か所にまとめる Script が必要です。

有料で AI 画像を作ってくれる機能を例に挙げてみます。お客さんが画像の生成を依頼すると、次のことが順番に起こらなければなりません。

  1. お客さんのクレジットが足りているかを確認します。足りなければここで止まり、「クレジットが足りません」と知らせます。
  2. 足りていれば、費用の分だけクレジットを先に差し引きます。
  3. 外部の AI サービスを呼んで画像を作ります。
  4. 作られた画像を Content として保存します。
  5. 3番か4番で問題が起きたら、先ほど差し引いたクレジットをまた元に戻します。

Webhook は「依頼が入ってきた」と外部に知らせることはできても、このように結果を見てクレジットを差し引いたり、失敗を元に戻したりすることはできません。いくつもの段階を条件に応じてつなぎ、失敗すれば前の段階を元に戻す仕事は Script が担います。Script が特に力を発揮する場合は、次のとおりです。

  • 結果を見て続けて処理する必要があるとき: 外部のサービスが返した応答に応じて、保存するか、差し引くか、元に戻すかをその場で判断します。
  • 同時に入ってきてもずれてはいけないとき: 同じお客さんが短い間に二度依頼しても、クレジットが二度差し引かれてはいけません。Script は、値を読んだあと保存する直前に「その間にほかの依頼がこの値を変えていないか」をバージョンで確認し、ずれていれば止まります。
  • 呼ぶ側にない権限が必要なとき: お客さんには、クレジットの残高を自分で直接直す権限がありません。それでも差し引きが安全に行われるのは、Script がそれを作った人の権限を委任されて実行されるからです。呼ぶ側には、Script を実行する権限だけを与えればよいのです。この委任は、下の 実行と管理の権限 で詳しく扱います。

この例を実際の Script の定義としてどう書くのかは、クックブック のクレジットの確認・差し引き・戻しの例で扱います。

実行と管理の権限

Script を実行したり管理したりするには、ロール(SpaceRole)にそれに応じた権限が必要です。

  • 実行: Script を呼ぶには、ロールに Script の実行権限(Execute)が必要です。なければ実行がふさがれます。
  • 管理: Script を作り、直し、消すには、それぞれ作成・修正・削除の権限が必要です。

Script を実行するときに確認されるのは、呼ぶ側に実行権限(Execute)があるか、この一つだけです。Script の中に並べた個々の動作は、実行するその瞬間に別途権限を確認されることはありません。実行を許されたプログラムを呼ぶとき、そのプログラムを実行する権限だけを見て、その中でする一つひとつの作業まで毎回許可を得るわけではないのと同じです。

その代わり、個々の動作の権限は、実行するときではなく Script を 保存するとき に前もって確認されます。作った人が、その Script の中の動作が扱う Content・Media の操作権限を実際に持っていてはじめて保存されます。たとえば「商品説明の入力」Script は商品 Content の詳細説明を直すので、作った人に商品を直す権限がなければ、保存が差し戻されます。権限のない動作が入った Script は、そもそも保存されないということです。

こう見ると、Script の実行は、それを 作った人の権限を委任されて 代わりに行うのと同じです。呼ぶ側が自分では行えない作業でも、作った人ができる作業であれば、Script を通してそのまま起こります。ですから、Script を作るときは、その中にどんな動作を入れるかを慎重に決めなければなりません。作った人の権限が、そのまま、その Script にできることの範囲になります。

ロールに権限を入れる方法は、ロールと権限 で扱います。

知っておくこと

  • 発行がありません。 Script は、発行して訪問者へ配信される種類のリソースではなく、管理画面で作っておき、ウェブサイトが呼んで使う窓口です。ですから Content・Media と違って発行・発行取り消しの状態がなく、作ればすぐに使えます。直すたびにバージョンが一つずつ上がるだけで、消すときも発行取り消しのような事前の段階なく、そのまま消えます。
  • 数に上限があります。 Script は課金の対象なので、一つの Organization が持てる数が料金プランごとに決まっています(Free 3個、Basic 10個、Pro 50個、Enterprise 無制限)。上限に達すると新しい Script を作れなくなり、使っていない Script を消すと、一枠がまた空きます。

コンテンツスタジオで管理する

作られた Script は、コンテンツスタジオの Script 画面で見て管理します。左側のメニューで Script を押すと、これまでに作った Script が一覧で表示されます。各行には、名前、呼ぶ方式(HTTP メソッド)、Script を指す Script ID、実行の場所(実行モード)、最後に直した日付が表示されます。

Script 一覧画面。「商品説明の入力」Script が HTTP メソッド POST、実行モード Async で 1 行表示されている状態

定義はふつう AI エージェントが代わりに作ってくれますが、この画面で自分で作ることもできます。新しい Script は、一覧の右上の 作成 ボタンで作ります。

  1. 一覧の右上の 作成 ボタンを押してください。
  2. 名前 欄に 商品説明の入力 を入力してください。
  3. HTTP メソッド で、この Script を呼ぶ方式(ここでは POST)を選んでください。
  4. 実行モード で Async(バックグラウンド実行)を選んでください。この Script は外部の AI を呼ぶため、必ずバックグラウンド実行でなければなりません。
  5. Statement 欄に、やることを書いた定義を入れてください。上の「商品説明の入力」の例の定義をそのまま入れれば大丈夫です。

新しい Script 作成画面。名前「商品説明の入力」、HTTP メソッド POST、実行モード Async、Statement 欄に定義を入れた状態

呼ぶときに一緒に送る入力を、実行前に検査したい場合は、Payload Schema の Payload 検証 をオンにして、検査する形式を書いておきます。すべて埋めたら、右上の 保存 ボタンを押してください。

一覧から Script を一つ押すと、詳細画面が開きます。ここで名前と定義を確認でき、この Script を呼ぶアドレス(Execute URL)も見られます。定義を直したあと 保存 すると、バージョンが一つ上がり、もう使わない Script は 削除 で消します。

商品説明の入力 Script 詳細画面。名前・HTTP メソッド・実行モード・ID・Execute URL と Statement 定義が表示されている状態

次にすること

  • Script 概要: Script を成す定義の最上位の構造と実行規則、文法のドキュメント一式を扱います。
  • Statement カタログ: statements に入れられる動作(リソースの作成・読み取り・修正・削除、外部サービスの呼び出し、条件・繰り返しなど)の種類とフィールドを扱います。
  • Webhook: 商品が登録されると Script がひとりでに実行されるようつなぐように、決めておいた変化が起きると自動で反応させる方法を扱います。