把檢視公開出去

目標：讓外部網頁顯示某張自訂表格的即時資料，不需要登入，也不需要你自己架後端。流程是：先做出檢視、對它鑄造權杖、確認匿名讀者實際看到什麼，最後撤銷。撤銷是這個任務的一部分，不是事後才想的事。

以下都假設你是這張表的管理者。每個步驟背後的完整合約見公開讀取。

1. 先做出要公開的檢視

公開的對象永遠是檢視，不是資料表。檢視是你決定「哪些列、哪些欄」的地方，也是之後可以安全調整的東西。


curl -X POST \
  "$BASE_URL/private/module/custom_tables/chatroom/11111111-1111-4111-8111-111111111111/tables/22222222-2222-4222-8222-222222222222/views" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "已上架品項",
    "config": {
      "filters": { "已上架": { "eq": true } },
      "columns": ["品項", "單價", "分類"],
      "sort": [{ "column": "分類", "direction": "asc" }]
    }
  }'

設計時有兩個限制要遵守。檢視不能帶 computed_filters，sort 與 sort_by 也不能指到 link、rollup、lookup、formula 欄位：這種檢視無法公開，而且如果你事後才加上去，已公開的 URL 會直接停止服務。另外，受 SCP channel 規則治理的資料表完全不能公開，所以如果這張表受 channel 治理，就到此為止，改公開一份不受治理的副本。

2. 鑄造權杖


curl -X POST \
  "$BASE_URL/private/module/custom_tables/chatroom/tables/22222222-2222-4222-8222-222222222222/public-read-tokens" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "官網價目表",
    "view_id": "33333333-3333-4333-8333-333333333333",
    "secretless": true,
    "visible_columns": ["品項", "單價"],
    "allow_query": false,
    "rpm": 120,
    "valid_until": null
  }'

注意鑄造路徑沒有 scope id 那一段。有三件事要刻意決定：

secretless。 true 表示 URL 就是憑證，這是公開網頁需要的形式。false 會產生只顯示一次的 Bearer 密鑰，適合伺服器對伺服器的使用者。
visible_columns。 這是一份允許清單，會與檢視的欄位取交集。檢視裡放了 分類、但這裡不列它，就能「用它過濾但不顯示它」。
allow_query。 除非使用端真的需要在檢視之外再過濾、排序或分頁，否則保持 false。這是「公開一個頁面」與「公開一個小型查詢 API」的差別。

如果你鑄造的是帶密鑰的權杖，現在就把密鑰存起來，之後不會再顯示。

3. 以匿名讀者的身分驗證

在完全不帶 Authorization 標頭的環境下執行，並且要看回傳內容，不要只看狀態碼：


curl "$BASE_URL/public/module/custom_tables/read/44444444-4444-4444-8444-444444444444/records?limit=5"

檢查四件事：

columns 只列出你打算公開的欄位。
每一列都沒有 created_by、pending_approval，也沒有除 id 以外的任何 id。如果看到別的東西，先停下來，回去讀公開讀取再上線。
有公開的 formula 欄位要有真正的值，而不是 null。輸入被隱藏或跨表的公式在這條通道上會解析成 null。
有公開的 user 或 social_client 欄位顯示的是原始 id，這通常不是你想放在公開頁面上的東西。除非那個 id 本來就該公開，否則把它從 visible_columns 移除。

如果拿到 404，除錯要從私有側做：列出這張表的權杖，確認它沒有被撤銷或過期，然後重新打開檢視，確認它仍然沒有跨表計算語法。

4. 交出 URL 時，把它當成憑證

無密鑰權杖的 uuid 就是全部的憑證。把它放在頁面的伺服器端設定或建置產物裡，不要放進公開的 repository，也不要貼在工單裡。它沒辦法收回，只能撤銷。

5. 輪替與撤銷

輪替的順序是：鑄造、部署、驗證、撤銷。


curl -X DELETE \
  "$BASE_URL/private/module/custom_tables/chatroom/tables/22222222-2222-4222-8222-222222222222/public-read-tokens/44444444-4444-4444-8444-444444444444" \
  -H "Authorization: Bearer $TOKEN"

撤銷是永久的：資料列會留著並標記 revoked: true，URL 永遠失效，所以誤撤就只能鑄造新的 URL 並重新部署使用端。撤銷前先看權杖列表裡的 last_used_at，確認是不是還有人在讀。

讓它進版控

形狀確定之後，用 JSONL 文件宣告這個權杖，下一個環境就會得到同樣的公開設定，不必再手動鑄造：


{"kind":"view","table":"prices","ref":"published_items","spec":{"name":"已上架品項","config":{"filters":{"已上架":{"eq":true}},"columns":["品項","單價","分類"]}}}
{"kind":"public_read","table":"prices","ref":"website_price_list","spec":{"view":"published_items","secretless":true,"visible_columns":["品項","單價"],"rpm":120,"allow_query":false}}

IaC 公開只支援無密鑰，view 必須是受管理的檢視（上面那行 view 就滿足這個條件），而重複 apply 會就地更新權杖，所以 URL 保持不變。把 public_read 行設成 state: "absent" 就是撤銷。詳見 public_read 行類型。