> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dify.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 外部ナレッジベース API

> Dify と統合するために外部ナレッジサービスが実装する必要がある API 仕様

> このドキュメントは AI によって自動翻訳されています。不正確な部分がある場合は、[英語版](/en/cloud/use-dify/knowledge/external-knowledge-api) を参照してください。

このページでは、Dify が外部ナレッジサービスからコンテンツを取得するために実装が必要な API 仕様を定義します。API の準備ができたら、[外部ナレッジベースとの接続](/ja/cloud/use-dify/knowledge/connect-external-knowledge-base)を参照して Dify に登録してください。

## 認証

Dify は API キーを Bearer トークンとしてすべてのリクエストに含めます：

```text theme={null}
Authorization: Bearer {API_KEY}
```

認証ロジックはサービス側で定義します。Dify はキーを送信するのみで検証しません。

## リクエスト

```text theme={null}
POST {your-endpoint}/retrieval
Content-Type: application/json
Authorization: Bearer {API_KEY}
```

Dify は設定されたエンドポイント URL に `/retrieval` を付加します。`https://your-service.com` を登録した場合、`https://your-service.com/retrieval` にリクエストを送信します。

### ボディ

| プロパティ                | 必須  | 型      | 説明                                                                                        |
| :------------------- | :-- | :----- | :---------------------------------------------------------------------------------------- |
| `knowledge_id`       | はい  | string | 外部システム内のナレッジソースの識別子で、接続時に **外部ナレッジベース ID** フィールドに入力した値です。クエリを正しいナレッジソースにルーティングするために使用します。 |
| `query`              | はい  | string | ユーザーの検索クエリです。                                                                             |
| `retrieval_setting`  | はい  | object | 検索パラメータです。[下記](#retrieval_setting)を参照してください。                                              |
| `metadata_condition` | いいえ | object | メタデータのフィルタリング条件です。[下記](#metadata_condition)を参照してください。                                     |

#### `retrieval_setting`

| プロパティ             | 必須 | 型     | 説明                                                    |
| :---------------- | :- | :---- | :---------------------------------------------------- |
| `top_k`           | はい | int   | 返す結果の最大数です。                                           |
| `score_threshold` | はい | float | 最小類似度スコア（0～1）です。Dify でスコアしきい値が無効の場合、この値は `0.0` になります。 |

#### `metadata_condition`

<Info>
  Dify はメタデータ条件を API に渡しますが、現在ユーザーが設定するための UI は提供していません。このパラメータはプログラムからの利用のみ可能です。
</Info>

| プロパティ              | 必須  | 型              | 説明                             |
| :----------------- | :-- | :------------- | :----------------------------- |
| `logical_operator` | いいえ | string         | `and` または `or` です。デフォルト：`and`。 |
| `conditions`       | はい  | array\[object] | フィルタ条件のリストです。                  |

`conditions` 内の各オブジェクト：

| プロパティ                 | 必須  | 型                                | 説明                                           |
| :-------------------- | :-- | :------------------------------- | :------------------------------------------- |
| `name`                | はい  | string                           | フィルタ対象のメタデータフィールド名です。                        |
| `comparison_operator` | はい  | string                           | 比較演算子です。サポートされる値は下記を参照してください。                |
| `value`               | いいえ | string、number、または array\[string] | 比較値です。`empty` または `not empty` を使用する場合は省略します。 |

<Accordion title="サポートされる比較演算子">
  | 演算子            | 説明                |
  | :------------- | :---------------- |
  | `contains`     | 値を含む              |
  | `not contains` | 値を含まない            |
  | `start with`   | 値で始まる             |
  | `end with`     | 値で終わる             |
  | `is`           | 値と等しい             |
  | `is not`       | 値と等しくない           |
  | `in`           | リスト内のいずれかの値に一致    |
  | `not in`       | リスト内のいずれの値にも一致しない |
  | `empty`        | 空である              |
  | `not empty`    | 空ではない             |
  | `=`            | 等しい（数値）           |
  | `≠`            | 等しくない（数値）         |
  | `>`            | より大きい             |
  | `<`            | より小さい             |
  | `≥`            | 以上                |
  | `≤`            | 以下                |
  | `before`       | 指定日より前            |
  | `after`        | 指定日より後            |
</Accordion>

### リクエスト例

```json theme={null}
{
    "knowledge_id": "your-knowledge-id",
    "query": "Dify とは何ですか？",
    "retrieval_setting": {
        "top_k": 3,
        "score_threshold": 0.5
    }
}
```

## レスポンス

HTTP 200 と `records` 配列を含む JSON ボディを返します。一致する結果がない場合は、空の配列を返してください：`{"records": []}`。

### `records`

| プロパティ      | 型      | 説明                                               |
| :--------- | :----- | :----------------------------------------------- |
| `content`  | string | 取得されたテキストチャンクです。Dify はこれを LLM に渡すコンテキストとして使用します。 |
| `score`    | float  | 類似度スコア（0～1）です。スコアしきい値によるフィルタリングと結果のランキングに使用します。  |
| `title`    | string | ソースドキュメントのタイトルです。                                |
| `metadata` | object | Dify が保持する任意のキーバリューペアです。                         |

Dify はフィールドが欠落したレコードを拒否しませんが、`content` や `score` を省略すると不完全またはランキングされない結果になります。

<Warning>
  レコードに `metadata` を含める場合、オブジェクト（`{}`）である必要があります。`null` は Dify の検索パイプラインでエラーを引き起こします。
</Warning>

### レスポンス例

```json theme={null}
{
    "records": [
        {
            "content": "これは外部ナレッジベースのドキュメントです。",
            "score": 0.98,
            "title": "knowledge.txt",
            "metadata": {
                "path": "s3://dify/knowledge.txt",
                "description": "dify ナレッジドキュメント"
            }
        },
        {
            "content": "GenAI アプリケーションのイノベーションエンジン",
            "score": 0.66,
            "title": "introduce.txt",
            "metadata": {}
        }
    ]
}
```

## エラーハンドリング

Dify はレスポンスの HTTP ステータスコードを確認します。200 以外のステータスはユーザーに表示されるエラーを発生させます。

JSON で構造化されたエラー情報を返すこともできます：

| プロパティ        | 型      | 説明                           |
| :----------- | :----- | :--------------------------- |
| `error_code` | int    | 独自に定義するアプリケーションレベルのエラーコードです。 |
| `error_msg`  | string | 人間が読めるエラーの説明です。              |

以下は推奨されるエラーコードです。これらは慣例であり、Dify による強制ではありません：

| コード  | 推奨される用途                  |
| :--- | :----------------------- |
| 1001 | Authorization ヘッダーの形式が不正 |
| 1002 | 認証失敗                     |
| 2001 | ナレッジベースが見つからない           |

### エラーレスポンス例

```json theme={null}
{
    "error_code": 1002,
    "error_msg": "Authorization failed. Please check your API key."
}
```