Skip to Content
操作指南跨部門授權與洞察

把部門資料表分享給聊天室代理

情境：營運部的「訂單」資料表要分享給一個聊天室，而且代理只能看指定欄位；經理明確開啟該系統後，代理才應看見它。

前置條件

你需要部門 22222222-2222-4222-8222-222222222222 的資料表 moderator 權限來管理 grant，以及聊天室 11111111-1111-4111-8111-111111111111 的 manager 權限來選擇洞察系統。聊天室必須已啟用部門自訂表格的代理工作範圍；grant、代理工作範圍與洞察選擇是三個獨立開關。

以下 private 請求都使用使用者 access token。先從資料表回應的 settings.column_mapping 取得穩定的內部欄位 ID；不要把顯示名稱放進 visible_columns。

步驟

1. 建立系統標籤並指派資料表

若「訂單系統」標籤已存在，可直接使用既有 tag_id。否則先呼叫 tags.create 建立標籤，再以 tags.assignTable 指派部門資料表。

POST /private/module/custom_tables/department/22222222-2222-4222-8222-222222222222/table-tags
Content-Type: application/json
 
{
  "name": "訂單系統",
  "description": "訂單與出貨資料",
  "color": "#2563EB"
}
POST /private/module/custom_tables/department/22222222-2222-4222-8222-222222222222/table-tags/44444444-4444-4444-8444-444444444444/tables/33333333-3333-4333-8333-333333333333

保留建立或查得的 tag_id。洞察設定是以標籤為單位，不是以單一資料表為單位。

2. 對聊天室建立最小 grant

這個 upsert 同時定義讀寫權限與欄位投影。範例只允許內部成員讀取全部資料列，禁止新增與編輯，並只顯示「訂單編號」和「狀態」兩個內部欄位 ID；對應操作是 chatroomPermissions.grant。

PUT /private/module/custom_tables/department/22222222-2222-4222-8222-222222222222/tables/33333333-3333-4333-8333-333333333333/chatroom-permissions/11111111-1111-4111-8111-111111111111
Content-Type: application/json
 
{
  "audience": "internal",
  "can_read": "all",
  "can_insert": false,
  "can_edit": "none",
  "visible_columns": [
    "col_55555555_5555_4555_8555_555555555555",
    "col_66666666_6666_4666_8666_666666666666"
  ]
}

visible_columns 屬於這一筆 grant；同一張表分享給另一個聊天室時，可使用不同投影。

3. 從兩側驗證 ACL

先由 moderator 透過 chatroomPermissions.list 列出部門表 grants，再由聊天室成員以 tables.shared 列出分享進來的表。

GET /private/module/custom_tables/department/22222222-2222-4222-8222-222222222222/tables/33333333-3333-4333-8333-333333333333/chatroom-permissions
GET /private/module/custom_tables/chatroom/11111111-1111-4111-8111-111111111111/tables/shared

第二個回應應包含「訂單」，但可讀資料仍會套用該 grant 的 audience、列權限與欄位投影。加入聊天室本身不會自動產生 grant。

4. 由聊天室 manager 開啟洞察系統

先用 insight.systems.get 讀取候選系統，確認「訂單系統」出現在 systems 且尚未啟用，再以 insight.systems.set 用完整集合取代目前選擇。

GET /private/chatrooms/setting/custom-table-tags/11111111-1111-4111-8111-111111111111
PUT /private/chatrooms/setting/custom-table-tags/11111111-1111-4111-8111-111111111111
Content-Type: application/json
 
{
  "tag_ids": [
    "44444444-4444-4444-8444-444444444444"
  ]
}

這個 PUT 是 replace-set；若聊天室原本還啟用了其他標籤，也要一併放入。未指派標籤的合格分享表不受此 opt-in 過濾。

5. 驗證代理可見性

再次送出 insight.systems.get，確認該系統為 enabled: true，然後在聊天室開啟一個新的代理回合，要求列出可用的自訂表格。若 ACL grant、部門資料表代理工作範圍與洞察 opt-in 都成立，代理會看見「訂單」，且只取得 grant 允許的欄位。洞察切換不會放寬 REST ACL。

另一道門：同一個房間裡的外部 client

以上全部走的是內部受眾。步驟 2 的 grant 寫 audience: "internal"，涵蓋的是聊天室 1111… 裡的公司使用者；它不會給同一個房間裡的外部 client 任何權限。

「外部 client」才是正確的說法，而且這個區分不是措辭問題：平台會把任何解析出來、且 platform 不是 agent 的 client 標記為外部，也就是 LINE（含群組與聊天室情境）、Messenger、Instagram——以及 Web 頻道的訪客。他們通往這張表的路不是由 moderator 撰寫的 grant，而是 AI 以 custom_tables_apply_permission 與 custom_tables_use_passphrase 提供的權限申請／通行碼路徑。權限申請適用於聊天室資料表，或是分享進他們房間的部門資料表，所以上面那張「訂單」表是符合的；通行碼則不適用，因為 client-access 設定只有聊天室資料表那條路由。

在這個版本之前，agent 協定把那一節命名為「Social Media Channel Access Tools」，並告訴模型那些工具「只提供給社群媒體 client」。於是 Web 頻道訪客明明手上握著這兩個工具，卻被告知它們不是給自己用的，那條取得存取權的路從來沒有被提出來——訪客只看到一張讀不到的表，也沒有任何辦法開口要。這一節現在叫「External Client Access Tools」，並明確列出 Web 頻道。

有兩件事沒有改變。這兩個工具不存在代表呼叫者已經擁有完整存取，不是被鎖在門外。而且這條路徑不會放寬 REST ACL：申請通過後產生的是一筆明確的 client grant，之後照樣受同一套 audience、資料列權限與欄位投影約束。Moderator 這一側的審核佇列見 Grant 類型與 row policy，AI 那一側見 Agent 工具箱。

你會看到什麼

grant 清單會保留聊天室、audience、讀寫能力與兩個 visible_columns；tables/shared 會列出部門表；洞察回應會把「訂單系統」標成啟用。代理的新回合能找到這張表，但看不到投影之外的欄位。

常見錯誤

不要在此處猜測狀態碼；直接查看 grant 錯誤表、分享表錯誤表、洞察讀取錯誤表與洞察更新錯誤表。

試試看

在 API Playground 依序選擇 tags.create、tags.assignTable、chatroomPermissions.grant、tables.shared、insight.systems.get 與 insight.systems.set。

Last updated on
指南總覽連結、彙總與查找