make-api-shell-connection-workflow

Make API Shell + Connection 工作流

在以下特定工作流中使用此技能：

• 发现正确的 Make 应用和该应用专用的 API 调用模块
• 复用或构建可复用的 Shell 场景，其中包含 StartSubscenario、一个应用 API 调用模块和 ReturnData
• 复用现有的合适连接，或创建该 Shell 所需的连接请求
• 授权完成后，将选定的连接配置到 Shell 中
• 运行场景，并将其用作通用 SaaS 检索传输层，适用于电子邮件、CRM、工单及类似系统

此技能主要用于配置和构建 Shell。业务检索属于第二阶段，只有在连接就绪且 Shell 已根据当前工作区元数据完成验证后，才能开始。

此处所述的通用 Shell 是 API 传输封装，而非业务逻辑。它应充当可复用的 API 端点，适用于 Make 能够接入的任何 SaaS 应用，包括电子邮件、CRM、工单、支持、营销或任务系统。

已知的 Make 模块 ID：Make Code 模块为 "module": "code:ExecuteCode"。

快速路由

根据当前任务阅读对应文件：

任务	参考文档
发现应用、模块和连接类型层	发现与 Shell
创建、检查或处理凭据请求	连接请求
选择并执行连接后的检索路径	检索执行
Shell 运行后修复提供商授权或权限范围问题	检索执行
清理示例并准备可公开分享的版本	清理与分享
从通用蓝图模板开始	示例 Shell 蓝图
提供商没有 Make 应用：使用 noAuth、API 密钥、Basic auth 或 OAuth 2.0 构建通用 HTTP Shell	HTTP 备用 Shell

新 Agent 的操作顺序

当新 Agent 收到“获取我未读的电子邮件”“拉取我未处理的 CRM 潜在客户”或“获取我的 Jira 工单”等请求时，默认操作顺序如下：

1. 确定提供商锚点。
   • 电子邮件：Gmail、Outlook 或其他
   • CRM：HubSpot、Salesforce 或其他
   • 工单：Jira、Zendesk、Linear 或其他
2. 如果请求含糊不清，确定目标账户、邮箱、工作区、项目或队列。
3. 确定当前使用的 Make 区域、组织和团队。
4. 确定提供商应用。GET /api/v2/imt/apps 会忽略 search、limit 和 scoredSearch，并始终返回完整的约 4k 个应用目录，因此绝不要依赖服务器端搜索。应在本地进行匹配：先搜索精选的热门应用目录（在辅助环境中，search_apps(query=...) 会执行此操作）；只有在此处没有匹配项时，才获取一次完整目录，并在客户端按 name 和 label 进行不区分大小写的筛选。查询中的所有词都会参与评分；如果没有完全匹配的短语，候选项必须命中查询中的第一个词才会计入结果，排名第一的结果为推荐应用。
   • 只有 Make 验证过的应用以及组织自有的自定义应用/SDK 应用 才能自动选择。社区应用（communityApp-*）不参与匹配；自定义应用（目录前缀 app#*）可以使用。权威检查方式：GET /api/v2/imt/apps-meta 会列出组织可用的所有已验证应用和自定义应用（自定义应用名称在此处不会带 app# 前缀）。内置工具伪应用（builtin、util、gateway、regexp）不是 SaaS 提供商，绝不能作为搜索结果。如果提供商只有社区应用，则视为“没有应用”，并改为构建通用 HTTP 回退 shell——参见 HTTP 回退 Shell。
5. 使用 GET /api/v2/imt/apps/{appName}/{version} 检查所选应用，并记录准确的 API 调用模块 slug 和两层连接类型。
6. 只有在验证详细信息和可用性后，才重用现有的合适连接：GET /api/v2/connections/{connectionId} 加上 POST /api/v2/connections/{connectionId}/test。
7. 只有在重用现有的合适连接时才重用现有 shell。如果必须创建新连接，就为该新连接创建一个新 shell，而不是将旧 shell 修改为使用新授权的账户。
8. 只有在不存在合适连接时，才创建凭据请求。
9. 确定连接方案后，按照上述重用规则创建或修改 shell，并验证该 shell 能够运行。
10. 首先通过 API 调用 shell 运行范围尽可能窄的检索请求。
11. 只有在首次 shell 运行证明路径可用后，才扩展为列表/搜索 → 详情 → 规范化。
12. 如果该提供商完全没有 Make 应用，就使用 http:MakeRequest 构建通用 HTTP 回退 shell，而不是放弃——参见 HTTP 回退 Shell。

Agent 不应从“用户想要 SaaS 数据”直接跳到“创建新连接”或“调用直接 SDK”，而不按此顺序逐步执行。

