本文へスキップ
Sursa Developers

クイックスタート

このガイドでは、何もない状態から5分で動く連携システムを作ります。APIキーを作成して確認し、ナレッジベースにドキュメントを追加し、それを検索し、その内容について質問します。どの手順も1回のHTTPリクエストです。どれかの例で言語を一度選ぶと、ページのすべての例がその言語に切り替わります。

言語の切り替えがある例では、このポータルのAPIアドレスを使います。Sursaのクラウドではhttps://api.sursa.com、自社のインストール環境ではそのAPIアドレスです。例にhttps://api.example.comとある場合は、自分のAPIアドレスに置き換えてください。どのアドレスかわからない場合は、APIアドレスと環境を参照してください。

1. APIキーを作成する

組織の管理者は、SursaのAdministration → API keys（管理 → APIキー）でキーを作成します。キーには使用場所がわかる名前（たとえば「CRM sync」）を付け、ロールを選び、さらに狭めたい場合はスコープを選びます。キーは、そのロールのユーザーができることを、スコープで許可された範囲内で行えます。このガイドではeditorロールで十分です。

キーは一度だけ表示されます。自社のシステムのシークレットストアに保管し、環境変数でコードに渡してください。

export SURSA_API_KEY="kb_…"

すべてのリクエストは、キーをAuthorizationヘッダーでBearerトークンとして送信します。ロール、スコープ、有効期限、ローテーションについては、APIキーとスコープで説明しています。

2. クライアントを設定する

ライブラリは必要ありません。APIは普通のHTTPSとJSONです。このガイドの例では、各言語の小さなヘルパーを使います。自分の言語のヘルパーをコピーしてください。以降のガイドでも同じヘルパーを使います。公式のクライアントライブラリはSDKに掲載されています。

# cURL needs no setup: each example below is a complete command.
export SURSA_API="https://api.sursa.com"

3. キーを確認する

GET /v1/meは呼び出し元を説明します。組織、キー、そのロールとスコープ、適用されるレート制限を返します。有効なキーであればどれでも動作するので、どの連携システムでも最初のリクエストに最適です。

curl https://api.sursa.com/v1/me \
  -H "Authorization: Bearer $SURSA_API_KEY"
{
  "principal": "api_key",
  "org": {"id": 1, "slug": "acme", "name": "Acme"},
  "key": {"id": 42, "name": "CRM sync", "prefix": "kb_3f9c", "role": "editor"},
  "user": null,
  "role": "editor",
  "scopes": ["cards:read", "cards:write", "search", "ask"],
  "data_profile": null,
  "expires_at": null,
  "rate_limit": {"class": "standard", "requests_per_second": 20, "burst": 100}
}

コードauth.not_authenticatedの401は、キーがない、取り消されている、または入力ミスがあることを意味します。api_keys.expiredは、キーの有効期限が切れたことを意味します。

4. コレクションを探す

カードはコレクションの中にあります。GET /v1/collectionsは、キーで参照できるコレクションを一覧表示します。

curl https://api.sursa.com/v1/collections \
  -H "Authorization: Bearer $SURSA_API_KEY"

作業に使うコレクションのidとnameを控えておいてください。以下の例では、supportという名前のコレクション3を使います。

5. ドキュメントを追加する

PUT /v1/cards-by-external-id/{external_id}は、自社のIDでカードを作成します。カードがすでに存在する場合は置き換えます。リクエストを2回実行しても安全です。2回目は内容が変わっていないので、理由unchangedとともにskippedが返ります。external_idには、自社のシステムのレコードのIDを使ってください。

curl -X PUT https://api.sursa.com/v1/cards-by-external-id/policy-refunds \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "collection_id": 3,
    "title": "Refund policy",
    "content_type": "markdown",
    "body": "# Refund policy\n\nRefunds are processed within 14 days of the request."
  }'

リクエストは、カードが検索できる状態になると応答します。新しいカードでは"status": "ready"とともに201、置き換えたカードでは200が返ります。HTMLとプレーンテキストも、"content_type": "html"または"text"で同じように扱えます。ファイル（PDF、Word、Excelなど）は、同じエンドポイントにmultipart/form-dataで送信します。ファイル、フォルダー、メタデータ、多数のドキュメントのインポートについては、ドキュメントをインポートするで説明しています。

POST /v1/searchは、クエリに一致するカードの抜粋を、一致度の高い順に見つけます。

curl -X POST https://api.sursa.com/v1/search \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "refund policy", "collection": "support"}'

collectionにはコレクションの名前を指定します。指定しない場合は、defaultという名前のコレクションが検索の対象になります。

7. 質問する

POST /v1/askは、普通の言葉で書かれた質問に回答し、回答の出典を返します。アシスタントは関連するナレッジを見つけ、キーで読み込めるカードだけをもとに回答します。

curl -X POST https://api.sursa.com/v1/ask \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "How long does a refund take?", "collection": "support"}'

関連するものが見つからなかった場合も、レスポンスは200で、"empty": "no_hits"と、answerの短い説明が返ります。その場合にユーザーに何を表示するかは、コードで決めてください。

次のステップ