Connect Web APIs

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

阅读时间7分钟

你可以通过网络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消息头

名称
AuthorizationBasic <Base64(ClientId:ClientSecret)>.示例: Basic Q2xpZW50SWQ6Q2xpZW50U2VjcmV0
Content-Typeapplication/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-Typeapplication/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_tokenID令牌,可安全识别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, xbl
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-Typeapplication/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请求 GET /user/v1/product-users
HTTP头
名称
授权(Authorization) Bearer <EOS client access token>
HTTP查询参数
名称 类型 说明
产品用户ID(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,它将被排除在响应外。
HTTP Response 200 - OK: Success.
HTTP头
名称
Content-Type application/json
JSON Payload
名称 类型 说明
产品用户(productUsers) Object <String, ProductUser> 键是一个产品用户ID。 用于将产品用户ID映射到账户的对象。如果没有找到产品用户ID,它将被排除在响应外。

Schema

产品用户(ProductUser)
名称 类型 说明
账户 Array<Account> 产品用户的关联账户。
账户(Account)
名称 类型 说明
accountId 字符串 外部账户ID。
identityProviderId 字符串

外部账户的身份提供者。支持的提供方包括:

  • amazon
  • apple
  • discord
  • epicgames
  • gog
  • google
  • itchio
  • nintendo
  • oculus
  • openid
  • psn
  • steam
  • xbl

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

displayName 字符串(可选) 用户的显示名称。
lastLogin 字符串 最后登录时间。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"
}
]
}
}
}