Light

Dark

Web API を使用した所有権検証

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

Epic Games Store Only

このページ中

オンラインでの所有権検証
所有権検証トークン
- 所有権検証トークンをリクエストする
- 所有権検証トークンを検証する
利用資格の列挙
利用資格の引き換え/使用

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 の複数の組み合わせをチェックできます。

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

GET /epic/ecom/v1/platforms/EPIC/identities/94edb6df476d45199f6be940aa1337c0/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 つのステップがあります。

所有権検証トークンのリクエスト
公開キーを使用したトークンの検証

ゲームクライアント/サーバーが所有権検証トークンを取得すると、所有権検証を行う必要のある任意の統合サービスにトークンを渡すことができます。トークンを検証する統合サービスは 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"
}

egoc1~ は Epic Games Ownership Check を表すプレフィックスです。デコードの際には取り除いてください。

トークンには、base64 でエンコードされた 3 つの JSON オブジェクトがあり、それぞれ JWT のヘッダ、ペイロード、シグネチャに対応しています。詳細については、「JWT のドキュメント」を参照してください。

以下は JWT ヘッダの例です。

{
  "kid": "tFC2UIhFpTM_Ea3qcOd_MqQT1cBBm9kFLSDfeJhsRG8",
  "alg":"RS512"
}

以下は JWT ボディの例です。

{
 "jti" : "a19c3f03edf84c0a9621ee44ff36566f",
 "sub" : "d144285abee343df98c4e84572c576bb",
 "clid":"44c39619da304266855c9646e1081ab5",
 "iat" :1547675438,
 "exp" :1547704238,
 "ent" : [{
      "catalogItemId": "c204662afac64acd8a2117590be477da",
      "owned": true,
      "namespace": "catnip"
}]
}

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

トークンのシグネチャを検証するには、公開キーを取得する必要があります。キーを取得するには、キー ID (JWT 内の kid) が必要です。レスポンスには JSON Web Key (JWK) が含まれ、これを使用して JWT 内のシグネチャを検証できます。

公開キーをリクエストするために、クライアント/サーバーは HTTP リクエストを公開キーエンドポイントに対して発行します。

以下が公開キーエンドポイントです。

https://ecommerceintegration-public-service-ecomprod02.ol.epicgames.com/ecommerceintegration/api/public/publickeys/{kid}.

公開キーを取得するリクエストの例を以下のスニペットに示します。

GET /ecommerceintegration/api/public/publickeys/Vmgi01hCevuuDmKVdVnmzaZxiOiAkGDegQBgCug8vDY HTTP/1.1
Host: ecommerceintegration-public-service-ecomprod02.ol.epicgames.com

{
    "kty":"RSA",
    "e":"AQAB",
    "kid":"Vmgi01hCevuuDmKVdVnmzaZxiOiAkGDegQBgCug8vDY",
    "n": "k-LHmLHW5bbiqYLmPxC77ciG4N7IuF1SUOSsnDBLneKH3ZAU9kXRkq5MYjmRjxt8g3HpXmmhi_sHe4_g-VnSrM7jP6ntMiJ5t0d5J9ERkSEUSY4w_LS_YECavTr76GiutV_xPT-9jpHJWdVYqk68tiqR42xPFHEFUkYYsb_t6gONhth85ICnVY8Mjg6F0hFvvaMvOJcDVYfQbdjWY8-mzvIF9DmvyVkWaZSQYBaVuNCNKkSiSnkyCtbrynneayugwW0R-rNP5lEcp8UwXpBnep6sRf8nQEsByCnR91RdRXjuvrCSl7fOxpFX82t2WjWTYEOkOgb6yGc_ft-sJidSIQ"
}

利用資格の列挙

アカウントのダイレクトな利用資格のリストが必要な場合にチェックするエンドポイント。

https://api.epicgames.dev/epic/ecom/v1/identities/{identityId}/entitlements

所有権のチェックのみが必要な場合は、Epic が推奨する上述の所有権チェック API を使用してください。

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

このエンドポイントは以下のクエリパラメータをサポートします。


パラメータ	説明
`sandboxId`	ゲームタイトルの名前空間。
`entitlementName`	オプションです。利用資格の名前。指定されていない場合は、sandboxId 以下の利用資格が返されます。このパラメータを繰り返すことで、複数の利用資格をチェックできます。

ユーザーとサンドボックスの利用資格をすべて取得するリクエストの例を以下のスニペットに示します。

GET /api.epicgames.dev/epic/ecom/v1/identities/94edb6df476d45199f6be940aa1337c0/entitlements HTTP/1.1
Host: api.epicgames.dev

Authorization:Bearer 1fe59d629cda497b9f65dbdbee7d468e
[{
        "id":"8894469f1120432095eff043a4529433",
        "entitlementName":"942e8a7133464f0ea83179030536505e",
        "namespace": "buffalo",
        "catalogItemId":"942e8a7133464f0ea83179030536505e",
        "accountId":"94edb6df476d45199f6be940aa1337c0",
        "identityId":"94edb6df476d45199f6be940aa1337c0",
        "entitlementType":"AUDIENCE",
        "grantDate":"2019-01-04T21:34:24.826Z",
        "consumable": false,
        "status":"ACTIVE",
        "active": true,
        "useCount":0,
        "originalUseCount":0,
        "entitlementSource":"AppEpicgamesCom",
        "platformType":"EPIC",
        "created":"2019-01-04T21:34:24.829Z",
        "updated":"2019-01-04T21:34:24.829Z",
        "groupEntitlement": false
    },
    {
        "id": "e21aa0b339ae4e778971058c9395b2b7",
        "entitlementName":"25ed76af7816430cbfc0f5e6d3195d56",
        "namespace": "badger",
        "catalogItemId":"25ed76af7816430cbfc0f5e6d3195d56",
        "identityId":"94edb6df476d45199f6be940aa1337c0",
        "entitlementType":"AUDIENCE",
        "grantDate":"2019-01-16T04:42:06.270Z",
        "consumable": false,
        "status":"ACTIVE",
        "useCount":0,
        "originalUseCount":0,
        "entitlementSource":"LauncherWeb",
        "platformType":"EPIC",
        "created":"2019-01-16T04:42:06.273Z",
        "updated":"2019-01-16T04:42:06.273Z",
        "groupEntitlement": false,
        "country":"CA"
    }]

利用資格の引き換え/使用

以下は利用資格の引き換え/使用のためのエンドポイントです。利用資格の引き換えが行われると、利用資格の状態は「非アクティブ」に変更されます。

https://api.epicgames.dev/epic/ecom/v1/identities/{identityId}/entitlements/redeem

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

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

{
  "entitlementIds": [
    "8894469f1134432095eff043a4529433",
    "25ed76af9816430cbfc0f5e6d3195d56"
  ],
  "sandboxId":"8894469f1120432095eff043a4529433"
}

ユーザーとサンドボックスの複数の利用資格を取得するリクエストの例を以下のスニペットに示します。

PUT
/ecom/v1/identities/94edb6df476d45199f6be940aa1337c0/entitlements/redeem
Host: api.epicgames.dev

Authorization:Bearer 1fe59d629cda497b9f65dbdbee7d468e
Content-Type:  application/json
Request body:
{
  "entitlementIds": [
    "8894469f1134432095eff043a4529433",
    "25ed76af9816430cbfc0f5e6d3195d56"
  ],
  "sandboxId":"8894469f1120432095eff043a4529433"
}

Was this document useful?

Thank you for the response!

You’ve marked this document as useful:

yes

You’ve marked this document as not useful: