Dvina MCP

使用 API 存取

為指令碼和 MCP 用戶端建立個人存取權杖，並透過 webhook 將 Livespace 的事件傳送至你自己的系統。

在「設定」› API 存取中，你可以建立個人存取權杖，讓指令碼或 MCP 用戶端以你的身分使用 Dvina。管理員也可以在這裏新增 webhook，將 Livespace 的事件傳送至自己的系統。

API 存取功能包含在 Enterprise 方案內。每位成員都可以建立自己的權杖；只有擁有者和管理員能看到 Webhook。

建立權杖

  1. 開啟「設定」，然後選擇 API 存取。
  2. 在個人存取權杖下，選擇建立權杖。
  3. 輸入名稱，方便日後辨認哪些程式正在使用這個權杖。
  4. 選擇存取權限：唯讀或讀取及寫入。
  5. 選擇到期時間：30 天後、90 天後、365 天後或永不到期。
  6. 選擇建立權杖。
  7. 在複製你的權杖下，複製權杖並妥善保存。權杖只會顯示這一次。

權杖會在你建立它的 Livespace 中，以你的身分及你目前在該 Livespace 的角色運作。唯讀權杖可以讀取內容，但不能新增或更改任何內容。

如要在 MCP 用戶端使用權杖，請參閱使用 API 金鑰而非 OAuth 連線。

查看、輪替或撤銷權杖

你的權杖及其存取權限會列在個人存取權杖下。選擇一個權杖，即可查看其開頭字元、存取權限、上次使用時間及到期時間。

  • 如要更換權杖，請選擇輪替…，然後選擇輪替以確認。新權杖會取代舊權杖，而舊權杖會立即失效。在複製你的權杖下複製新權杖。
  • 如要停用權杖，請選擇撤銷…，然後選擇撤銷以確認。所有使用該權杖的程式都會立即停止運作。

建立、輪替和撤銷權杖的操作都會記錄在稽核記錄中。

新增 webhook

Webhook 會將 Livespace 的事件傳送至你指定的網址。這些事件與稽核記錄中的記錄相同。

  1. 在「設定」› API 存取的 Webhook 下，選擇新增 Webhook。
  2. 輸入名稱和 URL。請使用公開的 HTTPS URL。
  3. 在事件下，留空即可接收所有事件，或列出操作和範圍，例如 member.added 或 sharing.*。
  4. 選擇新增。
  5. 在複製簽署密鑰下，複製密鑰。密鑰只會顯示這一次。

如果 Dvina 顯示 Dvina 無法連線至此網址，請使用公開的 HTTPS URL。

檢查每個請求的簽章

Dvina 會以 JSON 格式分批傳送事件，並為每個請求簽署。使用簽署密鑰來確認請求是否來自 Dvina：

  • 每個請求都有一個 X-Dvina-Signature 標頭，格式如 t=<timestamp>,v1=<signature>。
  • 簽章是將時間戳記、句點和請求主體串接後，使用你的簽署密鑰產生的 HMAC-SHA256，以十六進位表示。
  • 自行計算簽章並比較。如果請求的簽章不符，或時間戳記過舊，請拒絕該請求。

查看或更改 webhook

你的 webhook 會列在 Webhook 下，並顯示狀態：已開啟、已暫停或傳送失敗。選擇其中一個即可查看詳細資料。

  • 如要更改 webhook，請編輯其名稱、URL或事件，然後選擇儲存。
  • 如要暫停 webhook，請關閉傳送事件。再次開啟即可恢復傳送。
  • 如要查看運作情況，請查看其狀態和已傳送的事件數量。傳送失敗的 webhook 會顯示其最近一次錯誤。Dvina 會持續重試，並在稽核記錄中記錄失敗情況。
  • 如要更改簽署密鑰，請選擇新增簽署密鑰…，然後確認。系統會立即使用新密鑰簽署請求，因此請立即更新接收端。
  • 如要移除 webhook，請選擇刪除…，然後選擇刪除以確認。系統將不再向它傳送任何內容。