输入解析关卡

在配置或检索之前，明确解析以下输入：

• 提供商锚点
• 如果可能存在多个账户或邮箱，则确定目标账户身份
• 如果凭据请求的接收者可能与当前令牌所有者不同，则确定预期的接收者
• Make 区域、组织和团队

如果缺少其中某项，且无法安全地发现，则停止并仅询问缺失的那一项。

核心规则

1. 切勿猜测 API 调用模块名称。请从当前 Make 元数据中查明。
2. 将 Gmail、Outlook 或 HubSpot 等示例应用视为示例，不要将其当作通用默认值。
3. 将以下两个类型层分开处理：
   • 场景／模块连接参数类型
   • 连接列表或凭据请求类型
4. 优先复用，然后再创建：
   • 优先使用现有的合适连接，而不是请求新凭据
   • 仅在复用现有合适连接时，才复用现有 shell 场景
   • 新授权的连接必须配有新建的 shell
5. 不要将业务数据检索路由到 Make 原生的搜索／列表／获取模块。对于此类工作流，始终通过 Make 应用的 API 调用 shell 检索。
6. 在写入现有的线上场景或替换连接映射之前，先征求确认。
7. 公开示例必须经过脱敏。不要包含真实姓名、用户 ID、团队 ID、组织 ID、特定租户的主机名，也不要声称单个私有工作区能证明通用规则。
8. 示例中使用干净的基础 URL 变量。公开示例默认使用 https://us1.make.com，占位符保持通用。除非当前用户明确提供或要求该区域，否则不要在公开示例中提及 we.make.com。有效区域包括 eu1、eu2、us1、us2 或 we；如果用户提供自定义区域或 BASE_URL，请予以接受。
9. 明确区分以下四个阶段：
   • 服务提供商和应用解析
   • 连接配置
   • shell 配置
   • 检索执行和输出规范化
10. 不要假定通用的三模块蓝图对所有应用都能自动激活。激活前，请将中间模块元数据与当前工作区中同一应用及版本的真实蓝图或模块导出进行比较。
11. 对于使用 scenario-service:ReturnData 和 ExpectDataAny 的通用 API shell 契约，最终映射器必须将应用模块的响应正文作为 data: {{MIDDLE_API_MODULE_ID.body}} 返回。
12. 此技能中的通用示例蓝图里，中间 API 调用模块的 ID 是 3，因此示例映射器为 data: {{3.body}}。如果真实蓝图使用不同的模块 ID，则使用真实中间模块的 ID。例如，Make UI 导出可能使用 StartSubscenario 2、API 调用模块 5 和 ReturnData 4，此时正确的映射器为 data: {{5.body}}。
13. 切勿仅仅因为完整 bundle 看起来更合适，就用 {{MIDDLE_API_MODULE_ID}} 或 {{MIDDLE_API_MODULE_ID.data}} 替换该 shell 契约默认值。该 shell 的用途是返回 API 响应正文，而非整个 Make 模块 bundle。
14. 仍需检查真实执行 bundle 以进行验证，但应使用它来确认 body 是否包含预期的有效负载或错误对象，而不是借此重新定义通用 shell 契约。
15. 在进行任何团队级调用之前，先确定活动工作区的区域。GET /api/v2/users/me 和 GET /api/v2/imt/apps/... 可能在多个区域成功，但在错误区域调用 GET /api/v2/connections?teamId=... 或场景端点可能会因 403 Permission denied 失败。
16. 对于 REST /api/v2/connections 端点，请使用 type=... 或 type[]=... 进行筛选。不要仅仅因为 MCP 工具使用了 accountName 这一术语，就假定 accountName=... 等查询参数会生效。
17. 不要让用户在聊天中粘贴原始 OAuth 密钥、API 密钥或密码。必须创建新连接时，请使用凭据请求。根据接收方选择路径：对于当前 Make 用户，自助服务端点（actions/create、actions/create-by-credentials）适用于多种套餐；只有向其他人请求凭据（requests/v2）才是受 license.credentialRequests 限制的 Enterprise／Partner 功能（参见连接请求中的“先根据接收方选择请求路径”）。如果没有可用的请求路径，请引导用户在场景编辑器中创建连接。在所有流程中，都要说明准确的凭据粘贴格式（带 Bearer 前缀或原始密钥），切勿假定用户知道。
18. 如果用户的请求含糊不清，先确认具体的服务提供商和账号；如果用户已明确说明，则不要重复询问。
19. 如果模块 2 的请求方法是 PUT、PATCH 或 DELETE，请在执行前明确警告。应将这些方法视为会更改线上 SaaS 数据的操作，而非被动检索。
20. 不要假定 StartSubscenario.metadata.interface 足以用于场景运行。创建或更新按需 shell 后，必须通过 /api/v2/scenarios/{scenarioId}/interface 显式设置场景级接口，并在首次运行前验证。
21. 对于此类 shell，/api/v2/scenarios/{scenarioId}/run 是标准执行路径。将业务有效负载放在 data 下传入，且其中的键必须与场景接口完全一致；验证运行时优先使用 responsive: true。
22. 将查询参数作为名为 qs 的一等 shell 输入公开。使用 qs 传入服务提供商 API 查询参数，例如 Gmail 搜索选项、Drive fields、Drive q、Graph $select、分页参数或 supportsAllDrives。如果调用方在 path 中提供了查询字符串，请在运行 shell 前将其规范化到 qs 中。
23. 在 Make UI 导出与 Make 场景创建／更新 API 之间迁移蓝图时，必须有意规范化结构：UI／导出产物可能将流程存储在 subflows[0].flow 中，而场景创建／更新负载要求顶层的 flow。未经规范化，不要将原始 UI 导出发送到创建／更新接口。
24. Shell 复用按应用区分，而不仅仅按服务提供商系列区分。围绕某个应用模块构建的 shell，不应仅因两个模块属于同一供应商套件，就改为指向另一个应用模块。
25. 复用任何现有连接或指向现有连接的 shell 之前，必须调用 Make 的连接验证 API：POST /api/v2/connections/{connectionId}/test。响应中的 verified: true 即为连接有效的证明。过时的凭据请求状态不能推翻已验证的连接。连接有效不代表服务提供商一定会授权所有路径、方法或作用域；只有针对预期操作成功运行 shell，才能证明服务提供商已授权。遇到服务提供商认证或作用域错误时，请使用授权修复手册。
26. 用户完成授权后恢复流程时，请复用已保存的凭据请求 requestId；检查该请求，然后列出并验证连接。同一应用／账号的有效请求仍在处理中时，不要创建新的凭据请求。
27. 将未来的 expire 时间戳视为有效。只有过期时间已过、连接已撤销、验证失败或出现服务提供商认证错误时，才视为无效。

