大多數團隊遲早會希望文件能與其他軟體對話:用指令碼上傳檔案、由排程器啟動工作流程,或在文件處理完成的瞬間收到通知。AuraDoc 提供兩種互補的方式。REST API 讓你的系統請求 AuraDoc 做某件事,Webhook 則讓 AuraDoc 通知你的系統某件事已經發生。本文介紹這兩者,以及在正式環境中真正重要的安全細節。
API 金鑰與範圍
一切從 API 金鑰開始。在 Dashboard › Settings › API keys 中建立金鑰,命名並選擇範圍。範圍限制了金鑰能做什麼,因此只用於上傳檔案的金鑰不需要管理其他內容的權限。金鑰無法建立範圍比自身更大的另一個金鑰,實際生效的權限始終是金鑰與此人角色的交集,詳見團隊角色與權限。請求透過 Authorization 標頭以 Bearer 權杖的形式攜帶金鑰。
同一頁面會顯示每個金鑰的使用統計,方便看出哪個整合很活躍、哪個已經沉寂。在付費方案中,還可以為單一金鑰設定速率限制,避免某個指令碼過於頻繁而影響其他指令碼。如果金鑰外洩,刪除它並建立新的即可,AuraDoc 這一側無需其他變更。
API 能做什麼
文件中的整合頁面列出了基礎位址,並提供可直接複製的範例。目前你可以上傳文件、讓 AuraDoc 從 URL 匯入文件、啟動一次工作流程執行以及建立簽署請求,每項都只需一個經過驗證的請求。這些與人們在控制台中執行的操作相同,所以透過 API 建立的結果與其他內容一樣出現在介面中。
如果你更願意輪詢而不是接收呼叫,可以使用觸發器端點,它們會回傳新文件、已完成的工作流程執行與已完成的簽署,並附有描述這些端點的目錄。無法接收 Webhook 的工具,例如試算表外掛或無程式碼平台,可以定期查詢這些端點。完整參考見整合文件頁面。
外送 Webhook
如需即時通知,請開啟 Dashboard › Webhooks 並新增一個端點。你可以從清單中選擇關心的事件,包括文件建立、分類與刪除,OCR 與翻譯完成或失敗,工作流程事件,儲存配額預警以及簽署相關事件。儲存時,AuraDoc 只會顯示一次簽章密鑰。請立即複製到接收服務中;如果遺失,可以輪替密鑰,系統會產生新的密鑰,並在稽核紀錄中留下輪替記錄。
你可以用範本(最多數千字元)來調整內容,並在儲存前進行驗證。測試按鈕會傳送帶有測試標頭的範例事件,讓你在依賴它之前確認端點可連線並能解析請求本文。每個 Webhook 都可以停用而無需刪除,這在維護時段很有用。
驗證簽章與處理故障
每次傳送都帶有簽章。AuraDoc 使用你的密鑰,對時間戳記與原始請求本文計算 HMAC-SHA256,並把結果放在簽章標頭中,同時附帶事件名稱、Webhook ID、傳送 ID、時間戳記與重試次數的標頭。接收方應根據原始請求本文重新計算簽章,以恆定時間進行比較,並拒絕時間戳記過舊的請求。這樣即使別人知道端點位址,也無法向你的端點偽造事件。
端點可能當機,AuraDoc 對此有準備。傳送失敗後會自動重試,間隔逐步加長,從五分鐘到六小時。傳送檢視會顯示每次嘗試及其結果,問題修復後你也可以手動觸發重試。由於重試沿用同一個傳送 ID,接收方可以放心忽略重複項目。若要把 Webhook 與來自儲存服務供應商的檔案結合使用,請參閱雲端儲存與監控資料夾。