Light

Dark

使用Web API进行所有权验证

RESTful端点将在不使用SDK的情况下执行所有权验证

Epic Games Store Only

本页面的内容

在线所有权验证
所有权验证令牌
- 请求所有权验证令牌
- 验证所有权验证令牌
权限列举
补偿/使用权限

Epic在线服务 （EOS）提供多种方式来验证帐户的目录项所有权。首选的方法是通过Ecom界面使用EOS SDK API。本文是针对那些偏好通过RESTful终端访问所有权信息的标题和服务而提供的。EOS拥有用于直接在线所有权验证的RESTful服务终端，从而创建并验证可在客户端、服务与权限服务之间传递的所有权令牌，进而列举和使用授权记录。

所有权验证所使用的方法取决于具体用例。游戏客户端或游戏服务器可通过直接与我们的终端集成来使用在线方法。所有权验证令牌方法提供令牌，其中包括游戏客户端、用户和授权相关信息以及可供游戏客户端或任何其他服务验证的签名。若与执行所有权验证的第三方服务集成，最好使用所有权验证令牌校验来避免授予它们访问用户数据的权限。

所有权校验将遍历整个结构来确定用户是否有访问给定catalogItemId的权限。权限对于确认已发生的特定事务很有用。例如，若用户购买了含季票的Deluxe Edition游戏，而季票本身就包含对DLC1的访问权限，则对于DLC1，所有权校验将返回TRUE，而权限校验将不包含DLC1。

开始前，必须与身份验证服务集成以获得访问令牌。如需与身份验证有关的更多信息，请查看Epic账号服务入门。

在线所有权验证

终端将检查用户是否拥有项或一系列项。

https://api.epicgames.dev/epic/ecom/v1/platforms/EPIC/identities/{{currentAccountId}}/ownership?nsCatalogItemId={{sandboxId:catalogItemId}}

此端点适用于通过SDK 1.5+获取或通过使用配置 'https://api.epicgames.dev/epic/oauth/v1/.well-known/openid-configuration' 实施的OAuth OpenID Connect交换获取的身份验证令牌。

你需要使用Bearer授权在授权标头中传递访问令牌。

此终端支持下列查询参数：


参数	说明
`nsCatalogItemId`	使用 `{{sandboxId:catalogItemId}}` 格式，可重复此参数来检查多个sandboxId和catalogItem组合。
`sandboxId`	用户获得指定沙盒中的 `catalogItemIds` 的完整列表。

下文显示了用于获取所有权信息的请求示例：

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，有效期为五分钟。它是使用RS512（RSA PKCS#1签名，包含SHA-512，RSA密钥大小2048）签署的。

执行离线所有权验证包含两个步骤：

请求所有权验证令牌
用公钥验证令牌是否真实

游戏客户端/服务器获得所有权验证令牌，可将其传递给需执行所有权验证的任何集成。验证令牌的集成需解压缩JWT提取kid（密钥ID），然后获取该密钥ID的公钥来验证签名。

此令牌包含以下声明：


声明	说明
jti	此令牌的唯一辨识符。
sub	用于请求此令牌的帐户的帐户ID。
clid	用于请求此令牌的客户端的客户端ID。
ent	针对此令牌验证的一系列权限所有权。若此值为空，则该帐户无权享有请求权利
iat	令牌作为Unix时间戳发出的时间。
exp	令牌作为Unix时间戳到期的时间。

请求所有权验证令牌

要请求所有权验证令牌，客户端将向所有权令牌终端发出HTTP POST请求。

要请求所有权验证令牌的终端为：

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

需用Bearer授权在授权标头中传递访问令牌。

此终端支持下列请求正文参数：

注意：内容类型需为 "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游戏所有权校验。解码令牌时请将其去除。

令牌包括三个base64编码的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

若只需校验所有权，请使用上文所有权校验API，EPI推荐此方法。）

需用Bearer授权在授权标头中传递访问令牌。

此终端支持下列查询参数：


参数	说明
`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授权在授权标头中传递访问令牌。

此终端支持下列请求正文：

{
  "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: