> For the complete documentation index, see [llms.txt](https://docs.ggwp.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ggwp.com/jp/apidokyumento-chat/pakkji/chat-api-v2karav3heno.md). # Chat API v2からv3への移行 Chat API v3 は、新規統合向けの現在の推奨バージョンです。v2 を使用している既存の統合は引き続きレガシーエンドポイントを使用できますが、最新のカテゴリ分類、重大度モデル、応答構造を使うために v3 への移行を推奨します。 ### エンドポイントの変更 リクエスト URL を v2 エンドポイントから v3 エンドポイントに更新してください。 | バージョン | エンドポイント | | ------- | ----------------------- | | v2 レガシー | `POST /chat/v2/message` | | v3 現行 | `POST /chat/v3/message` | ベース URL は変わりません: ``` https://api.ggwp.com ``` ### リクエスト本文の互換性 コアとなるリクエスト本文は変更ありません。引き続き同じ必須フィールドを送信できます: ```json { "session_id": "match_7765", "message": "あちこちにいるクソ野郎ども", "user_id": "user989" } ``` 以下の任意フィールドも引き続きサポートされています: * `username` * `timestamp` * `language` * `message_index` * `message_url` * `metadata` ### 設定の変更 以下を使用してリクエストごとの設定を渡している場合は `x-api-config` ヘッダーを使う場合、設定キーを v3 のカテゴリ名に更新してください。 | v2 の設定キー | v3 の設定キー | | --------------- | ---------------------- | | `identity_hate` | `identity_harm` | | `profanity` | `offensive_language` | | `link_sharing` | `links` | | `self_harm` | `self_harm_incitement` | | `age_concern` | `age_disclosure` | v3 では、以下を含む追加カテゴリも導入されています: * `extremism` * `gameplay_criticism` * `real_threat` * `sexual_harassment` * `sexual_violence` v3 では、ほとんどのカテゴリが同じ感度スケールをサポートしています: ``` off, low, medium, high ``` 感度は、どの重大度レベルがブロックされるかを制御します:
感度動作
offそのカテゴリをフィルタしない
low高重大度のコンテンツのみをフィルタする
medium中および高重大度のコンテンツをフィルタする
high低・中・高重大度のコンテンツをフィルタする
> 注: v3 では、カテゴリ全体で重大度ベースの感度がより一貫して使用されています。以前は `on` / `off`を使用していた v2 の一部カテゴリ、たとえば `drugs`, `spam`, `scam`および `solicitation`は、現在では `off`, `low`, `medium`または `high`. ### デフォルト設定の変更 以下の `x-api-config` ヘッダーを送らない場合、またはアカウントにカスタムのオンボーディング時設定が構成されていない場合、v3 は v2 と異なる既定のフィルタリング動作を適用することがあります。 v2 では、いくつかのカテゴリが既定で無効、または低い感度に設定されていました。たとえば: ```json { "solicitation": "off", "scam": "off", "age_concern": "off", "minor_safety": "low", "pii": "medium" } ``` v3 では、このドキュメントに示す既定設定により、サポート対象のカテゴリはすべて `high` 感度: ```json { "age_disclosure": "high", "drugs": "high", "extremism": "high", "gameplay_criticism": "high", "identity_harm": "high", "links": "high", "minor_safety": "high", "offensive_language": "high", "pii": "high", "real_threat": "high", "scam": "high", "self_harm_incitement": "high", "sexual_content": "high", "sexual_harassment": "high", "sexual_violence": "high", "solicitation": "high", "spam": "high", "verbal_abuse": "high", "violence": "high" } ``` これは、設定を見直さずに v2 から v3 に移行すると、より厳しいフィルタリング動作になる可能性があることを意味します。 本番トラフィックを v3 に切り替える前に、現在の v2 設定を確認し、次のいずれかを行ってください: 1. GGWP アカウントで同等の設定を構成する、または 2. 明示的な `x-api-config` ヘッダーを、希望する v3 の感度設定とともに送信する。 現在 v2 の既定値に依存している場合は、本番展開の前に代表的な本番相当トラフィックで v3 をテストすることを推奨します。 ### 応答の変更 最も大きな移行変更は `message_details`. v2 では、カテゴリ検出は個別のブール値フィールドとして返されていました: ```json { "violence": false, "verbal_abuse": true, "profanity": true, "identity_hate": true } ``` v3 では、カテゴリ検出は構造化された `flagged_categories` 配列として返されます: ```json { "flagged_categories": [ { "category": "identity_harm", "category_severity": "medium" }, { "category": "offensive_language", "category_severity": "high" } ] } ``` 現在の統合で v2 のブール値フィールドをチェックしている場合は、 `message_details.flagged_categories`. ### フィールドの対応 | v2 フィールド | v3 フィールド | 備考 | | ---------------------------------- | ------------------------------------------------------------------------- | --------------------------------- | | `message_details.identity_hate` | `message_details.flagged_categories[].category == "identity_harm"` | カテゴリ名変更 | | `message_details.profanity` | `message_details.flagged_categories[].category == "offensive_language"` | カテゴリ名変更 | | `message_details.link` | `message_details.flagged_categories[].category == "links"` | カテゴリ名変更 | | `message_details.self_harm` | `message_details.flagged_categories[].category == "self_harm_incitement"` | カテゴリ名変更 | | `message_details.age_concern` | `message_details.flagged_categories[].category == "age_disclosure"` | カテゴリ名変更 | | `message_details.custom` | `message_details.custom_flag` | フィールド名変更 | | `message_details.replaced_message` | v3 では返されません | 使用している場合は依存を हटしてください | | 個別のカテゴリのブール値 | `flagged_categories` | v3 はカテゴリ検出のリストを返します | | ブール値ごとのカテゴリレベルの重大度は利用できません | `flagged_categories[].category_severity` | v3 ではカテゴリ固有の重大度が含まれます | | トップレベルの confidence フィールドはありません | `message_details.confidence` | v3 では全体の検出に対する confidence が追加されます | ### 重大度の変更 v2 のメッセージ重大度は次を使用していました: ``` none, low, medium, high ``` v3 は、より広いメッセージレベルの重大度スケールをサポートします: ``` none, very_low, low, medium, high, very_high, custom ``` アプリケーションが重大度値を内部アクションにマッピングしている場合は、新しい値に対応できるよう解析ロジックを更新してください。 ### プレイヤーと会話サマリーの変更 主な構造は同じです: * `player_details` * `conversation_summary` * `recommendations` ただし、v3 では一部の集計フィールドが簡素化されています。統合が以下の v2 フィールドに依存している場合は、ワークフローで本当に必要か確認してください: * `player_details.incident_types_detected` * `player_details.incidents_by_severity` * `conversation_summary.incident_types_detected` * `conversation_summary.incidents_by_severity` ### 推奨される移行手順 1. **エンドポイントを更新する**\ 以下からのリクエストを変更する `/chat/v2/message` から `/chat/v3/message`. 2. **デフォルト設定の動作を確認する**\ v3 のデフォルトは v2 のデフォルトより厳しい場合があります。現在 v2 の既定設定に依存しているなら、ロールアウト前に同等の v3 設定を構成してください。 3. **設定キーを更新する**\ v2 のカテゴリキーを v3 の対応キーに名前変更し、設定したい新しい v3 カテゴリを追加してください。 4. **応答の解析を更新する**\ 個別のカテゴリのブール値に対するチェックを、以下に対するチェックに置き換えてください `message_details.flagged_categories`. 5. **重大度処理を更新する**\ アプリケーションが拡張された v3 の重大度値をサポートしていることを確認してください。 6. **代表的なトラフィックでテストする**\ 本番トラフィックを切り替える前に、安全なメッセージ、境界線上のメッセージ、違反メッセージで v2 と v3 の出力を比較してください。 7. **段階的に展開する**\ まずステージングまたは限定的な本番トラフィックから開始し、下流の解析とモデレーション動作が検証されたら全面移行してください。 ``` ```