> 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-yz.md). # APIドキュメント: ユーザー名 ## **はじめに** GGWP は、ユーザー名データの処理や、アプリケーションのワークフローにアクションを組み込むために使える API を提供します。この製品は、ユーザー名に関連するさまざまな種類の有害コンテンツを特定するよう設計されており、チーム名やギルド名のような類似ユースケースも、作成時だけでなく、ユーザーが変更を加えたり新しい社会的トレンドによって「有害」と見なされる概念が変化したりする時間経過の中でも対象にします。 ## オンボーディングガイド API を使い始める前に、この製品がどのように動作するかを理解しておくことが重要です。そうすることで、その機能を最大限に引き出せます。 ### **GGWP のユーザー名モデレーションソリューションを理解する** この製品の主なユースケースは、他のコミュニティメンバーを不快にさせる可能性のある有害なユーザー名やチーム名の生成を防ぐことです。さらに、このツールは、時間の経過とともに有害になる可能性のある既存のユーザー名を見つけたり、別のユーザーのユーザー名を通報したユーザーから提出された報告を検証して優先度付けしたりするためにも使えます。 各ユーザー名ごとに 1 回 API を呼び出し、送信者を追跡するための一意の識別子を含めます（詳細は下記の「Username API」セクションを参照）。GGWP がこの情報を処理し、そのユーザー名およびその背後にいるユーザーに関連する適切なインサイトを提供します。 レスポンスが返ってきたら、プラットフォーム上のユーザー体験を向上させるために、さまざまなアクションを組み込むことを推奨します。たとえば、新規ユーザーに別のユーザー名の選択を促したり、既存ユーザーにプロフィール名の変更を通知したりできます。 ### **設定可能な項目** プラットフォーム全体でユーザー名に対して防ぎたいコンテンツの種類を選択するために、カスタム設定を定義できます。これは 2 つの方法で行えます： * オンボーディング時（推奨）- 必要な設定をアカウントマネージャーに共有すると、GGWP がそれらをお使いの API 設定に組み込みます。 * 各 API 呼び出し時 - ヘッダーを使用して、API 呼び出しのたびにカスタム設定を入力することもできます（詳細は「Username API」セクションを参照）。ただし、すべてのカスタム要素を指定できるわけではなく、エラーが発生しやすいという制限があります。 設定できる項目は以下のとおりです： * **トピック**：利用可能なトピックには、暴力、性的コンテンツ、暴言、属性ヘイト、不適切表現、リンク共有、薬物、自傷行為があります。 * **フィルター強度**：Username API のフィルター強度設定は、安全性という親レンズに基づいています。通常、各トピックに対して 4 つの値を選べますが、一部例外があります。この 4 つの値は次のとおりです： * フィルター強度 =「Off」- フィルターは有効ではないため、あらゆる種類の有害表現が許可されます。制限を課したくない成人向け環境に適しています。 * フィルター強度 =「Low」- 非常に不快なコンテンツのみをフィルターし、中程度および軽度の有害表現は通します。成人のみの環境に適しています。 * フィルター強度 =「Medium」- 極端な有害表現と中程度の有害表現をフィルターし、軽度の有害表現のみを通します。多少の無害な有害表現を許容できるティーン向け環境に適しています。 * フィルター強度 =「High」- あらゆる種類の有害表現をフィルターします。子どもがいる環境に適しています。 * **カスタムコンテンツ：** 特別に扱いたい用語のカスタム許可リストまたはブロックリストがある場合、それらをお使いの API 設定に組み込むこともできます。たとえば、特定のキャラクター名を予約しておき、ユーザーがプロフィールで使用できないようにしたい場合に役立ちます。 ### **処理モード** 異なる性能要件に対応するため、Username API には 2 つの処理モードがあります。どちらも同じカテゴリと設定可能な項目を使用しますが、レイテンシと分析の深さが異なります。 **品質モード（デフォルト）** GGWP のフルモデルを実行し、最大限の検出精度とより広範な言語一般化を実現します。 * **レイテンシ:** 中央値は約 500〜700 ミリ秒。 * **対応言語範囲:** はるかに多くの言語に対応しています。 * **最適な用途:** より厳格な安全ポリシーを持つコミュニティや、より若い利用者がいるコミュニティなど、有害なユーザー名がモデレーションをすり抜けるリスクを最小限に抑えることが重要な場面に適しています。報告の検証や既存ユーザー名の定期監査のように、レイテンシがあまり重要でないオフラインチェックにも便利です。 **パフォーマンスモード** 低レイテンシ向けに最適化された簡素化モデルを使用しつつ、Username API がサポートする主要言語をカバーします。 * **レイテンシ:** 中央値は約 100〜150 ミリ秒 * **対応言語範囲:** 「言語サポート」セクションで説明されている標準の言語セットをサポートします * **最適な用途:** リアルタイムのユーザー名検証や、高速な応答が求められる大量処理のワークフロー向けです。 ### **言語サポート** GGWP Username API は現在、以下の言語をサポートしています： アラビア語、中国語、英語、フランス語、ドイツ語、インドネシア語、イタリア語、日本語、韓国語、ポーランド語、ポルトガル語、ロシア語、スペイン語、トルコ語。 加えて： * **品質モード** は言語対応範囲を **100以上の言語**に拡張します。これは、基盤となる学習データセットがより多様だからです。 * **パフォーマンスモード** は、上記の標準言語セット向けに最適化されています。 追加言語のサポートが必要な場合は、利用可否や今後のロードマップ項目を確認するためにアカウントマネージャーへお問い合わせください。 ## 認証 GGWP は API キーを使用して、認可されたユーザーに以下に記載するすべての API エンドポイントへの安全なアクセスを付与します。すべてのリクエストでは、発行済みの API キーに加えて、以下の HTTP ヘッダーを含める必要があります： `x-api-key: ` 各 API キー： * あなたのプラットフォーム/ゲームを一意に識別します * この文書に記載されたすべての API へのアクセスを提供します * 1 秒あたりに実行できるリクエスト数に対する特定のレート制限と、月単位で実行できるリクエスト数の可能な所定クォータがあります * 秘密として保持し、権限のないゲーム／ユーザーと共有しないでください * 紛失した場合は、新しいキーを再生成する必要があります API キーの発行と、ゲームに必要な正しいレート制限の設定については、GGWP のアカウントマネージャーにお問い合わせください。 ## API キーの使い方 以下は、有効な API キーを使用して本番 API エンドポイントを呼び出す例です（この例ではキーを伏せています）： ```bash curl --request POST 'https://api.ggwp.com/username/v1/validate' \\ --header 'x-api-key: api_key' \\ --header 'Content-Type: application/json' \\ --data-raw '{ "username": "fuckyou123", "user_id": "user001", "timestamp": "2022-01-25 09:44:12" }' ``` 無効な API キーを使用すると `403` レスポンスコードが返されます。以下は無効な API キーを使用した応答例です： ```bash < HTTP/2 403 < date: Thu, 18 Nov 2021 21:28:27 GMT < content-type: application/json < content-length: 23 < x-amzn-requestid: f4361ec6-71bc-478f-98cd-da0fe9df829b < x-amzn-errortype: ForbiddenException < x-amz-apigw-id: JBPLRHGjPHcFdbg= < * 接続 #0 からホスト api.ggwp.com への接続は維持されました {"message":"Forbidden"}* 接続 0 を終了中 ``` ## Username API \[ ベース URL: `api.ggwp.com`] `POST` /username/v1/validate ### **説明** この API エンドポイントは、入力されたユーザー名とユーザー ID、さらに有害表現フィルタリング強度に関する設定可能なオプション一覧を処理し、2 つのレベルで情報を返します： * ユーザー名の詳細 - ユーザー名における有害コンテンツの存在と深刻度を示す指標、および有害性が見つかった場合のそれらの信頼度。 * ユーザーの詳細 - ユーザー名 API への呼び出し履歴、最近ブロックされた試行を含む、そのユーザーに関連する文脈情報。これにより、常習者に対して異なるアクションを発動できます。 ### **ヘッダー** 設定は、GGWP アカウントのセットアップ（推奨）または HTTP ヘッダーを使った各リクエストごとの動的設定のいずれかで提供できます。
ヘッダー必須説明
x-api-keyはい認証に使用する GGWP API キー。
Content-Typeはいに設定する必要があります application/json.
x-api-config任意各リクエストごとの設定上書きを含む Base64 エンコード済み JSON オブジェクト（トピック、フィルター強度）。詳細は下記を参照してください。指定されない場合は、デフォルトまたはオンボーディング時の設定が適用されます。
x-api-processing-mode任意リクエストの処理モードを選択します。受け入れ可能な値： quality （デフォルト）または performance.
**設定可能なトピック（ `x-api-config`)** 以下に、設定可能なトピックと、それぞれがサポートするフィルター強度の値を示します。これらの値は、次を通じて渡される JSON に含まれます： `x-api-config`: * **暴力**：個人または集団に対する身体的危害や破壊を促したり、美化したり、脅したりする言語をフラグします。これには、脅迫、死を願う表現、暴力行為への言及が含まれます。サポートされるフィルター強度の値は次のとおりです： * off: このフィルターは無効です * low: 極端で生々しい暴力的表現のみをフラグします * 例: "getcancer", "hopeyoudie", "rapist" * medium: 上記に加えて、ティーンや子ども向けとして適さないその他の暴力行為への言及もフラグします * 例: "genocide", "lynch", "slaughter", "torture", "kidnapper" * high: 上記に加えて、軽度の暴力的表現もフラグします * 例: "kill", "death", "shooter", "sniper", "blood", "murder" * **性的コンテンツ**：露骨な性的発言、ほのめかし、または不適切もしくは不快な言及を含む言語をフラグします。これには、裸の描写、性的行為への言及、または性的に示唆的な言葉が含まれます。サポートされるフィルター強度の値は次のとおりです： * off: このフィルターは無効です * low: 性的暴力への極端な言及のみをフラグします * 例: "childmolester", "daterape", "gatorbait", "sexoffender" * medium: 上記に加えて、性的行為へのその他の言及や、やや生々しい性的表現もフラグします * 例: "suckmydick", "penisfucker", "pussy", "blowjob", "gangbang" * high: 上記に加えて、子どもには不適切と見なされる軽度の性的表現もフラグします * 例: "boobs", "cock", "porn", "sexy", "butt" * **暴言**：侮辱、個人攻撃、軽蔑的な発言、またはその他の標的型の攻撃的表現を含むユーザー名をフラグします。サポートされるフィルター強度の値は次のとおりです： * off: このフィルターは無効です * low: 非常に攻撃的で侮辱的な用語のみをフラグします * 例: "fuktard", "schizo", "mong", "assmonkey" * medium: 上記に加えて、その他の攻撃的な言葉や、対象を絞った侮辱表現もフラグします * 例: "bastard", "douche", "asshole", "shitfucker", "bitch" * high: 上記に加えて、軽度の攻撃的な用語もフラグし、若年層に最も適しています * 例: "dummy", "idiot", "incel", "braindead", "smartass" * **属性ヘイト**：宗教、民族、国籍、人種、性別、性的指向、その他の属性要因に基づいて、個人または集団に対する差別的な表現を含むユーザー名をフラグします。サポートされるフィルター強度の値は次のとおりです： * off: このフィルターは無効です * medium: 極端なヘイトスラングのみをフィルターします * 例: "nigger", "faggot", "cunt", "retard", "chink", "tranny", "slut" * high: 上記に加えて、特定の属性グループに対するより微妙な偏見と頻繁に結びつく属性用語もフラグします * 例: "gay", "homo", "queer", "nazi", "lesbian" * **不適切表現**：卑猥または下品な言葉、あるいは罵り言葉を含むユーザー名をフラグします。サポートされるフィルター強度の値は次のとおりです： * off: このフィルターは無効です * medium: より卑猥な不適切表現や攻撃的な罵り言葉をフラグします * 例: "fuck", "stfu", "motherfucking", "scumbag" * high: 上記に加えて、軽度の不適切表現もフラグします * 例: "shit", "dammit", "ugly", "stupid", "noob", "wtf", "piss" * **リンク共有**：ユーザーが不適切なサイト、広告、詐欺、その他の潜在的に有害なコンテンツを共有するのを防ぐため、外部リンクを含むユーザー名をフラグします。サポートされるフィルター強度の値は次のとおりです： * off: このフィルターは無効です * medium: 一般的な不適切または成人向けコンテンツ（性的コンテンツ、ギャンブルやその他の違法行為、フィッシング攻撃の可能性が高いものなど）に関連すると知られている URL をフラグします * high: すべての URL をフラグします * **薬物**：ゲーム環境には不適切な、違法物質、薬物使用、または薬物文化への言及を含むユーザー名をフラグします。サポートされるフィルター値は次のとおりです： * off: このフィルターは無効です * on: このフィルターは有効になり、すべての薬物への言及をフラグします * 例: "overdose", "drunk", "crack", "alcohol", "stoned", "cocaine" * **自傷行為**：自傷、自殺、その他の自己破壊的行動を促したり、美化したり、示唆したりするユーザー名をフラグします。サポートされるフィルター値は次のとおりです： * off: このフィルターは無効です * on: このフィルターは有効になり、有害な行動を促進するものをブロックします * 例: "kys", "suicide", "cutyourself", "endurlife" * **政治：** ：政党、政治家、政治運動などの政治的な言及を含むユーザー名をフラグします。サポートされるフィルター値は次のとおりです： * off: このフィルターは無効です * on: このフィルターは有効になっています * 例: "obama", "trump", "liberal", "BLM", "socialist" * **宗教：** ：宗教、宗教的人物、または宗教に一般的に関連付けられる物品や場所など、宗教的な言及を含むユーザー名をフラグします。サポートされるフィルター値は次のとおりです： * off: このフィルターは無効です * on: このフィルターは有効になっています * 例: "catholic", "buddha", "faith", "pope", "prophet", "jewish" * **思想：** ：有害な思想への言及を含むユーザー名をフラグします。サポートされるフィルター値は次のとおりです： * off: このフィルターは無効です * on: このフィルターは有効になっています * 例: "zionism", "supremacy", "caste", "antivax", "kkk", "misogyny" * **物議を醸す内容：** ：物議を醸す人物、出来事、または集団への言及を含むユーザー名をフラグします。サポートされるフィルター値は次のとおりです： * off: このフィルターは無効です * on: このフィルターは有効になっています * 例: "hitler", "jeffreydahmer", "hamas", "covid19", "slavery" **設定の渡し方** 1. サンプル JSON（`config.json`) ```json { "violence": "off", "sexual_content": "low", "verbal_abuse": "medium", "identity_hate": "medium", "profanity": "high", "link_sharing": "high", "drugs": "off", "self_harm": "on", "politics": "on", "religion": "on", "ideologies": "on", "controversial": "on" } ``` 2. JSON を Base64 エンコードする ```bash base64 config.json ``` 3. エンコードされた出力例 
ewogICJ2aW9sZW5jZSI6ICJvZmYiLAoJInNleHVhbF9jb250ZW50IjogImxvdyIsCgkidmVyYmFsX2FidXNlIjogIm1lZGl1bSIsCgkiaWRlbnRpdHlfaGF0ZSI6ICJtZWRpdW0iLAoJInByb2Zhbml0eSI6ICJoaWdoIiwKCSJsaW5rX3NoYXJpbmciOiAiaGlnaCIsCgkiZHJ1Z3MiOiAib2ZmIiwKCSJzZWxmX2hhcm0iOiAib24iCn0=
4. curl のリクエスト例 
curl --request POST 'https://api.ggwp.com/username/v1/validate' \\
     --header 'x-api-key:<API_KEY>' \\
     --header 'Content-Type: application/json' \\
     --header 'x-api-config: ewogICJ2aW9sZW5jZSI6ICJvZmYiLAoJInNleHVhbF9jb250ZW50IjogImxvdyIsCgkidmVyYmFsX2FidXNlIjogIm1lZGl1bSIsCgkiaWRlbnRpdHlfaGF0ZSI6ICJtZWRpdW0iLAoJInByb2Zhbml0eSI6ICJoaWdoIiwKCSJsaW5rX3NoYXJpbmciOiAiaGlnaCIsCgkiZHJ1Z3MiOiAib2ZmIiwKCSJzZWxmX2hhcm0iOiAib24iCn0=' \\
     --header 'x-api-processing-mode: performance' \\
     --data-raw '{
       "username": "fuckyou123", 
       "user_id": "user001", 
       "timestamp": "2022-01-25 09:44:12"
     }'
