连接网络API

使用连接接口网络API，验证EOS游戏服务网络API。

你可以通过网络API访问EOS游戏服务。该网络API需要访问令牌来识别作出请求的认证客户端。客户端可以作为独立客户端（客户端访问令牌），或代表用户（用户访问令牌）请求访问令牌。

例如，网页应用可能会对用户进行身份验证，以便为玩家提供账号相关的管理功能。一个独立客户端可以是发行商托管的后端，该后端负责协调EOS语音后端服务托管的语音聊天室。

请求EOS访问令牌

EOS连接（EOS Connect）后端提供了OAuth 2.0令牌端点，以便为访问EOS游戏服务网络API请求访问令牌。

EOS连接令牌端点如下：

https://api.epicgames.dev/auth/v1/oauth/token

客户端可以请求两种访问令牌：

  • 客户端访问令牌：由与后端服务交互的独立客户端使用，用于常规的产品级访问。

  • 用户访问令牌：由与后端服务交互的、代表验证用户的客户端使用。

客户端请求访问令牌时，必须提供有效的产品客户端凭据。你可以在开发者门户的 产品设置 中，为每个产品创建客户端，并获取单独的客户端政策。

客户端可通过两种方式之一传递客户端凭据：

  • 通过标准授权HTTP头

  • 通过POST参数。

请求令牌

HTTP方法

POST /auth/v1/oauth/token

HTTP消息头

名称

值

Authorization

Basic <Base64(ClientId:ClientSecret)>.示例： Basic Q2xpZW50SWQ6Q2xpZW50U2VjcmV0

Content-Type

application/x-www-form-urlencoded

POST Body参数

名称

值

grant_type

如为客户端访问，需使用"client_credentials"。如为用户访问，需使用"external_auth"。

client_id

客户端凭据的ID。未使用授权HTTP头时需使用此项。

client_secret

客户端凭据加密。未使用授权HTTP头时需使用此项。

nonce

由客户端提供的任意字符串值，可增强安全性。包含在客户端的API恢复中，用以验证正确的nonce值。用户访问需要。

deployment_id

指定EPS部署，以请求用户访问所必需的访问权。

external_auth_token

外部验证令牌，可辨识外部账号系统中的用户账号。用户访问需要。

external_auth_type

识别外部验证令牌的类型。用户访问需要。可能的值包括： amazon_access_token, apple_id_token, discord_access_token, epicgames_access_token, epicgames_id_token, gog_encrypted_sessionticket, google_id_token, itchio_jwt, itchio_key, nintendo_id_token, oculus_userid_nonce, openid_access_token, psn_id_token, steam_access_token, steam_encrypted_appticket, xbl_xsts_token

请求示例

curl -X "POST" "https://api.epicgames.dev/auth/v1/oauth/token" \ -H "Content-Type:application/x-www-form-urlencoded" \ -H "Accept:application/json" \ -H "Authorization: Basic Q2xpZW50SWQ6Q2xpZW50U2VjcmV0" \ -d "grant_type=client_credentials&deployment_id=<deploymentId>"

令牌响应

HTTP 200 - OK

HTTP头

名称

值

Content-Type

application/json

JSON Payload

名称

说明

access_token

将访问令牌生成为JSON Web Token（JWT）字符串。访问令牌说明了验证的客户端和用户。

token_type

始终设置为"bearer"。

expires_at

令牌失效时间。包含了一个NumericDate数值，表示了Unix时间戳后的时间点，精确到秒数。

expires_in

令牌有效期。从令牌发布到失效之间的秒数。

nonce

由客户端在令牌请求中提供的任意字符串值。客户端用其增强安全性。在HTTP回复中接收到访问令牌时，客户端可以验证令牌回复是否包含了预期的nonce值。

organization_id

你的组织标识符。

product_id

你的产品标识符。

sandbox_id

你的沙盒标识符。

deployment_id

你的部署标识符。

features

客户端允许访问的功能列表。可在开发者门户中为客户端启用功能。

organization_user_id

在组织的各个产品中识别唯一EOS用户。包含在用户访问令牌中。

product_user_id

验证的EOS产品用户的ID。包含在用户访问令牌中。

id_token

ID令牌，可安全识别EOS产品用户。包含在用户访问令牌中。

接收的"access_token"将用户调用EOS游戏服务网络API，会在授权HTTP头中以Bearer令牌的形式提供。例如： Authorization: Bearer <access_token>.

响应示例

