开发者 API、MCP、GitHub 和触发器模拟
您可以查看触发器、开启或关闭触发器、查阅事件历史记录，以及通过您自己的代码或 AI 助手模拟触发器。Workflow Trigger Extensions 提供了一个 REST API 和一个 MCP 服务器，并可连接到 GitHub 仓库，以便您的自定义触发器代码处于版本控制之下。这三项功能均在“开发者”页面上进行管理。
模拟触发器
测试 Flow 工作流通常意味着在您的商店中实际执行相关操作 - - 编辑商品、下单、等待投票结果。模拟功能则省去了这种等待：选择一个触发器，将其指向某个资源，它就会像真实事件刚刚发生一样触发。
有两种方法可以运行它：
- 在应用中，打开“事件历史记录”中的任意一个事件，然后再次选择**“模拟”**。这将重新触发该特定事件。
- 通过 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 |
写 | 打开或关闭一个扳机 |
| PUT | /api/v1/triggers |
写 | 通过一次调用批量开启或关闭多个设备 |
| POST | /api/v1/triggers/:handle/simulate |
执行 | 模拟一个触发器 |
| GET | /api/v1/triggers/custom |
阅读 | 您自己的自定义触发器及其代码 |
| GET | /api/v1/triggers/custom/:handle/test |
阅读 | 自定义触发器的捕获样本事件 |
| POST | /api/v1/triggers/custom/:handle/test |
执行 | 在不保存或触发的情况下运行自定义触发器代码 |
| GET | /api/v1/history |
阅读 | 列出触发事件 |
| GET | /api/v1/history/:id |
阅读 | 获取一个事件及其有效载荷 |
| 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}'Enable 不会授予任何权限。如果触发器需要某项您尚未授予的权限，调用仍会成功，并会明确告知您缺少哪些权限以及应在何处授予：
{
"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
在“开发者”页面中，“连接”选项卡可让您连接用于自定义触发器代码的GitHub仓库。更改内容将以拉取请求的形式供审核，您可以查看谁对哪些内容进行了修改，还可以回滚已无法正常工作的转换。
点击“连接”将在您选择的账户上安装我们的 GitHub 应用。您可以选择允许该应用访问哪些仓库，并且可以随时在 GitHub 上撤销该访问权限。选择一个仓库后，系统会立即将您已有的所有自定义触发器写入该仓库，这样该仓库一开始就能与应用匹配，而不是需要随着时间推移逐步填充。
| 你的工作内容 | 会发生什么 |
|---|---|
| 在应用中创建、编辑或复制一个触发器 | 该文件已提交到您的代码库 |
| 在应用中删除触发器 | 该文件已从您的代码库中删除 |
| 将更改推送到已连接的分支 | 应用中更新了触发器的代码 |
每个触发器都是一个以该触发器句柄命名的文件，其中包含的正是你在编辑器中看到的那个模块 - - 没有任何额外包装。因此，你可以像处理其他 JavaScript 文件一样，在自己的编辑器中打开它、运行它并进行代码检查，然后在提交之前，使用上方的 /test 端点，将其应用于一个实际捕获的事件上进行测试。
恢复到较早的版本
无需了解 Git 即可撤销更改。一旦连接了仓库，Trigger 编辑器会显示一个**“版本**”下拉菜单，其中列出了该文件的所有历史版本，并附有日期和作者信息。选择其中一个版本，它就会作为未保存的更改加载到编辑器中，这样你就可以先阅读一下 - - 保存操作会将其作为新的提交恢复到版本控制中。
更改或断开连接
“更改仓库”会将您带回选择器，且不会对安装进行任何更改。“断开连接”会撤销 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}')"你会得到该应用“测试”按钮所显示的内容：是否会触发、输出对象、你的ctx.log代码行以及运行时间。
既不会触发任何操作，也不会进行任何保存 - - 不会运行任何工作流，不会记录任何事件，不会消耗任何配额，且存储的代码保持不变。该操作可在文件监听器每次保存时安全地运行。完整的工作流请参见 自定义触发器。
MCP 服务器
“开发者”页面中的“MCP”选项卡会显示服务器 URL 以及适用于 Claude、Cursor、VS Code、Gemini CLI 等工具的、可直接复制的连接命令。这些工具对应于 REST 端点，且工具集取决于您的密钥权限级别 - - 只读密钥完全无法访问写入或执行类工具。
| 工具 | 级别 | 功能介绍 |
|---|---|---|
list_triggers |
阅读 | 每个触发器及其状态 |
list_custom_triggers |
阅读 | 您自己的自定义触发器及其代码 |
get_custom_trigger_sample |
阅读 | 自定义触发器用于检测的捕获事件 |
list_history |
阅读 | 近期触发事件 |
get_event |
阅读 | 一个事件及其有效载荷 |
get_stats |
阅读 | 汇总统计数据 |
get_permissions |
阅读 | 已授予的权限及其解锁的功能 |
get_trigger |
写 | 详细介绍一个触发器 |
set_trigger |
写 | 打开或关闭一个扳机 |
set_triggers_bulk |
写 | 一次打开或关闭多个开关 |
simulate_trigger |
执行 | 按需触发 |
test_custom_trigger |
执行 | 在不保存或触发的情况下运行自定义触发器代码 |
这正是让助手真正派上用场的原因：它能列出现有内容、解释触发器需要什么、开启触发器、触发测试事件、读取结果 - - 对于自定义触发器，还能重写代码并进行测试 - - 而这一切都无需您离开当前对话。
您的数据如何得到保护
事件有效载荷在返回时会对个人数据进行匿名处理：电子邮件地址、电话号码、卡号以及包含个人姓名的字段将被替换为 ***。Shopify 资源 ID 和业务字段则保持不变，以确保有效载荷仍具有实用价值。
屏蔽功能适用于字段名称和值模式，因此虽然处理较为谨慎，但并非绝对可靠 - - 自由文本字段中的个人数据仍可能泄露。此外，错误消息在离开服务器之前，其内部诊断细节也会被移除。
GitHub 连接不会存储任何可能泄露的凭据：仅保留安装 ID，而访问仓库则使用按需生成的令牌，该令牌在 1 小时内失效。
下一步
- 自定义触发器 - 只需几行 JavaScript 代码，即可创建自己的触发器。
- 套餐与使用情况 - 哪些情况算作“事件”，以及津贴是如何发放的。
- Workflow Trigger Extensions 简介 - 触发器的工作原理以及如何启用它们。
速率限制
REST API 和 MCP 服务器为每个 API 密钥共享一个配额。
- 每个密钥每60秒300次请求，作为固定时间窗口。
- **执行级调用有第二项更严格的配额限制，即每小时 60 次。**这两项配额都会被消耗，因此执行操作的突发情况也会占用共享配额。对于此应用而言，这意味着模拟触发器以及运行自定义触发器代码，这两者都会真正触发您的工作流。
- **所有套餐均是如此。**您的套餐计费机制是根据事件触发的，而非 API 调用，因此升级不会导致这些数字增加。
- 处理时返回 HTTP 429 状态码。请延迟并重试，最好采用指数退避算法。
- 如果我们的缓存短暂不可用，限流器会采用**“限流失败时放行”的机制**，而不是阻塞您的集成。
Shopify 的入站 webhook 不受速率限制
我们不会对Shopify发送给我们的 webhook 进行限流 - - 这些 webhook 会在到达时被接收并排入队列。上限是您套餐中30天的事件配额。
如果您编写自定义触发器，有一点值得了解：您的代码会在监听主题的每个事件发生时执行，且每次执行都计为一个事件，包括您通过返回 null 过滤掉的那些事件。其资源消耗与针对同一事件的内置触发器相同。
Shopify
这些是Shopify对Shopify API设定的限制，并非我们设定的。这些限制适用于该应用（以及您的工作流）在Shopify端可执行的操作，因此即使您完全在我们的限制范围内，在大型商店中也可能遇到这些限制。
- 所有Shopify API的输入数组项数上限均为250项。包含超过该限制的数组的请求将被拒绝。
- **分页在 25,000 个对象处停止。**计数在 25,000 以内是准确的；超过该数值时，Shopify 会返回
25001，表示“超过 25,000”。如果需要进一步查询，请先进行筛选。 - GraphQL 管理 API 根据计算出的查询成本（以每秒点数为单位）进行计量，其上限取决于商店的Shopify套餐：
| Shopify 计划 | 每秒得分 |
|---|---|
| 标准 | 100 |
| 高级 | 200 |
| 此外 | 1000 |
| 企业（商务组件） | 2000 |
Storefront API 没有速率限制。
详细信息：Shopify API 速率限制