应用绑定与连接系列矩阵

外壳模式是通用的，但每个实际外壳都绑定到一个已发现的 Make 应用模块。

不要将“Google”或“Microsoft”视为可互换的单一连接系列。在 Make 中，应用系列通常会按产品界面拆分。

常见示例：

业务界面	API 调用模块示例	场景／模块连接参数类型	常见连接列表或请求类型
Gmail	google-email:makeAnApiCall	account:google-email	google-email 或工作区专用变体，例如 google-restricted
Google Calendar / Sheets / Drive 风格的应用	从元数据中发现的应用专用 Google 模块	通常为 account:google	通常为 google
Outlook / Microsoft 邮件	microsoft-email:makeApiCall	account:azure	azure

由此应遵循以下规则：

• 只有在已发现的应用、模块标识、版本和连接系列仍匹配时，才复用外壳。
• 只有在账户身份和范围仍符合所请求操作时，才复用连接。
• 如果为其他账户或连接系列授权了新连接，应为其创建新外壳，而不是悄悄将旧外壳改指向该连接。

如有疑问，请检查确切的应用元数据和现有连接详情，不要根据供应商名称推断兼容性。

标准外壳结构

可复用外壳恰好包含三个模块：

1. scenario-service:StartSubscenario
2. 一个从元数据中发现的应用专用 Make API 调用模块
3. scenario-service:ReturnData

通过 StartSubscenario 暴露以下外壳输入：

• path
• method
• header
• qs
• body

将已发现的中间模块作为外壳中唯一的应用专用部分。

通用外壳契约

此外壳是一个通用 API 端点包装器。

它接收：

• path
• method
• header
• qs
• body

它会将这些值转发到应用专用的 Make API 调用模块。

默认检索应使用 GET。将 PUT、PATCH 和 DELETE 视为写入／破坏性方法，运行前必须获得用户明确确认。

它只返回一项内容：

• 应用专用 Make API 调用模块返回的响应正文

因此，外壳契约为：

{
  "data": "{{MIDDLE_API_MODULE_ID.body}}"
}

在此技能的通用示例蓝图中，MIDDLE_API_MODULE_ID 为 3，因此示例值是 {{3.body}}。在真实的 Make 导出内容中，务必检查模块 ID，并使用实际 API 调用模块的 ID。

此契约适用于 SaaS 供应商，具有通用性。无论中间模块连接的是 Gmail、Outlook、HubSpot、Jira，还是其他供应商专用的 Make API 调用模块，均适用。

外壳不应尝试返回：

