多くのチームは、いずれドキュメントを他のソフトウェアと連携させたくなります。スクリプトからファイルをアップロードする、スケジューラからワークフローを開始する、ドキュメントの処理が終わった瞬間に通知を受け取る、といった具合です。AuraDocには補い合う2つの方法があります。REST APIは自社システムからAuraDocに依頼するためのもので、Webhookは何かが起きたことをAuraDocが自社システムに知らせるためのものです。この記事では両方と、本番運用で重要なセキュリティの要点を説明します。
APIキーとスコープ
すべてはAPIキーから始まります。Dashboard › Settings › API keys でキーを作成し、名前とスコープを選びます。スコープはキーにできることを制限するため、ファイルのアップロード専用のキーに他の管理権限は不要です。キーは自分より広いスコープを持つ別のキーを作れず、実際に使える権限は常にキーと本人の役割に共通するものになります。詳しくはチームの役割と権限をご覧ください。リクエストでは、キーをAuthorizationヘッダーにBearerトークンとして付けます。
同じページにはキーごとの利用統計が表示されるので、どの連携が活発で、どれが止まっているかが分かります。有料プランでは個々のキーにレート制限を設定でき、騒がしいスクリプトが他に影響しないようにできます。キーが漏れた場合は削除して新しく作成してください。AuraDoc側で他に変更する必要はありません。
APIでできること
ドキュメントの連携ページには、ベースURLとそのまま使える例が載っています。現在は、ドキュメントのアップロード、URLからのドキュメント取り込み、ワークフロー実行の開始、署名依頼の作成を、それぞれ1回の認証付きリクエストで行えます。ダッシュボードで行う操作と同じなので、APIで作成した結果も他のものと同様に画面に表示されます。
呼び出しを受けるよりも定期的に確認したい場合は、新しいドキュメント、完了したワークフロー実行、完了した署名を返すトリガー用エンドポイントと、それらを説明するカタログがあります。表計算のアドオンやノーコード基盤のようにWebhookを受けられないツールは、これらを定期的に確認できます。詳細は連携のドキュメントページにあります。
送信Webhook
リアルタイム通知には、Dashboard › Webhooks を開いてエンドポイントを追加します。ドキュメントの作成、分類、削除、OCRと翻訳の完了または失敗、ワークフローのイベント、ストレージ容量の警告、署名関連のイベントなど、必要なイベントを一覧から選びます。保存時に署名用のシークレットが一度だけ表示されます。すぐに受信側のサービスにコピーしてください。紛失した場合はシークレットをローテーションすると新しいものが生成され、その操作は監査証跡に記録されます。
ペイロードは数千文字までのテンプレートで整形でき、保存前に検証できます。テストボタンはテスト用ヘッダー付きのサンプルイベントを送信するので、本番で頼る前にエンドポイントに届くか、本文を読み取れるかを確認できます。Webhookは削除せずに無効化でき、メンテナンス中に便利です。
署名の検証と障害への対応
すべての配信には署名が付きます。AuraDocはシークレットを使ってタイムスタンプと生の本文に対するHMAC-SHA256を計算し、署名ヘッダーに入れて送ります。あわせて、イベント名、Webhook ID、配信ID、タイムスタンプ、再試行回数のヘッダーも付きます。受信側は生の本文から署名を再計算し、定数時間で比較し、タイムスタンプが古すぎるリクエストを拒否してください。これにより、アドレスを知られていても、エンドポイントへ偽のイベントを送ることはできません。
エンドポイントは停止することがあり、AuraDocはそれを想定しています。配信に失敗すると、5分から6時間まで間隔を延ばしながら自動で再試行します。配信ビューには各試行と結果が表示され、問題を直したあとで手動で再試行もできます。再試行には同じ配信IDが使われるため、受信側は重複を安全に無視できます。ストレージ事業者から届くファイルとの組み合わせは、クラウドストレージと監視フォルダーをご覧ください。