ClickHouse

ClickHouse Cloud以在你組織設定中建立的API金鑰連接。一把API金鑰恰好屬於一個組織，所以一把金鑰連接一個組織，而每個組織只會連接到一個工作區一次。金鑰在儲存前會先加密，代理永遠看不到它們。

1. 開啟ClickHouse Cloud，前往你組織的API Keys。
2. 點擊New API key並選擇Developer（唯讀）角色：Polylane在同步期間只讀取。
3. 複製金鑰ID與金鑰密鑰；密鑰只會顯示一次。
4. 把兩個值都貼到Polylane。
5. Polylane驗證金鑰並開始同步。

Polylane會探索你的服務，包括狀態、層級、區域、雲端供應商、ClickHouse版本、副本規格與連線端點。連線主機名稱用於跨雲端連結，所以透過環境變數觸及某個服務的應用程式會在地圖上連結到它。

當服務處於degraded、failed、stopped或部分執行狀態時，監控會提出問題；idle與waking對於閒置縮放的服務是正常的生命週期，維持健康。ClickHouse Cloud的控制層面把指標回報為沒有歷史的即時快照，所以代理按需讀取目前的值，而服務沒有指標圖表。

疑難排解

「Invalid API key」錯誤

• 金鑰ID與金鑰密鑰都是必要的；單獨任一個都無法驗證。
• 檢查該金鑰是否已在ClickHouse Cloud的API金鑰設定中被刪除或停用。
• 有到期日的金鑰會在到期時停止運作；建立一把新金鑰並在Polylane中輪替它。

缺少資源

• ClickHouse Cloud可能需要幾分鐘才能同步完所有內容。
• 從帳戶標頭觸發手動Sync以重新整理。

速率限制

• ClickHouse Cloud允許每把金鑰每10秒10個API請求。為Polylane準備一把專用金鑰可避免與其他工具共用這個預算。

中斷連接

在Polylane中斷該帳戶的連接，然後從你的ClickHouse Cloud組織設定刪除該API金鑰。

連接ClickHouse Cloud不需要瀏覽器：主控台呼叫的同一個端點可以放進CI工作。一次經過驗證的POST建立連接並開始第一次同步。

先決條件

• 一把具有cloud_accounts:write與cloud_accounts:read範圍的Polylane API金鑰。請見API金鑰與OAuth。
• 你的工作區ID，以ws_開頭。用同一把金鑰從GET /v1/workspaces讀取它。
• 一組來自你組織API Keys的ClickHouse Cloud API金鑰ID與密鑰，以Developer（唯讀）角色建立。

建立連接

curl -X POST https://api.polylane.com/v1/cloud_accounts \
  -H "x-api-key: $POLYLANE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "clickhouse",
    "workspaceId": "ws_0abc123",
    "keyId": "<key-id>",
    "keySecret": "<key-secret>"
  }'

一把API金鑰恰好屬於一個組織，所以一次呼叫連接一個組織。

回應列出已連接的內容，第一次同步已在執行。精簡為流程其餘部分會讀取的兩個欄位：

{
  "success": true,
  "result": {
    "provider": "clickhouse",
    "accounts": [{ "id": "acc_34gky74ibc92h8t2efn8csrh", "status": "syncing" }],
    "failures": []
  }
}

已經連接的帳戶會落在failures而不是accounts中，所以重複呼叫永遠不會重複建立連接。

等待第一次同步

依id輪詢每個回傳的帳戶，直到status達到ready（註冊時為new，資源串流進來時為syncing）：

until [ "$(curl -s "https://api.polylane.com/v1/cloud_accounts/$WORKSPACE_ID/$ACCOUNT_ID" \
  -H "x-api-key: $POLYLANE_API_KEY" | jq -r '.result.status')" = "ready" ]; do
  sleep 15
done

給這個迴圈一個期限，讓失敗的連接讓工作失敗，而不是掛住它。帳戶為ready後，它的資源就在拓樸中，Polylane也已開始第一次檢查。

從API中斷連接

刪除連接會停止所有同步與檢查，並刪除Polylane持有的憑證。這個呼叫需要cloud_accounts:delete範圍：

curl -X DELETE "https://api.polylane.com/v1/cloud_accounts/$WORKSPACE_ID/$ACCOUNT_ID" \
  -H "x-api-key: $POLYLANE_API_KEY"

然後如下方中斷連接一節所述，在供應商端撤銷ClickHouse Cloud憑證。