"access_token" : "<Access Token>",
"token_type" : "bearer",
"expires_at" : "2021-06-11T23:10:53.491Z",
"expires_in" : 3599,
"features" : ["Matchmaking", "Voice"],
"organization_id" : "<Organization ID>",
"product_id" : "<Product ID>",
"sandbox_id" : "<Sandbox ID>",
"deployment_id" : "<Deployment ID>"

查询外部账号

请求"queryExternalAccountsForAnyUser"会从外部账号ID列表中返回相应的产品用户ID。

政策

客户端必须启用连接功能的queryExternalAccountsForAnyUser客户端政策操作。

授权

这一调用需要使用EOS客户端访问令牌进行Bearer令牌授权。

QueryExternalAccounts请求

HTTP请求

GET /user/v1/accounts

HTTP头

名称

值

Authorization

Bearer <EOS client access token>

HTTP查询参数

名称

类型

说明

accountId

数组 <String>

外部账号ID列表，用于查询产品用户ID。输入的账号ID最多为16位数字。

identityProviderId

字符串

支持的身份供应商。 可用的值包括： Amazon, apple, discord, epicgames, gog, google, itchio, nintendo, oculus, Openid, psn, steam, xb

environment

字符串

如果外部账号系统使用了独立的账号环境，就必须指定一个环境。请查看平台供应商的文档，了解可用的环境值。否则不可填入该栏位。

请求示例

curl -X "GET" "https://api.epicgames.dev/user/v1/accounts?accountId=<ExternalAccountId_1>&accountId=<ExternalAccountId_2>&identityProviderId=<IdentityProviderId>" \ -H "Accept:application/json" \ -H "Authorization: Bearer <EOS client access token>"

QueryExternalAccounts响应

HTTP回复 200 - OK：成功。

HTTP头

名称

值

Content-Type

application/json

JSON Payload

名称

类型

说明

ids

对象 <String, String> 秘钥为外部账号ID。值为产品用户ID。

将外部账号ID映射到产品用户ID的对象。如果外部账号ID未有对应的产品用户ID，则会从回复中排除。

响应示例

    {
    "ids": {
        "<ExternalAccountId_1>": "<ProductUserId_1>",
        "<ExternalAccountId_2>": "<ProductUserId_2>",
    }
    }

查询产品用户

queryProductUsersForAnyUser 请求用于从产品用户列表中返回相关账户。

策略

客户端必须为连接功能启用 queryProductUsersForAnyUser 客户端策略动作。

授权

该调用需要使用EOS客户端访问令牌和Bearer令牌授权。

QueryProductUsers请求

HTTP Request

GET /user/v1/product-users

HTTP Headers

Name

Value

Authorization

Bearer <EOS client access token>

HTTP Query Parameters

Name

Type

Description

productUserId

Array <String>

用于查询账户的产品用户ID列表。产品用户ID的最大输入数量是16。

请求示例

    curl -X "GET" "https://api.epicgames.dev/user/v1/product-users?productUserId=<ProductUserId_1>&productUserId=<ProductUserId_2>" \
    -H "Accept:application/json" \
    -H "Authorization: Bearer <EOS client access token>"

QueryProductUsers响应

HTTP Response 200 - OK: Success.

HTTP Headers

Name

Value

Content-Type

application/json

JSON Payload

Name

Type

Description

productUsers

Object <String, ProductUser> 键是一个产品用户ID。

用于将产品用户ID映射到账户的对象。如果没有找到产品用户ID，它将被排除在响应外。

Schema

ProductUser

Name

Type

Description

accounts

Array<Account>

Accounts associated with the Product User.

Account

Name

Type

Description

accountId

String

External Account ID.

identityProviderId

String

Identity provider of the external account.

Supported providers are:

  • amazon

  • apple

  • discord

  • epicgames

  • gog

  • google

  • itchio

  • nintendo

  • oculus

  • openid

  • psn

  • steam

  • xbl

新的身份提供者可能会被添加到列表中。

displayName

String (optional)

Display name of the user.

lastLogin

String

Last login time, ISO 8601.

Response示例

    {
        "productUsers": {
            "<ProductUserId_1>": {
                "accounts": [
                    {
                        "accountId": <AccountId_1>",
                        "displayName": "<DisplayName_1>",
                        "identityProviderId": "<IdentityProvider_1>",
                        "lastLogin": "2022-03-18T11:55:44Z"
                    }
                ]
            },
            "<ProductUserId_2>": {
                "accounts": [
                    {
                        "accountId": <AccountId_2>",
                        "displayName": "<DisplayName_2>",
                        "identityProviderId": "<IdentityProvider_2>",
                        "lastLogin": "2022-01-05T10:25:38Z"
                    }
                ]
            }
        }
    }