🌐 Sync PR #737 translations: docs: rewrite external knowledge base documentation

ja/use-dify/knowledge/external-knowledge-api.mdx

@@ -1,177 +1,172 @@
 ---
-title: 外部知識API
+title: 外部ナレッジAPI
+description: Difyと統合するために外部ナレッジサービスが実装する必要があるAPI仕様
 ---
 
 <Note> ⚠️ このドキュメントはAIによって自動翻訳されています。不正確な部分がある場合は、[英語版](/en/use-dify/knowledge/external-knowledge-api)を参照してください。</Note>
 
-## エンドポイント
+このページでは、Difyが外部ナレッジサービスからコンテンツを取得するために実装する必要があるAPIコントラクトを定義します。APIの準備ができたら、[外部ナレッジベースへの接続](/ja/use-dify/knowledge/connect-external-knowledge-base)を参照してDifyに登録してください。
 
-```
-POST <your-endpoint>/retrieval
-```
+## 認証
 
-## ヘッダー
+Difyは、設定したAPIキーをBearerトークンとしてすべてのリクエストで送信します：
 
-このAPIは、Difyとは独立して開発者が維持管理するナレッジベースに接続するために使用されます。詳細については、[外部ナレッジベースへの接続](/ja/use-dify/knowledge/connect-external-knowledge-base)を参照してください。`Authorization` HTTPヘッダーで `API-Key` を使用して権限を検証できます。認証ロジックは、以下のように検索APIで定義します：
-
-```
+```text
 Authorization: Bearer {API_KEY}
 ```
 
-## リクエストボディ要素
-
-リクエストは以下のJSON形式のデータを受け入れます。
-
-| プロパティ | 必須 | 型 | 説明 | 例値 |
-|------------|------|-----|------|------|
-| knowledge_id | TRUE | string | ナレッジベースの一意ID | AAA-BBB-CCC |
-| query | TRUE | string | ユーザーのクエリ | Difyとは何ですか？ |
-| retrieval_setting | TRUE | object | 知識の検索パラメータ | 以下参照 |
-| metadata_condition | TRUE | object | 元の配列のフィルタリング | 以下参照 |
-
-`retrieval_setting` プロパティは以下のキーを含むオブジェクトです：
+認証ロジックは開発者側で定義します。Difyはキーを渡すだけで、検証は行いません。
 
-| プロパティ | 必須 | 型 | 説明 | 例値 |
-|------------|------|-----|------|------|
-| top_k | TRUE | int | 検索結果の最大数 | 5 |
-| score_threshold | TRUE | float | クエリに対する結果の関連性スコアの閾値、範囲：0〜1 | 0.5 |
+## リクエスト
 
-`metadata_condition` プロパティは以下のキーを含むオブジェクトです：
-
-| 属性 | 必須かどうか | 型 | 説明 | 例 |
-|------|----------|------|------|--------|
-| logical_operator | いいえ | 文字列 | 論理演算子、値は `and` または `or`、デフォルトは `and` | and |
-| conditions | はい | 配列（オブジェクト） | 条件リスト | 以下参照 |
-
-`conditions` 配列の各オブジェクトには以下のキーが含まれます：
-
-| 属性 | 必須かどうか | 型 | 説明 | 例 |
-|------|----------|------|------|--------|
-| name | はい | 配列（文字列） | フィルタリングするmetadataの名前 | `["category", "tag"]` |
-| comparison_operator | はい | 文字列 | 比較演算子 | `contains` |
-| value | いいえ | 文字列 | 比較値、演算子が `empty`、`not empty`、`null`、`not null` の場合は省略可能 | `"AI"` |
-
-サポートされている `comparison_operator` 演算子：
-
-- `contains`：特定の値を含む
-- `not contains`：特定の値を含まない
-- `start with`：特定の値で始まる
-- `end with`：特定の値で終わる
-- `is`：特定の値と等しい
-- `is not`：特定の値と等しくない
-- `empty`：空である
-- `not empty`：空ではない
-- `=`：等しい
-- `≠`：等しくない
-- `>`：より大きい
-- `<`：より小さい
-- `≥`：以上
-- `≤`：以下
-- `before`：特定の日付より前
-- `after`：特定の日付より後
+```text
+POST {your-endpoint}/retrieval
+Content-Type: application/json
+Authorization: Bearer {API_KEY}
+```
 
-## リクエスト構文
+Difyは設定したエンドポイントURLに`/retrieval`を追加します。`https://your-service.com`を登録した場合、Difyは`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`、`null`、または`not null`を使用する場合は省略。 |
+
+<Accordion title="サポートされている比較演算子">
+
+| 演算子 | 説明 |
+|:---------|:------------|
+| `contains` | 値を含む |
+| `not contains` | 値を含まない |
+| `start with` | 値で始まる |
+| `end with` | 値で終わる |
+| `is` | 値と等しい |
+| `is not` | 値と等しくない |
+| `in` | リスト内のいずれかの値に一致 |
+| `not in` | リスト内のいずれの値にも一致しない |
+| `empty` | 空である |
+| `not empty` | 空ではない |
+| `=` | 等しい（数値） |
+| `≠` | 等しくない（数値） |
+| `>` | より大きい |
+| `<` | より小さい |
+| `≥` | 以上 |
+| `≤` | 以下 |
+| `before` | 日付より前 |
+| `after` | 日付より後 |
+
+</Accordion>
+
+### リクエスト例
 
 ```json
-POST <your-endpoint>/retrieval HTTP/1.1
--- ヘッダー
-Content-Type: application/json
-Authorization: Bearer your-api-key
--- データ
 {
     "knowledge_id": "your-knowledge-id",
-    "query": "your question",
-    "retrieval_setting":{
-        "top_k": 2,
+    "query": "What is Dify?",
+    "retrieval_setting": {
+        "top_k": 3,
         "score_threshold": 0.5
     }
 }
 ```
 
