Epic Online Services (EOS) ではカタログ アイテムのアカウント所有権を検証する方法が複数あります。推奨されるのは、Ecom インターフェース を使って EOS SDK API を使用する方法です。このドキュメントは、RESTful エンドポイントを使用して所有権情報にアクセスすることを推奨しているタイトルやサービスのためのものです。EOS には、所有権検証を直接オンラインで実行するための RESTful サービス エンドポイントがあり、クライアントとサービスとの間で受け渡し可能な所有権トークンを作成して検証します。また、利用資格レコードを列挙して処理する利用資格サービスもあります。
所有権検証に使用する方法はユースケースによって異なります。オンライン方式は、エンドポイントと直接統合することで、ゲーム クライアントまたはゲーム サーバーから使用できます。所有権検証トークン方式では、ゲーム クライアント、ユーザー、利用資格およびシグネチャに関する情報を含むトークンが提供され、ゲーム クライアントまたはその他のサービスがそれを検証することができます。所有権検証を行うサードパーティ製のサービスを統合している場合は、所有権検証トークン チェックを使用して、ユーザーのデータにサービスがアクセスできないようにすることをお勧めします。
所有権チェックはツリー全体を探索して、指定した catalogItemId へのアクセス権をユーザーが持っているかどうかをチェックします。利用資格は特定の取引が発生しているかどうかを確認する際に役立ちます。たとえば、ユーザーがゲームのデラックス版を購入し、それに DLC1 にアクセス可能なシーズンパスが含まれている場合、所有権チェックは TRUE を返しますが、それに対し、利用資格チェックでは DLC1 は含まれません。
アクセス トークンを取得するためには、事前に認証サービスと統合を行う必要があります。認証の情報については、Epic アカウント サービスを開始する を参照してください。
オンラインでの所有権検証
ユーザーにアイテム、またはアイテム リストの所有権があるかどうかをチェックするエンドポイント。 https://api.epicgames.dev/epic/ecom/v1/platforms/EPIC/identities/{{currentAccountId}}/ownership?nsCatalogItemId={{sandboxId:catalogItemId}}
このエンドポイントは、'https://api.epicgames.dev/epic/oauth/v1/.well-known/openid-configuration' を使って実装されたコンフィギュレーション SDK 1.5+ または OAuth OpenID Connect exchange を介して取得した認証トークンに適用します。
Bearer 承認を使用して Authorization ヘッダにアクセス トークンを渡す必要があります。
このエンドポイントは以下のクエリ パラメータをサポートします。
| パラメータ | 説明 |
|---|---|
nsCatalogItemId | {{sandboxId:catalogItemId}} の書式で、このパラメータを繰り返すことで、sandboxId と catalogItem の複数の組み合わせをチェックできます。 |
sandboxId | This parameter can be used to obtain the full list of owned catalogItemIds in a given sandbox. |
所有権情報を取得するリクエストの例を以下のスニペットに示します。
所有権検証トークン
所有権検証トークンは署名付きの JWT で、有効期限は 5 分間です。所有権検証トークンは、RS512 (SHA-512 を使用した RSA PKCS#1 シグネチャ、RSA キー サイズ 2048) を使用して署名されています。
オフラインでの所有権検証の実行には 2 つのステップがあります。
-
所有権検証トークンのリクエスト
-
公開キーを使用したトークンの検証
ゲーム クライアント/サーバーが所有権検証トークンを取得すると、所有権検証を行う必要のある任意の統合サービスにトークンを渡すことができます。トークンを検証する統合サービスは JWT をアンパックして kid (キー ID) を展開します。その後、そのキー ID の公開キーを取得してシグネチャを検証します。
トークンには以下の情報が含まれます。
| クレーム | 説明 |
|---|---|
| jti | このトークン固有の ID。 |
| sub | トークンのリクエストに使用されたアカウントのアカウント ID。 |
| clid | トークンのリクエストに使用されたクライアントのクライアント ID。 |
| ent | このトークンで確認された利用資格所有権の配列。この値が空の場合、そのアカウントはリクエストされた利用資格を持ちません。 |
| iat | トークンが発行された時刻を示す UNIX タイムスタンプ。 |
| exp | トークンの有効期限を示す UNIX タイムスタンプ。 |
所有権検証トークンをリクエストする
所有権検証トークンをリクエストするために、クライアントは HTTP POST リクエストを所有権トークン エンドポイントに対して発行します。
以下が所有権検証トークンをリクエストするエンドポイントです。
Bearer 承認を使用して Authorization ヘッダにアクセス トークンを渡す必要があります。
このエンドポイントでは、以下のリクエスト ボディがサポートされます。
注:Content-Type は「application/x-www-form-urlencoded」で、パラメータがリクエスト ボディに含められている必要があります。
| パラメータ | 説明 |
|---|---|
nsCatalogItemId | {{sandboxId:catalogItemId}} の書式で、このパラメータを繰り返すことで、sandboxId と catalogItem の複数の組み合わせをチェックできます。 |
検証トークンを取得するリクエストの例を以下のスニペットに示します。
egoc1~ は Epic Games Ownership Check を表すプレフィックスです。デコードの際には取り除いてください。
トークンには、base64 でエンコードされた 3 つの JSON オブジェクトがあり、それぞれ JWT のヘッダ、ペイロード、シグネチャに対応しています。詳細については、「JWT のドキュメント」を参照してください。
以下は JWT ヘッダの例です。
以下は JWT ボディの例です。
所有権検証トークンを検証する
トークンのシグネチャを検証するには、公開キーを取得する必要があります。キーを取得するには、キー ID (JWT 内の kid) が必要です。レスポンスには JSON Web Key (JWK) が含まれ、これを使用して JWT 内のシグネチャを検証できます。
公開キーをリクエストするために、クライアント/サーバーは HTTP リクエストを公開キー エンドポイントに対して発行します。
以下が公開キー エンドポイントです。
公開キーを取得するリクエストの例を以下のスニペットに示します。
利用資格の列挙
アカウントのダイレクトな利用資格のリストが必要な場合にチェックするエンドポイント。
所有権のチェックのみが必要な場合は、Epic が推奨する上述の所有権チェック API を使用してください。
Bearer 承認を使用して Authorization ヘッダにアクセス トークンを渡す必要があります。
このエンドポイントは以下のクエリ パラメータをサポートします。
| パラメータ | 説明 |
|---|---|
sandboxId | ゲーム タイトルの名前空間。 |
entitlementName | オプションです。利用資格の名前。指定されていない場合は、sandboxId 以下の利用資格が返されます。このパラメータを繰り返すことで、複数の利用資格をチェックできます。 |
ユーザーとサンドボックスの利用資格をすべて取得するリクエストの例を以下のスニペットに示します。
利用資格の引き換え/使用
以下は利用資格の引き換え/使用のためのエンドポイントです。利用資格の引き換えが行われると、利用資格の状態は「非アクティブ」に変更されます。
Bearer 承認を使用して Authorization ヘッダにアクセス トークンを渡す必要があります。
このエンドポイントでは、以下のリクエスト ボディがサポートされます。
ユーザーとサンドボックスの複数の利用資格を取得するリクエストの例を以下のスニペットに示します。