Ecom Web APIs

SDK を使用せずに所有権の検証を実行する RESTful エンドポイント

Epic Games Store
10 分で読めます

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このパラメータを使用して、特定のサンドボックスで所有されている catalogItemIds の完全なリストを取得できます。

所有権情報を取得するリクエストの例を以下のスニペットに示します。

GET /epic/ecom/v1/platforms/EPIC/identities/12abc3de456f78901a2bc345dd6789e0/ownership HTTP/1.1
Host: api.epicgames.dev
Authorization: Bearer 1fe59d629cda497b9f65dbdbee7d468e
nsCatalogItemId=fn:ff150af93c9a4fb99fee12f5db49fa5b&nsCatalogItemId=fn:94egdb6df476d45199f6be940aa1337c0
[
{
"namespace": "fn",
"itemId": "94egdb6df476d45199f6be940aa1337c0",
"owned": false
},
{
"namespace": "fn",
"itemId": "ff150af93c9a4fb99fee12f5db49fa5b",
"owned": true
}
]

トークン ベースでの所有権の検証

所有権検証トークンは署名付きの JWT で、有効期限は 5 分間です。所有権検証トークンは、RS512 (SHA-512 を使用した RSA PKCS#1 シグネチャ、RSA キー サイズ 2048) を使用して署名されています。

トークン ベースでの所有権検証の実行には 2 つのステップがあります。

  1. 所有権検証トークンのリクエスト

  2. 公開キーを使用したトークンの検証

ゲーム クライアント/サーバーが所有権検証トークンを取得すると、所有権検証を行う必要のある任意の統合サービスにトークンを渡すことができます。トークンを検証する統合サービスは JWT をアンパックして kid (キー ID) を展開します。その後、そのキー ID の公開キーを取得してシグネチャを検証します。

トークンには以下の情報が含まれます。

クレーム説明
jtiこのトークン固有の ID。
subトークンのリクエストに使用されたアカウントのアカウント ID。
clidトークンのリクエストに使用されたクライアントのクライアント ID。
entこのトークンで確認された利用資格所有権の配列。この値が空の場合、そのアカウントはリクエストされた利用資格を持ちません。
iatトークンが発行された時刻を示す UNIX タイムスタンプ。
expトークンの有効期限を示す UNIX タイムスタンプ。

所有権検証トークンをリクエストする

所有権検証トークンをリクエストするために、クライアントは HTTP POST リクエストを所有権トークン エンドポイントに対して発行します。

以下が所有権検証トークンをリクエストするエンドポイントです。

https://api.epicgames.dev/epic/ecom/v1/platforms/{platform}/identities/{identityId}/ownershipToken

Bearer 承認を使用して Authorization ヘッダにアクセス トークンを渡す必要があります。

このエンドポイントでは、以下のリクエスト ボディがサポートされます。

注:Content-Type は「application/x-www-form-urlencoded」で、パラメータがリクエスト ボディに含められている必要があります。

パラメータ説明
nsCatalogItemId{{sandboxId:catalogItemId}} の書式で、このパラメータを繰り返すことで、sandboxId と catalogItem の複数の組み合わせをチェックできます。

検証トークンを取得するリクエストの例を以下のスニペットに示します。

POST /epic/ecom/v1/platforms/EPIC/identities/{{currentAccountId}}/ownershipToken HTTP/1.1
Host: api.epicgames.dev
Authorization: Bearer 1fe59d629cda497b9f65dbdbee7d468e
nsCatalogItemId=fn:c204662afac64acd8a2117590be477da
{
"token": "egoc1~eyJraWQiOiJWbWdpMDFoQ2V2dXVEbUtWZFZubXphWnhpT2lBa0dEZWdRQmdDdWc4dkRZIiwiYWxnIjoiUlM1MTIifQ.eyJzdWIiOiI5NGVkYjZkZjQ3NmQ0NTE5OWY2YmU5NDBhYTEzMzdjMCIsImlwIjoiNTAuOTguMjI2LjEwIiwiY2xpZCI6IjI5Y2VlNDJlNzExNzQ2ZTFiYmNhZmI2MjkyOWU0OGZkIiwiZW50IjpbeyJjYXRhbG9nSXRlbUlkIjoiYzIwNDY2MmFmYWM2NGFjZDhhMjExNzU5MGJlNDc3ZGEiLCJvd25lZCI6dHJ1ZSwibmFtZXNwYWNlIjoiY2F0bmlwIn1dLCJleHAiOjE1Njk5Nzg1NjUsImlhdCI6MTU2OTk3ODI2NSwianRpIjoiMzgzN2FjODhlNDJjNDE1OTlmMzI5OTNjMmViYzBhOWQifQ.CX4yEEsZph9qPaVvtpnS0sLe_9YGLic5jIOQhhk3tG88GfNLp10w5y9DbYXocDlMXdEoAsAt-33G1JOPIFzrktrOxpR_FNdQ_ozCbBCF1aTQFTYKtvrbYkpA5AIGHmy_J9jSKMq-jN4TQxoSbR0LnowiWoKp_ntibmx0titFQ0kOYBQMvwwTlLgTzUv55I6VlFl8gMBSEw1_oRIUbdNbdHJO4UwnHTeUbcUUvuAWm13BpI2P39vRjU1xx4t51kUj_yY9ISWFBSGsLgEAhH13Mm1CilaeiPsLanE1sA5B3mRMjq8KcLtkkp8JvlIrgD4e-xo_tnRSLkRyKuU0GoqNKw"
}