Composio Salesforce 工具包实战指南：OAuth 配置、域名修复与常见错误排查

Composio Salesforce 工具包实战指南OAuth 配置、域名修复与常见错误排查【免费下载链接】composioComposio powers 1000 toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composio本文围绕 Composio 开源仓库中的 Salesforce 集成文档系统梳理 Salesforce 工具包的自定义 OAuth 凭据配置、连接字段My Domain 子域与 Instance 端点的填写规范、URL_NOT_RESET/OAUTH_APPROVAL_ERROR_GENERIC等典型错误的原因与修复路径、刷新令牌配额限制以及关系型数据查询SOQL 子查询与工具选型建议帮助你快速定位并解决 Salesforce 集成中的真实故障。一、连接前的必填字段子域与 Instance 端点在 Composio 中发起 Salesforce 连接时有两个关键字段需要确认My Domain SubdomainMy Domain 子域例如your-company.myInstance endpoint实例端点例如/services/data/v61.0。这两项属于 Salesforce 接受的附加连接发起字段。如果你通过 SDK/API 直接发起连接应将它们通过.initiate()传入而不是依赖托管连接 UI 去收集详细字段说明可参考 docs/content/toolkits/faq/salesforce.md 与 docs/kb/source/toolkits/salesforce/public.md。子域取值格式默认情况下 Salesforce 子域取值为login适用于大多数流程。但当组织有特定 My Domain 或使用 Developer Edition / Lightning 环境时需要按下表格式传入登录/API 域前缀注意是 API 域前缀而非完整浏览器 URL场景浏览器 URL 示例应传入的子域默认情况—login标准 My Domainhttps://your-company.my.salesforce.com/...your-company.myDeveloper Edition / Lightninghttps://org.develop.lightning.force.com/...org.develop.my对应 OAuth 主机通常为https://org.develop.my.salesforce.com/...值得注意的边界情况如果用户只输入了orgComposio 可能生成org.salesforce.com这会在 OAuth 之前就因浏览器 DNS 解析失败而报错如DNS_PROBE_FINISHED_NXDOMAIN。因此务必使用 My Domain 或 API 域前缀而不是不完整的组织标签。相关原始文档位于 docs/kb/source/toolkits/salesforce/public.mdSalesforce subdomain defaults to login一节。通过工具包 API 检查预期字段你可以按 slug 拉取工具包定义来确认实际期望的字段列表GET /api/v3.1/toolkits/salesforce连接成功后再次拉取 connected account即可看到连接后回填的相同字段。Composio 的 Salesforce 工具包 slug 在 ts/packages/cli/src/generated/toolkit-slugs.ts 中注册salesforce、salesforce_service_cloud可据此确认工具包名称拼写。二、自定义 OAuth 凭据托管认证与直接发起两条路径Composio 的 Salesforce 工具包支持OAuth2与server-to-server OAuth2并且支持使用客户自有的凭据customer-owned credentials。做法是按 Salesforce 官方的 OAuth 指引在 Salesforce 侧配置 Connected App然后把该 App 的凭据填入 Composio 的自定义 Auth Config从而获得对 scopes、品牌标识以及服务商侧策略的控制权。路径 A托管认证Hosted AuthSalesforce 字段收集界面属于 Hosted Authentication / 连接链接流程的一部分。当你希望 Composio 代为收集必填字段子域、实例端点时使用托管认证即可用户会在连接 UI 中填写这些字段。路径 B直接调用.initiate()如果应用本身已经知道 Salesforce 实例与子域值可以跳过字段收集界面直接调用.initiate()并传入必填字段。相关方法语义如下.initiate()发起新连接并生成认证 URL.refresh()为已发起的连接重新生成认证 URL.link()开启一条全新连接allow_multipleTrue当同一user_id确实需要多条连接时传入。回调地址的区分自定义 Salesforce OAuth 时授权重定向 URI 应使用 Composio auth-config 流程中展示的provider 回调端点即 Composio 工具包 auth callback 地址。它与连接发起时传入的callback_url/callbackUrl认证完成后的客户侧跳转地址是两个不同概念不要混淆。三、常见错误深度排查3.1URL_NOT_RESET子域未配置、回落到login现象连接报URL_NOT_RESET。原因Salesforce 组织要求使用特定的 My Domain 值但连接仍在使用通用的login默认值或使用了不完整的子域。处理步骤重新核对连接上的 Salesforce 域/子域值传入正确的 My Domain 子域参考上文格式表如果问题出现在旧版固定的工具包版本上请升级到最新工具包版本后重试。默认login值对大多数 Salesforce 流程是没问题的只有组织级失败才需要替换为具体子域。3.2OAUTH_APPROVAL_ERROR_GENERIC与app must be installed into org现象OAuth 被 Salesforce 拦截用户看到OAUTH_APPROVAL_ERROR_GENERIC或者回调 URL 中携带errorinvalid_clienterror_descriptionappmustbeinstalledintoorg原因Connected App 尚未被组织安装或批准。Salesforce 的 connected app 使用限制可能要求组织管理员先安装/批准该应用组织用户才能完成认证。处理步骤让 Salesforce 组织管理员进入Setup设置搜索External Client App Settings或OAuth Connected App Usage可参考 docs/kb/source/toolkits/salesforce/public.md 中关于 OAuth Connected App Usage 的描述Actions 列会显示 Install 按钮找到对应应用并执行 Salesforce 展示的安装/批准操作管理员批准后用户重试 OAuth 连接。3.3 每个用户每 App 仅允许 5 个有效刷新令牌现象同一 Salesforce 用户第 6 次连接后较早的 Composio connected account 开始出现令牌错误。原因Salesforce 限制每个用户在每个 connected app 上最多拥有 5 个有效刷新令牌。同一用户连接第 6 次时Salesforce 可能吊销最旧的刷新令牌。排查清单除配额外还应检查用户是否更改了密码用户是否在 Salesforce 中撤销了该应用connected app 的刷新令牌策略是否被改为非valid until revoked是否存在使令牌失效的组织级会话策略。3.4 连接后找不到自己创建的数据在 Salesforce 中创建的记录可能不会立即出现在某个给定视图里。此时应使用搜索Search确认记录确实存在再决定是否需要调整视图或查询条件。四、关系型数据查询用 SOQL 子查询遍历关系当需要查询 Pricebooks、Opportunities 等关联对象时应使用SOQL 子查询遍历对象关系。官方 FAQ 给出的示例是从 Opportunity 出发向下展开 OpportunityLineItems并顺带取到关联的 PricebookEntry 与 Product2 名称SELECT Id, Name, (SELECT Id, Quantity, UnitPrice, TotalPrice, PricebookEntry.Product2.Name FROM OpportunityLineItems) FROM Opportunity这个例子展示了 Product → Pricebook → Opportunity 这条关系链的查询方式外层查询 Opportunity内层子查询通过OpportunityLineItems关系名取得明细并用点号导航PricebookEntry.Product2.Name跨对象取字段。五、工具选型当前工具、废弃工具与 Schema 发现5.1 用SALESFORCE_GET_ALL_FIELDS_FOR_OBJECT做 Schema 发现在构建针对某个 Salesforce 对象的查询或更新流程之前可以使用SALESFORCE_GET_ALL_FIELDS_FOR_OBJECT检查该对象可用字段这是面向对象构建查询前的 Schema 发现手段。5.2 废弃工具与迁移对照废弃工具在正式移除前仍可继续使用使用时请留意工具描述中的DEPRECATED:标记。FAQ 与知识库均给出了明确的迁移对照见 docs/kb/source/toolkits/salesforce/public.md废弃工具旧当前工具新SALESFORCE_RETRIEVE_LEAD_BY_IDSALESFORCE_GET_LEADSALESFORCE_RETRIEVE_SPECIFIC_CONTACT_BY_IDSALESFORCE_GET_CONTACT_BY_IDSALESFORCE_RETRIEVE_OPPORTUNITIES_DATASALESFORCE_LIST_OPPORTUNITIES5.3 先列表后按 ID 取详情推荐模式先用SALESFORCE_LIST_CONTACTS列出联系人并记录 ID 与名称再调用SALESFORCE_GET_CONTACT_BY_ID传入目标联系人 ID 获取明细避免一次性深查带来的不确定性问题。六、进阶用 Proxy Execute 实现 Frontdoor/UI Bridge 流程对于 Salesforce Frontdoor / UI Bridge 类流程不要通过 connected account API 读取访问令牌来手动构造请求。正确做法是使用Proxy Execute并绑定 Salesforce connected accountComposio 会在服务端把 OAuth 访问令牌注入被代理的 Salesforce 请求例如调用/services/oauth2/singleaccessSalesforce 返回 frontdoor URI应用将用户的浏览器重定向到该 frontdoor URI从而安全地进入 Salesforce UI。这样访问令牌全程不出服务器避免了在客户端暴露敏感凭据。七、参考资料本文核心来源docs/content/toolkits/faq/salesforce.md支持知识库原文docs/kb/source/toolkits/salesforce/public.md面向用户的知识库文章docs/kb/articles/toolkits-salesforce.md工具包 slug 注册ts/packages/cli/src/generated/toolkit-slugs.ts更多工具包 FAQdocs/content/toolkits/faq【免费下载链接】composioComposio powers 1000 toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考