開発者向けAPI、MCP、GitHub、およびトリガーシミュレーション
Shopify Flow では、REST API または MCP を利用して、トリガーのシミュレーション、キーの管理、および GitHub との連携を行い、カスタムトリガーコードを設定できます。
トリガーを確認したり、オン／オフを切り替えたり、イベント履歴を確認したり、ご自身のコードやAIアシスタントからトリガーをシミュレートしたりすることができます。Workflow Trigger ExtensionsはREST APIとMCPサーバーを提供しており、GitHubリポジトリに接続できるため、カスタムトリガーコードをバージョン管理下に置くことが可能です。これら3つすべては、「Developer」ページで管理されます。
トリガーのシミュレーション
Shopify Flowのワークフローをテストするというのは、通常、ストアで実際に操作を行うことを意味します。つまり、商品の編集、注文の確定、投票の結果を待つといった作業です。シミュレーションを利用すれば、そのような待ち時間を省くことができます。トリガーを選択し、対象のリソースを指定するだけで、あたかも実際のイベントが発生したかのようにワークフローが実行されます。
1つを実行する2つの方法：
- **アプリ内で、「****イベント履歴」**から任意のイベントを開き、「シミュレート」をもう一度選択してください。そうすることで、そのイベントが再び発生します。
- APIまたはMCPを介して、リソースIDまたは過去のイベントを用いて。
シミュレーションは意図的に忠実に再現されています。ショートカットペイロードを生成することはありません。実際の Shopify の Webhook と同じパイプラインを経由するため、ワークフローが受け取る内容は、本番環境で受け取る内容とまったく同じになります。
curl -X POST https://shopify.workflow-trigger-extensions.app/api/v1/triggers/product-update-trigger/simulate \
-H "Authorization: Bearer ftk_your_key_here" \
-H "Content-Type: application/json" \
-d '{"resourceId":"gid://shopify/Product/123456789","dryRun":true}'ドライランでは、トリガーの検証、トピックの解決、ペイロードの表示が行われますが、実際にイベントは発火しません。実際にイベントを発火させるには、dryRun を削除してください。また、{"fromHistoryId":"456"} を指定することで、新しいイベントを作成する代わりに、過去のイベントを再発火させることもできます。
Webhookではなくポーリングによって駆動されるトリガーはシミュレートできません。トリガー一覧では、simulatable: falseというエラーが表示されます。
APIキー
**「開発者」**ページでキーを作成し、そのアクセスレベルを選択してください：
- 読み取り専用 - トリガーとその状態の表示、イベント履歴、統計情報、および権限の確認が可能です。
- 読み取りと書き込み、およびトリガーのオン・オフの切り替えも可能です。
- 読み取り、書き込み、実行――さらに、トリガーのシミュレーションやカスタムトリガーコードのテストも可能です。
完全な鍵は、作成時に一度だけ表示されます。鍵はハッシュ化されて保存され、いつでも取り消すことができます。Bearerトークンとして送信してください：
Authorization: Bearer ftk_your_key_hereシミュレーションは、上記の理由から独自のレベルに配置されています。シミュレーションでは自動化処理が実際に実行されるため、日常的な読み取りに使用されるキーではそれらを起動できないからです。
REST API
| 方法 | パス | レベル | 目的 |
|---|---|---|---|
| GET | /api/v1 |
なし | APIインデックス - APIが稼働中であることを確認します |
| GET | /api/v1/me |
読む | 認証を確認し、ご自身のキーのレベルをご確認ください |
| GET | /api/v1/triggers |
読む | 各トリガーと、貴店におけるその状態 |
| GET | /api/v1/triggers/:handle |
読む | あるトリガーの詳細 |
| PUT | /api/v1/triggers/:handle |
書く | 1つのトリガーをオンまたはオフにする |
| PUT | /api/v1/triggers |
書く | 1回の呼び出しで複数のスイッチをオンまたはオフにする |
| 投稿 | /api/v1/triggers/:handle/simulate |
実行する | トリガーをシミュレートする |
| GET | /api/v1/triggers/custom |
読む | 独自のカスタムトリガーとそのコード |
| GET | /api/v1/triggers/custom/:handle/test |
読む | カスタムトリガーに対するキャプチャされたサンプルイベント |
| 投稿 | /api/v1/triggers/custom/:handle/test |
実行する | 保存や発火を行わずに、カスタムトリガーコードを実行する |
| GET | /api/v1/history |
読む | トリガーとなるイベントの一覧 |
| GET | /api/v1/history/:id |
読む | 1つのイベントとそのペイロードを取得します |
| GET | /api/v1/stats |
読む | 合計、成功率、ステータス別内訳 |
| GET | /api/v1/permissions |
読む | どのデータへのアクセス許可を付与したか、そしてそれぞれによって何が利用可能になるか |
GET /api/v1/triggers これは設定に役立つ機能です。各トリガーについて、必要な権限、その権限が付与されているかどうか、トリガーが有効になっているかどうか、そしてアプリ内のどこで管理できるかが表示されます。
トリガーのオン・オフを切り替える
PUT PATCH ではなくこれを使用するのは、この呼び出しが冪等であるためです。タイムアウト後に再実行しても、何かが二重に適用されることはありません。これは、アシスタントが API を操作する際に重要な点となります。
curl -X PUT https://shopify.workflow-trigger-extensions.app/api/v1/triggers/order-tags-added-trigger \
-H "Authorization: Bearer ftk_your_key_here" \
-H "Content-Type: application/json" \
-d '{"enabled":true}'「Enabling」では、権限は付与されません。トリガーに、まだ付与していない権限が必要な場合でも、呼び出しは成功し、何が不足しているか、どこで付与すべきかを正確に通知します：
{
"enabled": true,
"scopeGranted": false,
"missingScopeLabels": ["Order Data Access"],
"permissionsUrl": "https://admin.shopify.com/store/.../app/permissions?permission=read_orders",
"warning": "Enabled, but this trigger cannot fire until Order Data Access is granted."
}そのリンクをクリックすると、「権限」ページが開き、必要なカードまでスクロールされた状態になります。
"sync": true を追加してデータ同期も開始するようにすると、トリガーは今後作成されるレコードだけでなく、既存のレコードに対しても機能するようになります。
一度に複数の設定を切り替えるには、PUT /api/v1/triggers に対して、明示的なリストまたはカテゴリ全体を指定することができます：
{ "enabled": true, "handles": ["order-tags-added-trigger", "order-note-changed-trigger"] }
{ "enabled": true, "category": "orders" }GitHubを連携する
「Developer」ページの「Connections」タブでは、カスタムトリガーのコード用のGitHubリポジトリを連携させることができます。変更内容はプルリクエストとしてレビュー可能になり、誰が何を変更したかを確認できるほか、正常に動作しなくなった変換をロールバックすることも可能です。
「接続」を選択すると、指定したアカウントにGitHubアプリがインストールされます。アプリがアクセスできるリポジトリはご自身で選択でき、GitHubからそのアクセス権をいつでも取り消すことができます。リポジトリを選択すると、すでに設定済みのカスタムトリガーがすべて即座にそのリポジトリに書き込まれるため、時間の経過とともに徐々に反映されていくのではなく、最初からアプリと連動した状態で利用を開始できます。
| 担当業務 | どうなるのでしょうか |
|---|---|
| アプリ内でトリガーを作成、編集、または複製します | ファイルがリポジトリにコミットされました |
| アプリ内のトリガーを削除する | そのファイルはリポジトリから削除されました |
| 接続されているブランチに変更をプッシュしてください | アプリ内でトリガーのコードが更新されます |
各トリガーは、そのハンドル名をファイル名とした1つのファイルであり、エディタに表示されているモジュールそのものが含まれています。それ以外の要素は一切含まれていません。そのため、他のJavaScriptファイルと同様に、ご自身のエディタで開いて実行し、リンティングを行うことができます。その後、コミットする前に、上記の/testエンドポイントを使用して、実際にキャプチャされたイベントに対して実行することができます。
以前のバージョンに戻す
変更を元に戻すために、Gitの知識は必要ありません。リポジトリが接続されると、トリガーエディタに「バージョン」ドロップダウンが表示され、そのファイルの過去のすべてのバージョンが、日付や作成者とともに一覧表示されます。その中から1つを選択すると、未保存の変更としてエディタに読み込まれるため、まず内容を確認することができます。保存を行うと、新しいコミットとして元に戻されます。
変更または切断
「リポジトリを変更」を選択すると、インストールには一切影響を与えずにピッカー画面に戻ります。「接続を解除」を選択すると、GitHub上のインストールが取り消されるほか、こちらでもインストールが削除されます。つまり、その名の通りの動作となります。**「権限を管理」を選択すると、**GitHub上のインストール設定画面が開き、そこでリポジトリの追加や削除を行うことができます。
カスタムトリガーコードのテスト
カスタムトリガーコードをリポジトリに保存し、ご自身のエディタで編集すれば、アプリに保存することなく、キャプチャされたサンプルイベントに対してそのコードを実行することができます。
curl -X POST https://shopify.workflow-trigger-extensions.app/api/v1/triggers/custom/my-trigger/test \
-H "Authorization: Bearer ftk_your_key_here" \
-H "Content-Type: application/json" \
-d "$(jq -Rn --rawfile c flow-triggers/my-trigger.js '{code:$c}')"アプリの「Test」ボタンに表示される内容――つまり、テストが実行されるかどうか、出力オブジェクト、ctx.logの記述内容、および実行時間――が返されます。
何も実行されず、何も保存されません。ワークフローは実行されず、イベントは記録されず、割り当ても消費されず、保存されたコードには一切手を加えられません。ファイルウォッチャーによる保存のたびに実行しても安全です。ワークフローの詳細については、カスタムトリガー をご覧ください。
MCPサーバー
「Developer」ページの「MCP」タブには、サーバーのURLと、Claude、Cursor、VS Code、Gemini CLIなどに対応した、そのままコピーして使える接続コマンドが表示されます。各ツールはRESTエンドポイントを反映しており、利用可能なツールセットはキーの権限レベルに応じて異なります。読み取り専用キーの場合、書き込みや実行関連のツールは一切表示されません。
| ツール | レベル | 機能の説明 |
|---|---|---|
list_triggers |
読む | すべてのトリガーとその状態 |
list_custom_triggers |
読む | 独自のカスタムトリガーとそのコード |
get_custom_trigger_sample |
読む | カスタムトリガーが検証対象とする、キャプチャされたイベント |
list_history |
読む | 最近のトリガー事象 |
get_event |
読む | ペイロードを含む1つのイベント |
get_stats |
読む | 集計統計 |
get_permissions |
読む | 付与された権限と、それによって利用可能になる機能 |
get_trigger |
書く | あるトリガーの詳細について |
set_trigger |
書く | 1つのトリガーのオン／オフを切り替える |
set_triggers_bulk |
書く | 複数のスイッチを一度にオンまたはオフにする |
simulate_trigger |
実行する | 必要に応じてトリガーを発動させる |
test_custom_trigger |
実行する | 保存や発火を行わずに、カスタムトリガーコードを実行する |
アシスタントが真に役立つ理由はここにあります。アシスタントは、現在の状況を一覧表示し、トリガーに必要な条件を説明し、トリガーを有効にし、テストイベントを実行し、結果を読み返すことができます。さらに、カスタムトリガーの場合は、コードを書き直してテストすることも可能です。これらすべてを、ユーザーが会話を中断することなく行うことができます。
お客様のデータの保護について
イベントのペイロードは、個人データがマスキングされた状態で返されます。メールアドレス、電話番号、カード番号、および個人名が記載されたフィールドは、*** となります。ShopifyのリソースIDおよびビジネス関連のフィールドはそのまま残されるため、ペイロードは有用なままとなります。
マスキングはフィールド名や値のパターンに対して行われますが、これはあくまで慎重な措置であり、完全な保証ではありません。フリーテキストフィールド内の個人情報が漏れてしまう可能性があります。また、エラーメッセージについても、サーバーから送信される前に、内部の診断情報が削除されます。
GitHubとの連携では、漏洩の恐れがある認証情報は一切保存されません。保存されるのはインストールIDのみであり、リポジトリへのアクセスには、必要に応じて発行され、1時間以内に失効するトークンが使用されます。
今後の手順
- カスタムトリガー - わずか数行のJavaScriptで、独自のトリガーを作成できます。
- プランと利用方法 - どのような事象が「事由」に該当するのか、また手当の支給はどのように行われるのか。
- 『Workflow Trigger Extensions』の概要 - トリガーの仕組みと、その有効化方法について。
レート制限
REST APIとMCPサーバーは、APIキーごとに1つの予算を共有します。
- キーごとに60秒あたり300件のリクエストを、固定ウィンドウとして設定します。
- **実行レベルの呼び出しには、1時間あたり60回という、さらに厳格な上限が設定されています。**これらは両方とも消費されるため、実行が集中すると、共有の割り当て分も消費されてしまいます。このアプリの場合、トリガーのシミュレーションやカスタムトリガーコードの実行が該当しますが、これらはいずれもワークフローを実際に起動させるものです。
- **どのプランでも同様です。**プランのメーターはAPI呼び出しではなくイベントをトリガーするため、プランのアップグレードを行ってもこれらの数値は増加しません。
- HTTP 429が返ってきました。一旦待機してから再試行してください。できれば指数関数的なバックオフを行ってください。
- 万が一、キャッシュが一時的に利用できなくなった場合でも、リミッターはお客様の統合機能をブロックすることなく、オープン状態を維持します。
Shopifyへの受信Webhookにはレート制限は適用されません
Shopify から送信される Webhook に対して、弊社では送信速度の制限を行っておりません。送信された順に受け付け、キューに格納されます。上限は、お客様のプランにおける 30 日間のイベント許容量となります。
カスタムトリガーを作成する際に知っておくべきことが一つあります。それは、コードはリスニング対象のトピックで発生するすべてのイベントに対して実行され、null を返すことでフィルタリングされたイベントも含め、各実行が1つのイベントとしてカウントされるということです。その処理コストは、同じイベントに対する組み込みトリガーと同じです。
Shopify
これらは、ShopifyがShopifyのAPIに対して設定している制限であり、当社が設定しているものではありません。これらは、このアプリ（およびお客様のワークフロー）がShopify側で実行できる操作に適用されるものであり、当社の制限を十分に下回っている場合でも、大規模なストアではこれらの制限に達してしまう可能性があります。
- ShopifyのすべてのAPIにおいて、入力配列の最大要素数は250個に制限されています。これを超える要素数を含むリクエストは拒否されます。
- **ページネーションは25,000件で終了します。**件数は25,000件までは正確ですが、それを超えるとShopifyは
25001を返します。これは「25,000件を超える」という意味です。さらに多くの件数を取得する必要がある場合は、まずフィルタリングを行ってください。 - GraphQL Admin API の利用量は、1秒あたりのポイント数で算出されるクエリコストに基づいて計測され、上限はストアのShopifyプランによって異なります：
| Shopify プラン | 1秒あたりのポイント数 |
|---|---|
| 標準 | 100 |
| 上級 | 200 |
| さらに | 1000 |
| エンタープライズ（コマース・コンポーネント） | 2000 |
ストアフロント API にはレート制限は設けられていません。
詳細はこちら：Shopify APIのレート制限