Zapier、Make、n8nと連携する

連携プラットフォームを使うと、コードを書かずにSursaを数百の他のツールにつなげます。Sursa専用のアプリは必要ありません。プラットフォームの汎用のHTTPリクエストとWebhookのステップが、APIと直接連携します。このガイドでは、よく使われる3つのレシピを説明します。

どのプラットフォームでも、キーはステップの中ではなく、プラットフォームの認証情報や接続の保管場所に入れてください。そうすれば、すべてのシナリオや実行ログにキーがコピーされることはありません。

レコードをカードとして送信する

Sursaでカスタムソースを作成し（Sources → New source → Custom source（ソース → 新しいソース → カスタムソース））、ソースのページのAPI keys（APIキー）でそのソースのキーを作成します。キーはkbsrc_で始まり、このソースにドキュメントを書き込むことしかできないので、第三者のプラットフォームに保管するキーとして適しています。

よくある設定は「Xでレコードが作成または更新されたら、Sursaに送信する」です。

{
  "external_id": "{{record_id}}",
  "title": "{{record_title}}",
  "content": "{{record_body_html}}",
  "content_type": "html",
  "url": "{{record_link}}",
  "path": "{{record_category}}",
  "updated_at": "{{record_updated_at}}"
}

• external_idには、時刻や実行番号ではなく、レコードの安定したIDを対応付けてください。そうすれば、同じレコードをもう一度送信しても同じカードが更新され、ステップの再試行も無害です。応答はunchangedになります。
• 「レコードが削除された」トリガーには、メソッドDELETE、URLhttps://api.example.com/v1/push/sources/42/documents/{{record_id}}の2つ目のワークフローを追加します。
• 接続は、同じAuthorizationヘッダーを付けたGET https://api.example.com/v1/push/sources/42でテストします。ソースの名前とドキュメントの数が返ります。

ドキュメントのフィールドは、コードから送信する場合と同じです。

Zapier

Webhooks by Zapier → Custom Requestを使います。

• Method: POST。
• URL: https://api.example.com/v1/push/sources/42/documents。
• Data Pass-Through: オフ。Data: 上のJSON。フィールドはトリガーから挿入します。
• Headers: Authorization = Bearer kbsrc_…、Content-Type = application/json。

Make

モジュールHTTP → Make a requestを使います。

• MethodはPOST、URLは上と同じ、HeadersはAuthorization: Bearer kbsrc_…。
• Body typeはRaw、Content typeはJSON (application/json)、Request contentは値を対応付けた上のJSON。
• 後のモジュールでresult（created、updated、unchanged）を使うには、Parse responseをオンにします。
• ファイルを送信するには、Body typeでMultipart/form-dataを選び、fileフィールド（前のモジュールのファイル）と、contentを除いたJSONのフィールドを入れたdocumentテキストフィールドを指定します。

n8n

ノードHTTP Requestを使います。

• MethodはPOST、URLは上と同じ。
• AuthenticationはGeneric Credential Type → Header Authで、名前はAuthorization、値はBearer kbsrc_…。
• Send Bodyをオン、Body Content TypeはJSON、フィールドは{{ $json.id }}のような式で対応付けます。

定期的な完全エクスポートでは、3つのHTTP Requestノードをつなぎます。同期を開始し（初回は{"type": "initial"}、以降は{"type": "incremental"}でPOST …/syncs）、項目を送信し、{"status": "complete"}で同期を終了します。n8nはノードを項目ごとに1回実行します。リクエストの数を減らすには、Aggregateノードで項目をまとめ、{"sync_number": …, "documents": [...]}として…/documents/batchに送信してください。

ワークフローで質問する

ワークフローからSursaに質問し、その回答を使えます。サポートチケットへの返信の下書き、CRMのレコードへの情報の追加、チャットチャンネルへの回答の投稿などです。askスコープと、適切なコレクションを参照できるロールを持つ組織のAPIキーを使ってください。

レスポンスでは、answerに回答（Markdown）が、sourcesにその出典が入り、出典にはそれぞれdoc_nameがあります。ナレッジベースに質問に関する情報がないときは、emptyが設定されます（たとえばno_hits）。ワークフローが空の回答を投稿しないように、フィルターのステップを追加してください。Q&Aボットを作るを参照してください。

回答には数秒かかることがあります。プラットフォームのHTTPステップのデフォルトのタイムアウトが短い場合は、60秒以上に延ばしてください。

Sursaのイベントでワークフローを開始する

どのプラットフォームもWebhookを受信できます。

1. トリガーを作成し、表示されたHTTPSのアドレスをコピーします。
2. SursaのAdministration → Integrations → Webhooks and API（管理 → 連携 → Webhook）またはPOST /v1/webhooksで、そのアドレスと受信したいイベントを指定してWebhookを登録します。
3. Webhookのページからテストイベントを送信し、次のステップでイベントのフィールド（type、data.card.title、…）を対応付けます。

署名を確認する。トリガーのアドレスは公開されています。アドレスを知った人なら誰でもリクエストを送信できます。特にワークフローがデータを変更する場合は、各配信に対応する前にその署名を検証してください。

• n8nでは、Webhookノードの後にCodeノードを追加し、Webhookを受信するのNode.jsの署名検証コードを入れます。正確なバイト列を使えるように、Webhookノードの生のボディのオプションを有効にしてください。
• 生のボディを取得しにくいZapierとMakeでは、少なくともアドレスを秘密にし、typeで絞り込み、対応する前にAPIからオブジェクトを読み込み直してください。

再試行と重複は、他の受信サーバーと同じくプラットフォームにも当てはまります。重複した実行が害になる場合は、イベントのidで絞り込んでください。

ヒント

• 429では、プラットフォームの自動再試行にRetry-Afterの秒数だけ待たせてください。大量のエクスポートにはバッチを使ってください。
• プラットフォームはすべてのリクエストとレスポンスをログに残します。キーを決してURLに含めず、ワークフローがドキュメントを書き込むだけの場合は、できるだけkbsrc_のキーを使ってください。
• ステップが401 sources.push_key_invalidで失敗した場合は、URLのソースIDがキーと一致しているか確認してください。