你可以通过网络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)> . Example: 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 |
请求示例
令牌响应
HTTP 响应 200 - OK: 成功。 | ||
HTTP头 | ||
名称 | 值 | |
Content-Type | application/json | |
JSON Payload | ||
名称 | 描述 | |
access_token | 将访问令牌生成为JSON Web Token(JWT)字符串。访问令牌说明了验证的客户端和用户。 | |
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>
.
响应示例
查询外部账号
请求 queryExternalAccountsForAnyUser
会从外部账号ID列表中返回相应的产品用户ID。
政策
客户端必须启用连接功能的 queryExternalAccountsForAnyUser
客户端政策操作。
授权
这一调用需要使用EOS客户端访问令牌进行Bearer令牌授权。
QueryExternalAccounts请求
HTTP请求 | GET /user/v1/accounts | ||
HTTP头 | |||
名称 | 值 | ||
授权(Authorization) | Bearer <EOS client access token> | ||
HTTP查询参数 | |||
名称 | 类型 | 描述 | |
accountId | Array<String> | 外部账号ID列表,用于查询产品用户ID。输入的账号ID最多为16位数字。 | |
identityProviderId | String | 支持的身份供应商。 可用的值包括: Amazon , apple , discord , epicgames , gog , google , itchio , nintendo , oculus , Openid , psn , steam , xbl 。 | |
environment | 字符串 | 如果外部账号系统使用了独立的账号环境,就必须指定一个环境。请查看平台供应商的文档,了解可用的环境值。否则请勿填入该栏位。 如果是Xbox,请使用 xbl_retail 。 |
响应示例
QueryExternalAccounts响应
HTTP 响应 200 - OK: 成功。 | ||
HTTP头 | ||
名称 | 值 | |
Content-Type | application/json | |
JSON Payload | ||
名称 | 类型 | 描述 |
ids | Object <String, String> | 用于将外部账户ID映射到产品用户ID的对象。键是外部账户ID,值是产品用户ID。如果外部账户ID没有与产品用户ID相关联,它将被从响应中排除。 |
响应示例
查询产品用户
queryProductUsersForAnyUser
请求用于从产品用户列表中返回相关账户。
策略
客户端必须为连接功能启用 queryProductUsersForAnyUser
客户端策略动作。
授权
该调用需要使用EOS客户端访问令牌和Bearer令牌授权。
QueryProductUsers请求
HTTP请求 | GET /user/v1/product-users | |
HTTP头 | ||
名称 | 名称 | |
Authorization | Bearer <EOS client access token> | |
HTTP查询参数 | ||
名称 | 类型 | 描述 |
productUserId | Array <String> | 用于查询账户的产品用户ID列表。产品用户ID的最大输入数量是16。 |
响应示例
QueryProductUsers响应
HTTP 响应 200 - OK: 成功。 | ||
HTTP头 | ||
名称 | 值 | |
Content-Type | application/json | |
JSON Payload | ||
名称 | 类型 | 描述 |
productUsers | Object <String, ProductUser> | 用于将产品用户ID映射到账户的对象。如果没有找到产品用户ID,它将被排除在响应外。 |
ProductUser架构
ProductUser | ||
名称 | 类型 | 描述 |
accounts | Array<Account> | 产品用户的关联账户。 |
账户架构
账户(Account) | ||
名称 | 类型 | 描述 |
accountId | String | 外部账户ID。 |
identityProviderId | 字符串 | 外部账户的身份提供者。新的身份提供者可能会被添加到列表中。支持的提供方默认包括:
|
displayName | 字符串 (可选) | 用户的显示名称。 |
lastLogin | 字符串 | 最后登录时间,采用ISO 8601定义。 |