**デフォルト設定** もし `x-api-config` ヘッダーが提供されない場合： ```json { "violence": "high", "sexual_content": "high", "verbal_abuse": "high", "identity_hate": "high", "profanity": "high", "link_sharing": "high", "drugs": "on", "self_harm": "on", "politics": "on", "religion": "on", "ideologies": "on", "controversial": "on" } ``` もし `x-api-processing-mode` が提供されない場合： ```json { "processing_mode": "quality" } ``` ### **パラメータ** `body`：次のフィールドを含む辞書:\ (*utf-8 エンコーディングである必要があります)* * **username:** 検証するユーザー名を含む文字列。 * **user\_id:** ユーザー名を送信したユーザーの一意の識別子。これが新しいユーザーで、まだ *user\_id* が作成されていない場合は、下記に示す形式の使用を推奨します。ここで *sessionID* は、たとえばブラウザのナビゲーション設定のような、そのユーザーを識別できる任意のアクティビティに基づくことができます。 ```json user_id = "anonymous_sessionID" ``` * （任意） **timestamp:** ユーザー名が作成された時刻を *YYYY-MM-DD HH:MM:SS* 形式で、UTC で指定します。追加しない場合は、代わりにサーバー側の UTC タイムスタンプが追加されます。 例 ```json { "username": "fuckyou123", "user_id": "user001", "timestamp": "2022-01-25 09:44:12" } ``` サンプル呼び出し： ```bash curl --request POST 'https://api.ggwp.com/username/v1/validate' \\ --header 'x-api-key: api_key' \\ --header 'Content-Type: application/json' \\ --data-raw '{ "username": "fuckyou123", "user_id": "user001", "timestamp": "2022-01-25 09:44:12" }' ``` ### **出力** #### 200 レスポンス 次のトップレベルフィールドを持つ JSON オブジェクトを返します：
username_details 送信されたユーザー名に対するユーザー名レベルのモデレーション結果。 * `username` — モデレーションのために送信されたユーザー名。 * `flag` — `true` 有効化されたモデレーションカテゴリまたはカスタムルールのいずれかでそのユーザー名がフラグされた場合。 * `severity` — ユーザー名に割り当てられた全体的な深刻度。可能な値： `none`, `low`, `medium`, `high`、および `custom`. * `custom` は、GGWP がそのユーザー名をフラグしていないが、クライアントのカスタムブロックリストの用語に一致した場合に使用されます。 * `confidence` — ユーザー名レベル全体の検出に対する信頼度。可能な値： `none`, `low`, `medium`、または `high`。これはモデレーション動作の調整に使えます： * 偽陽性を減らすには、 `low` の信頼度検出を自動適用の対象から除外します。 * より多くの潜在的に有害なユーザー名を検出するには、 `low` の信頼度検出を含めます。ただし、その分、境界線上のユーザー名がより多くフラグされる可能性があります。 カテゴリフィールドは、そのユーザー名で検出されたモデレーションカテゴリを示します。これらのフィールドはブール値であり、相互排他的ではありません。1 つのユーザー名が複数のカテゴリでフラグされることがあります。 * `politics` — `true` そのユーザー名が政治的コンテンツのシグナルに一致した場合。 * `controversial` — `true` そのユーザー名が物議を醸すコンテンツのシグナルに一致した場合。 * `性的コンテンツ` — `true` そのユーザー名が性的コンテンツのシグナルに一致した場合。 * `暴力` — `true` そのユーザー名が暴力関連のシグナルに一致した場合。 * `不適切表現` — `true` そのユーザー名が不適切表現のシグナルに一致した場合。 * `link` — `true` そのユーザー名に URL、ドメイン、またはリンクのような内容が含まれているように見える場合。 * `自傷行為` — `true` そのユーザー名が自傷行為関連のシグナルに一致した場合。 * `custom` — `true` そのユーザー名がクライアントのカスタムブロックリスト用語に一致した場合。 * `religion` — `true` そのユーザー名が宗教関連のコンテンツシグナルに一致した場合。 * `属性ヘイト` — `true` そのユーザー名が属性ベースのヘイトシグナルに一致した場合。 * `薬物` — `true` そのユーザー名が薬物関連のコンテンツシグナルに一致した場合。 * `暴言` — `true` そのユーザー名が侮辱または攻撃的な言葉のシグナルに一致した場合。 * `ideologies` — `true` そのユーザー名が思想関連のコンテンツシグナルに一致した場合。
user_details 送信されたユーザーのユーザーレベルのユーザー名モデレーション履歴 `user_id`. このオブジェクトは、現在のユーザー名だけを単独で評価するのではなく、短い時間枠内でのユーザー名の繰り返し不正利用を特定するのに役立ちます。 * `user_id` — リクエストで指定されたユーザー識別子。 * `recent_username_calls` — 過去 5 分間にこのユーザーに関連して行われたユーザー名モデレーションリクエストの数。 * `recent_flagged` — 過去 5 分間にこのユーザーに関連してフラグされたユーザー名モデレーションリクエストの数。 * `recent_flagged_usernames` — 過去 5 分間にこのユーザーに関連してフラグされたユーザー名の一覧。
応答例： ```json { "username_details": { "username": "fuckoff", "flag": true, "severity": "medium", "confidence": "high", "politics": false, "controversial": false, "sexual_content": false, "violence": false, "profanity": true, "link": false, "self_harm": false, "custom": false, "religion": false, "identity_hate": false, "drugs": false, "verbal_abuse": true, "ideologies": false }, "user_details": { "user_id": "123", "recent_username_calls": 8, "recent_flagged": 7, "recent_flagged_usernames": [ "yousuck", "yousuck", "fuckyou123", "fuckyouoff", "fuckyou123" ] } } ``` #### 400 レスポンス リクエストが無効な場合に返されます。 一般的な原因は次のとおりです： * 無効な JSON 入力 * 必須フィールドの不足 * フィールド型が無効 * 不正な形式のリクエスト本文 #### 403 レスポンス API キーがない、無効である、またはこのエンドポイントへのアクセス権がない場合に返されます。 #### 500 レスポンス 内部サーバーエラーのためリクエストを完了できなかった場合に返されます。