名前空間の公開エンドポイント

名前空間 は、独自の公開エンドポイントを公開できます。1 つの URL で、その名前空間内の複数インスタンスを横断して検索し、結果をマージします。ドキュメント、ブログ、サポートポータルなど、複数インスタンスに分かれたコンテンツを 1 つの検索体験で扱う場合に使います。

名前空間エンドポイントは、インスタンスエンドポイントと同じパスを提供し、同じ設定を受け付けます。カスタムドメイン と Cloudflare Access も含みます。公開エンドポイントの設定 を参照してください。このページでは、名前空間固有の内容を扱います。

名前空間に public_endpoint_params を設定し、公開するインスタンスを instances_allowed に列挙します。

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/ai-search/namespaces/<NAMESPACE>" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "public_endpoint_params": {
      "enabled": true,
      "instances_allowed": ["docs", "blog", "support"]
    }
  }'

レスポンスは生成された public_endpoint_id を返します。名前空間のホスト名には ns- プレフィックスが付きます。

https://ns-<NAMESPACE_ENDPOINT_ID>.search.ai.cloudflare.com/search

名前空間エンドポイントを有効にしても、内包するインスタンスエンドポイントは変わりません。それぞれを個別に有効・無効にします。

instances_allowed は、エンドポイントが到達できるインスタンスを制御します。

• 各エントリは、その名前空間に存在するインスタンスである必要があります。不明なエントリはエラー 7097 を返します。
• リストには最大 10 インスタンスまで入ります。
• 空リストは、検索対象がないことを意味します。エンドポイントを初めて有効にしたときの初期状態です。
• インスタンスを削除するか、別の名前空間へ移すと、許可リストから外れます。

検索可能なインスタンスに解決できないリクエストは、エラー 60013 の 404 を返します。この応答は、インスタンスが存在しない、許可リスト外、許可リストが空、のいずれでも同じです。呼び出し側は、名前空間にどのインスタンスがあるかを発見できません。

デフォルトでは、リクエストは許可リスト内の全インスタンスを検索します。1 リクエストの範囲を狭めるには、リクエスト本文で ai_search_options.instance_ids を設定します。

curl https://ns-<NAMESPACE_ENDPOINT_ID>.search.ai.cloudflare.com/search \
  --header "Content-Type: application/json" \
  --data '{
    "messages": [
      {
        "content": "How do I configure AI Search?",
        "role": "user"
      }
    ],
    "ai_search_options": {
      "instance_ids": ["docs", "support"]
    }
  }'

各値は許可リストに含まれている必要があります。このフィールドの規則は次のとおりです。

• フィールドを省略するか null にすると、許可リスト全体を検索します。
• 空配列や文字列以外のエントリなど、不正な値はエラー 60012 の 400 を返します。
• 許可リスト外の値は、エラー 60013 の 404 を返します。

public_endpoint_params を null にします。設定は消え、トラフィックの配信は止まりますが、識別子は残るため、再度有効にすると同じ URL を再利用できます。

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/ai-search/namespaces/<NAMESPACE>" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "public_endpoint_params": null
  }'