• 整个 Make bundle {{3}}
• 猜测的嵌套字段，例如 {{3.data}}
• 与正文混在一起的传输元数据

外壳仅负责传输。业务解读在后续阶段进行。

两阶段运行模式

阶段 A：配置

首先完成以下步骤：

1. 确定供应商和确切的 Make 应用
2. 发现确切的应用版本和模块标识
3. 确定两层连接类型
4. 查找适用于正确账户身份和范围的现有连接
5. 使用 POST /api/v2/connections/{connectionId}/test 验证候选连接
6. 查找是否存在已符合该已验证连接契约的现有外壳场景
7. 只有在复用失败时，才创建或解析凭据请求
8. 如果创建了新连接，则创建新外壳；只有复用现有连接时，才修补现有外壳
9. 验证外壳是否使用所选连接运行

阶段 A 结束时的交付内容：

• 已准备好连接的 API 调用外壳场景

阶段 B：检索

只有阶段 A 成功后，才能：

1. 通过 API 调用 shell 配置检索调用
2. 运行范围较窄的验证查询或查找
3. 检查真实输出包的结构
4. 将 ReturnData 固定为通用 shell 契约，并仅在需要时更新下游规范化逻辑
5. 重新运行并验证面向用户的载荷

不要将凭据请求成功视为检索阶段已解决的证据。

重要事项：

• 通用的三模块 API shell 仍是此工作流系列中唯一的检索传输方式
• 将 shell 契约固定为 data: {{MIDDLE_API_MODULE_ID.body}}，其中 MIDDLE_API_MODULE_ID 是蓝图中实际的应用 API 调用模块 ID
• 不要将原生检索／搜索／列表模块用作回退方案或优化方案
• 如果授权失败是因为现有连接已过期或无效，请勿尝试在原连接上重新授权；应走凭据请求流程，然后为新连接创建一个新的 shell

接口与运行规则

对于按需 shell，请将接口配置视为单独的部署步骤：

1. 创建或更新场景蓝图
2. 明确设置 /api/v2/scenarios/{scenarioId}/interface
3. 在首次运行前验证接口结构
4. 只有完成上述步骤后，才能调用 /api/v2/scenarios/{scenarioId}/run

使用如下结构的运行载荷：

{
  "data": {
    "path": "...",
    "method": "GET",
    "header": [],
    "qs": [],
    "body": null
  },
  "responsive": true
}

data 下的键名必须与场景接口完全一致。如果从未明确设置接口，即使 StartSubscenario 模块本身包含接口元数据，run 仍可能拒绝调用。

请求体处理兼容性规则

保持通用 shell 契约稳定，但不要假设每个提供商模块对空请求体或 null 请求体的处理方式都相同。

已观察到的安全模式：

• 具备写入能力的 shell 可以公开并映射 body
• 读取为主的 shell 在提供商模块对 GET 或 DELETE 上的空载荷序列化处理不佳时，可能需要完全省略 Module 2 的 body 映射器

如果某个提供商专用的 Make API 调用模块仅在 body 存在但为空时失败，优先采用以下模式之一：

• 不带 body 映射器的读取 shell
• 带 body 映射器的写入 shell
• 如果提供商在读取与写入路径上的行为不同，则使用两个独立的 shell

不要因此更改 ReturnData。这是 Module 2 的请求结构兼容性问题，不是 shell 输出契约问题。

响应行为

使用此技能时：

• 首先总结发现的应用、版本、API 调用模块的确切名称，以及连接的两个类型层
• 明确说明提供商是如何确定的：用户陈述、现有 Make 构件，还是 Make 应用目录查询
• 明确说明是复用 shell，还是新建 shell
• 明确说明是复用连接，还是新请求连接
• 明确说明当前所处阶段：配置或检索
• 检索开始时，说明 API 调用计划：列表／搜索路径、任何后续详情路径，以及规范化计划
• 如果创建了新连接，明确说明已为其创建新的 shell
• 如果请求最初是电子邮件、CRM 或工单等业务诉求，说明业务目标以及所选的确切 API 路径模式
• 明确标注任何假设
• 写入操作提示应简短具体
• 如果 Module 2 即将运行 PUT、PATCH 或 DELETE，请先停止并在执行前发出警告
• 如果激活失败或 ReturnData 看起来不正确，请勿宣称流程已完成，并报告确切的失败阶段
• 如果要公开分享，请在最终定稿前将示例改写为占位符和中性标签

相关技能

• make-scenario-building：了解超出此 shell 模式范围的场景架构
• make-module-configuring：了解模块配置、映射、Webhook、密钥和数据存储的详细信息
• make-mcp-reference：了解 Make MCP 连接方式、作用域和超时行为