-## レスポンス要素
+## レスポンス
 
-アクションが成功した場合、サービスはHTTP 200レスポンスを返します。
+`records`配列を含むJSONボディとともにHTTP 200を返します。クエリに一致する結果がない場合は、空の配列を返します：`{"records": []}`。
 
-サービスは以下のデータをJSON形式で返します。
+### `records`
 
-| プロパティ | 必須 | 型 | 説明 | 例値 |
-|------------|------|-----|------|------|
-| records | TRUE | List[Object] | ナレッジベースのクエリ結果のレコードリスト | 以下参照 |
+| プロパティ | 型 | 説明 |
+|:---------|:-----|:------------|
+| `content` | string | 取得したテキストチャンク。DifyはこれをLLMに渡すコンテキストとして使用します。 |
+| `score` | float | 類似度スコア（0–1）。スコアしきい値フィルタリングと結果のランキングに使用されます。 |
+| `title` | string | ソースドキュメントのタイトル。 |
+| `metadata` | object | Difyによって保持される任意のキーと値のペア。 |
 
-`records` プロパティは以下のキーを含むリストオブジェクトです：
+Difyはフィールドが欠落しているレコードを拒否しませんが、`content`または`score`を省略すると、不完全またはランク付けされていない結果が生成されます。
 
-| プロパティ | 必須 | 型 | 説明 | 例値 |
-|------------|------|-----|------|------|
-| content | TRUE | string | ナレッジベースのデータソースからのテキストチャンクを含む | Dify：GenAIアプリケーションのイノベーションエンジン |
-| score | TRUE | float | クエリに対する結果の関連性スコア、範囲：0〜1 | 0.5 |
-| title | TRUE | string | ドキュメントタイトル | Dify紹介 |
-| metadata | FALSE | json | データソース内のドキュメントのメタデータ属性とその値を含む | 例参照 |
+<Warning>
+レコードに`metadata`を含める場合、それは`null`ではなくオブジェクト（`{}`）である必要があります。`null`のメタデータ値はDifyの検索パイプラインでエラーを引き起こします。
+</Warning>
 
-## レスポンス構文
+### レスポンス例
 
 ```json
-HTTP/1.1 200
-Content-type: application/json
 {
-    "records": [{
-                    "metadata": {
-                            "path": "s3://dify/knowledge.txt",
-                            "description": "dify知識ドキュメント"
-                    },
-                    "score": 0.98,
-                    "title": "knowledge.txt",
-                    "content": "これは外部知識のドキュメントです。"
-            },
-            {
-                    "metadata": {
-                            "path": "s3://dify/introduce.txt",
-                            "description": "dify紹介"
-                    },
-                    "score": 0.66,
-                    "title": "introduce.txt",
-                    "content": "GenAIアプリケーションのイノベーションエンジン"
+    "records": [
+        {
+            "content": "This is the document for external knowledge.",
+            "score": 0.98,
+            "title": "knowledge.txt",
+            "metadata": {
+                "path": "s3://dify/knowledge.txt",
+                "description": "dify knowledge document"
             }
+        },
+        {
+            "content": "The Innovation Engine for GenAI Applications",
+            "score": 0.66,
+            "title": "introduce.txt",
+            "metadata": {}
+        }
     ]
 }
 ```
 
-## エラー
+## エラーハンドリング
 
-アクションが失敗した場合、サービスは以下のエラー情報をJSON形式で返します：
+Difyはレスポンスの HTTP ステータスコードをチェックします。200以外のステータスはユーザーに表示されるエラーを発生させます。
 
-| プロパティ | 必須 | 型 | 説明 | 例値 |
-|------------|------|-----|------|------|
-| error_code | TRUE | int | エラーコード | 1001 |
-| error_msg | TRUE | string | API例外の説明 | 無効な認証ヘッダー形式です。`Bearer <api-key>` 形式が期待されます。 |
+オプションでJSON形式の構造化エラー情報を返すことができます：
 
-`error_code` プロパティには以下の種類があります：
+| プロパティ | 型 | 説明 |
+|:---------|:-----|:------------|
+| `error_code` | int | 開発者が定義するアプリケーションレベルのエラーコード。 |
+| `error_msg` | string | 人間が読めるエラーの説明。 |
 
-| コード | 説明 |
-|--------|------|
+以下は推奨されるエラーコードです。これらは慣例であり、Difyによって強制されるものではありません：
+
+| コード | 推奨される使用方法 |
+|:-----|:----------------|
 | 1001 | 無効な認証ヘッダー形式 |
 | 1002 | 認証失敗 |
-| 2001 | 知識が存在しません |
-
-## 開発例
-
-以下の動画では、LlamaCloudを例として外部ナレッジベースプラグインの開発方法を学ぶことができます：
+| 2001 | ナレッジベースが見つからない |
 
-<iframe
-  src="https://www.youtube.com/embed/FaOzKZRS-2E"
-  width="100%"
-  height="315"
-  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
-  allowFullScreen
-/>
+### エラーレスポンス例
 
-詳細については、プラグインの[GitHubリポジトリ](https://github.com/langgenius/dify-official-plugins/tree/main/extensions/llamacloud)を参照してください。
-
-### HTTPステータスコード
-
-**AccessDeniedException**
-アクセス権限がないため、リクエストが拒否されました。権限を確認して再試行してください。
-HTTPステータスコード：403
-
-**InternalServerException**
-内部サーバーエラーが発生しました。リクエストを再試行してください。
-HTTPステータスコード：500
+```json
+{
+    "error_code": 1002,
+    "error_msg": "Authorization failed. Please check your API key."
+}
+```