Composio Salesforce 工具包實(shí)戰(zhàn)指南OAuth 配置、域名修復(fù)與常見錯(cuò)誤排查【免費(fèi)下載鏈接】composioComposio powers 1000 toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/co/composio本文圍繞 Composio 開源倉庫中的 Salesforce 集成文檔系統(tǒng)梳理 Salesforce 工具包的自定義 OAuth 憑據(jù)配置、連接字段My Domain 子域與 Instance 端點(diǎn)的填寫規(guī)范、URL_NOT_RESET/OAUTH_APPROVAL_ERROR_GENERIC等典型錯(cuò)誤的原因與修復(fù)路徑、刷新令牌配額限制以及關(guān)系型數(shù)據(jù)查詢SOQL 子查詢與工具選型建議幫助你快速定位并解決 Salesforce 集成中的真實(shí)故障。一、連接前的必填字段子域與 Instance 端點(diǎn)在 Composio 中發(fā)起 Salesforce 連接時(shí)有兩個(gè)關(guān)鍵字段需要確認(rèn)My Domain SubdomainMy Domain 子域例如your-company.myInstance endpoint實(shí)例端點(diǎn)例如/services/data/v61.0。這兩項(xiàng)屬于 Salesforce 接受的附加連接發(fā)起字段。如果你通過 SDK/API 直接發(fā)起連接應(yīng)將它們通過.initiate()傳入而不是依賴托管連接 UI 去收集詳細(xì)字段說明可參考 docs/content/toolkits/faq/salesforce.md 與 docs/kb/source/toolkits/salesforce/public.md。子域取值格式默認(rèn)情況下 Salesforce 子域取值為login適用于大多數(shù)流程。但當(dāng)組織有特定 My Domain 或使用 Developer Edition / Lightning 環(huán)境時(shí)需要按下表格式傳入登錄/API 域前綴注意是 API 域前綴而非完整瀏覽器 URL場(chǎng)景瀏覽器 URL 示例應(yīng)傳入的子域默認(rèn)情況—login標(biāo)準(zhǔn) My Domainhttps://your-company.my.salesforce.com/...your-company.myDeveloper Edition / Lightninghttps://org.develop.lightning.force.com/...org.develop.my對(duì)應(yīng) OAuth 主機(jī)通常為https://org.develop.my.salesforce.com/...值得注意的邊界情況如果用戶只輸入了orgComposio 可能生成org.salesforce.com這會(huì)在 OAuth 之前就因?yàn)g覽器 DNS 解析失敗而報(bào)錯(cuò)如DNS_PROBE_FINISHED_NXDOMAIN。因此務(wù)必使用 My Domain 或 API 域前綴而不是不完整的組織標(biāo)簽。相關(guān)原始文檔位于 docs/kb/source/toolkits/salesforce/public.mdSalesforce subdomain defaults to login一節(jié)。通過工具包 API 檢查預(yù)期字段你可以按 slug 拉取工具包定義來確認(rèn)實(shí)際期望的字段列表GET /api/v3.1/toolkits/salesforce連接成功后再次拉取 connected account即可看到連接后回填的相同字段。Composio 的 Salesforce 工具包 slug 在 ts/packages/cli/src/generated/toolkit-slugs.ts 中注冊(cè)salesforce、salesforce_service_cloud可據(jù)此確認(rèn)工具包名稱拼寫。二、自定義 OAuth 憑據(jù)托管認(rèn)證與直接發(fā)起兩條路徑Composio 的 Salesforce 工具包支持OAuth2與server-to-server OAuth2并且支持使用客戶自有的憑據(jù)customer-owned credentials。做法是按 Salesforce 官方的 OAuth 指引在 Salesforce 側(cè)配置 Connected App然后把該 App 的憑據(jù)填入 Composio 的自定義 Auth Config從而獲得對(duì) scopes、品牌標(biāo)識(shí)以及服務(wù)商側(cè)策略的控制權(quán)。路徑 A托管認(rèn)證Hosted AuthSalesforce 字段收集界面屬于 Hosted Authentication / 連接鏈接流程的一部分。當(dāng)你希望 Composio 代為收集必填字段子域、實(shí)例端點(diǎn)時(shí)使用托管認(rèn)證即可用戶會(huì)在連接 UI 中填寫這些字段。路徑 B直接調(diào)用.initiate()如果應(yīng)用本身已經(jīng)知道 Salesforce 實(shí)例與子域值可以跳過字段收集界面直接調(diào)用.initiate()并傳入必填字段。相關(guān)方法語義如下.initiate()發(fā)起新連接并生成認(rèn)證 URL.refresh()為已發(fā)起的連接重新生成認(rèn)證 URL.link()開啟一條全新連接allow_multipleTrue當(dāng)同一user_id確實(shí)需要多條連接時(shí)傳入。回調(diào)地址的區(qū)分自定義 Salesforce OAuth 時(shí)授權(quán)重定向 URI 應(yīng)使用 Composio auth-config 流程中展示的provider 回調(diào)端點(diǎn)即 Composio 工具包 auth callback 地址。它與連接發(fā)起時(shí)傳入的callback_url/callbackUrl認(rèn)證完成后的客戶側(cè)跳轉(zhuǎn)地址是兩個(gè)不同概念不要混淆。三、常見錯(cuò)誤深度排查3.1URL_NOT_RESET子域未配置、回落到login現(xiàn)象連接報(bào)URL_NOT_RESET。原因Salesforce 組織要求使用特定的 My Domain 值但連接仍在使用通用的login默認(rèn)值或使用了不完整的子域。處理步驟重新核對(duì)連接上的 Salesforce 域/子域值傳入正確的 My Domain 子域參考上文格式表如果問題出現(xiàn)在舊版固定的工具包版本上請(qǐng)升級(jí)到最新工具包版本后重試。默認(rèn)login值對(duì)大多數(shù) Salesforce 流程是沒問題的只有組織級(jí)失敗才需要替換為具體子域。3.2OAUTH_APPROVAL_ERROR_GENERIC與app must be installed into org現(xiàn)象OAuth 被 Salesforce 攔截用戶看到OAUTH_APPROVAL_ERROR_GENERIC或者回調(diào) URL 中攜帶errorinvalid_clienterror_descriptionappmustbeinstalledintoorg原因Connected App 尚未被組織安裝或批準(zhǔn)。Salesforce 的 connected app 使用限制可能要求組織管理員先安裝/批準(zhǔn)該應(yīng)用組織用戶才能完成認(rèn)證。處理步驟讓 Salesforce 組織管理員進(jìn)入Setup設(shè)置搜索External Client App Settings或OAuth Connected App Usage可參考 docs/kb/source/toolkits/salesforce/public.md 中關(guān)于 OAuth Connected App Usage 的描述Actions 列會(huì)顯示 Install 按鈕找到對(duì)應(yīng)應(yīng)用并執(zhí)行 Salesforce 展示的安裝/批準(zhǔn)操作管理員批準(zhǔn)后用戶重試 OAuth 連接。3.3 每個(gè)用戶每 App 僅允許 5 個(gè)有效刷新令牌現(xiàn)象同一 Salesforce 用戶第 6 次連接后較早的 Composio connected account 開始出現(xiàn)令牌錯(cuò)誤。原因Salesforce 限制每個(gè)用戶在每個(gè) connected app 上最多擁有 5 個(gè)有效刷新令牌。同一用戶連接第 6 次時(shí)Salesforce 可能吊銷最舊的刷新令牌。排查清單除配額外還應(yīng)檢查用戶是否更改了密碼用戶是否在 Salesforce 中撤銷了該應(yīng)用connected app 的刷新令牌策略是否被改為非valid until revoked是否存在使令牌失效的組織級(jí)會(huì)話策略。3.4 連接后找不到自己創(chuàng)建的數(shù)據(jù)在 Salesforce 中創(chuàng)建的記錄可能不會(huì)立即出現(xiàn)在某個(gè)給定視圖里。此時(shí)應(yīng)使用搜索Search確認(rèn)記錄確實(shí)存在再?zèng)Q定是否需要調(diào)整視圖或查詢條件。四、關(guān)系型數(shù)據(jù)查詢用 SOQL 子查詢遍歷關(guān)系當(dāng)需要查詢 Pricebooks、Opportunities 等關(guān)聯(lián)對(duì)象時(shí)應(yīng)使用SOQL 子查詢遍歷對(duì)象關(guān)系。官方 FAQ 給出的示例是從 Opportunity 出發(fā)向下展開 OpportunityLineItems并順帶取到關(guān)聯(lián)的 PricebookEntry 與 Product2 名稱SELECT Id, Name, (SELECT Id, Quantity, UnitPrice, TotalPrice, PricebookEntry.Product2.Name FROM OpportunityLineItems) FROM Opportunity這個(gè)例子展示了 Product → Pricebook → Opportunity 這條關(guān)系鏈的查詢方式外層查詢 Opportunity內(nèi)層子查詢通過OpportunityLineItems關(guān)系名取得明細(xì)并用點(diǎn)號(hào)導(dǎo)航PricebookEntry.Product2.Name跨對(duì)象取字段。五、工具選型當(dāng)前工具、廢棄工具與 Schema 發(fā)現(xiàn)5.1 用SALESFORCE_GET_ALL_FIELDS_FOR_OBJECT做 Schema 發(fā)現(xiàn)在構(gòu)建針對(duì)某個(gè) Salesforce 對(duì)象的查詢或更新流程之前可以使用SALESFORCE_GET_ALL_FIELDS_FOR_OBJECT檢查該對(duì)象可用字段這是面向?qū)ο髽?gòu)建查詢前的 Schema 發(fā)現(xiàn)手段。5.2 廢棄工具與遷移對(duì)照廢棄工具在正式移除前仍可繼續(xù)使用使用時(shí)請(qǐng)留意工具描述中的DEPRECATED:標(biāo)記。FAQ 與知識(shí)庫均給出了明確的遷移對(duì)照見 docs/kb/source/toolkits/salesforce/public.md廢棄工具舊當(dāng)前工具新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列出聯(lián)系人并記錄 ID 與名稱再調(diào)用SALESFORCE_GET_CONTACT_BY_ID傳入目標(biāo)聯(lián)系人 ID 獲取明細(xì)避免一次性深查帶來的不確定性問題。六、進(jìn)階用 Proxy Execute 實(shí)現(xiàn) Frontdoor/UI Bridge 流程對(duì)于 Salesforce Frontdoor / UI Bridge 類流程不要通過 connected account API 讀取訪問令牌來手動(dòng)構(gòu)造請(qǐng)求。正確做法是使用Proxy Execute并綁定 Salesforce connected accountComposio 會(huì)在服務(wù)端把 OAuth 訪問令牌注入被代理的 Salesforce 請(qǐng)求例如調(diào)用/services/oauth2/singleaccessSalesforce 返回 frontdoor URI應(yīng)用將用戶的瀏覽器重定向到該 frontdoor URI從而安全地進(jìn)入 Salesforce UI。這樣訪問令牌全程不出服務(wù)器避免了在客戶端暴露敏感憑據(jù)。七、參考資料本文核心來源docs/content/toolkits/faq/salesforce.md支持知識(shí)庫原文docs/kb/source/toolkits/salesforce/public.md面向用戶的知識(shí)庫文章docs/kb/articles/toolkits-salesforce.md工具包 slug 注冊(cè)ts/packages/cli/src/generated/toolkit-slugs.ts更多工具包 FAQdocs/content/toolkits/faq【免費(fèi)下載鏈接】composioComposio powers 1000 toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/co/composio創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考