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