開発者向けAPI、MCP、GitHub、およびトリガーシミュレーション

トリガーの確認、有効化・無効化、イベント履歴の閲覧、および自身のコードやAIアシスタントからのトリガーシミュレーションを行うことができます。Workflow Trigger ExtensionsはREST APIとMCPサーバーを提供しており、GitHubリポジトリと連携できるため、カスタムトリガーコードをバージョン管理下に置くことが可能です。これら3つはすべて、「Developer」ページで管理されます。

トリガーのシミュレーション

Flowのワークフローをテストする際、通常はストア内で実際に操作を行う必要があります。つまり、商品の編集、注文の送信、投票の結果を待つといった作業です。シミュレーションを利用すれば、こうした待ち時間を省くことができます。トリガーを選択し、リソースを指定するだけで、あたかも実際のイベントが発生したかのようにワークフローが実行されます。

1つを実行する2つの方法：

**アプリ内で、「****イベント履歴」**から任意のイベントを開き、**もう一度「シミュレート」**を選択します。これにより、そのイベントが正確に再発生します。
APIまたはMCPを介して、リソースIDまたは過去のイベントを使用して。

シミュレーションは意図的に忠実に再現されています。ショートカットペイロードを生成するのではなく、実際の Shopify のウェブフックと同じパイプラインを経由するため、ワークフローが受け取る内容は本番環境で受け取る内容と完全に一致します。

Dry run firstbash

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 を操作する場合に重要な点です。

Enable one triggerbash

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 rm」や、不適切なマージ、あるいは間違ったブランチへのプッシュによって、稼働中のワークフローが黙って停止してしまい、元に戻す手段がなくなってしまうからです。トリガーを実際に削除したい場合は、アプリ内でトリガーを削除してください。

同じ理由で、ファイルからトリガーを作成することもできません。トリガーも、どのShopifyイベントを監視するかを認識する必要がありますが、ファイルにはコードしか含まれていないからです。

以前のバージョンに戻す

変更を元に戻すのに、Gitの知識は必要ありません。リポジトリが接続されると、トリガーエディタに「バージョン」ドロップダウンが表示され、そのファイルの過去のすべてのバージョンが日付と作成者とともに一覧表示されます。その中から1つを選択すると、未保存の変更としてエディタに読み込まれるため、まず内容を確認することができます。保存を行うと、新しいコミットとして元に戻されます。

変更または切断

「リポジトリを変更」を選択すると、インストール内容に変更を加えることなく、ピッカー画面に戻ります。「接続を解除」を選択すると、GitHub上のインストールが取り消されるほか、ここでのインストールも削除されます。つまり、その名の通りの動作をします。「権限を管理」を選択すると、GitHub上のインストール設定画面が開き、そこでリポジトリの追加や削除を行うことができます。

カスタムトリガーコードのテスト

カスタムトリガーコードをリポジトリに保存し、独自のエディタで編集すれば、アプリに保存することなく、キャプチャされたサンプルイベントに対してそのコードを実行することができます。

Test the file you are editingbash

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回という、より厳しい2つ目の割り当てが設定されています。**これらは両方の割り当てを消費するため、実行が集中すると、共有の割り当ても消費されてしまいます。このアプリの場合、トリガーのシミュレーションやカスタムトリガーコードの実行がこれに該当しますが、これらはいずれもワークフローを実際に起動させるものです。
**どのプランでも同様です。**プランのメーターはAPI呼び出しではなくイベントをトリガーするため、プランのアップグレードを行ってもこれらの数値は増加しません。
HTTP 429が返ってきた。一旦待機してから再試行する。可能であれば、指数関数的なバックオフを行う。
キャッシュが一時的に利用できない場合でも、リミッターは統合をブロックすることなく、オープン状態を維持します。

ShopifyへのインバウンドWebhookにはレート制限が適用されません

Shopify から送信される Webhook に対して、当社ではスループット制限を行っていません。Webhook は到着順に受け付けられ、キューに入れられます。上限は、ご利用のプランにおける 30 日間のイベント許容量となります。

カスタムトリガーを作成する際に知っておくべきことが1つあります。それは、コードは監視対象のトピックで発生するすべてのイベントに対して実行され、nullを返してフィルタリングしたイベントも含め、各実行が1つのイベントとしてカウントされるということです。この処理にかかるコストは、同じイベントに対する組み込みトリガーが実行される場合と同じです。

Shopify

これらは、ShopifyがShopifyのAPIに対して設定している制限であり、当社が設定しているものではありません。これらは、このアプリ（およびお客様のワークフロー）がShopify側で実行できる操作に適用されるものであり、当社の制限を十分に下回っている場合でも、大規模なストアではこれらの制限に達してしまう可能性があります。

すべてのShopify APIにおいて、入力配列の最大要素数は250個に制限されています。これを超える要素数を含むリクエストは拒否されます。
**ページネーションは25,000件で終了します。**件数カウントは25,000件までは正確ですが、それを超えるとShopifyは25001を返します。これは「25,000件を超える」ことを意味します。さらに深く参照する必要がある場合は、まずフィルタリングを行ってください。
GraphQL Admin API の利用量は、クエリコスト（秒あたりのポイント）に基づいて計測され、上限はストアの「Shopify」プランによって異なります：

Shopify 計画	1秒あたりの得点
標準	100
上級	200
さらに	1000
エンタープライズ（コマース・コンポーネント）	2000

Storefront APIにはレート制限はありません。

詳細はこちら：Shopify APIのレート制限