连接网络API

使用连接接口网络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)>. Example: 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

请求示例

令牌响应

HTTP 响应 200 - OK: 成功。
HTTP头
名称
Content-Typeapplication/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_tokenID令牌,可安全识别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查询参数
名称类型描述
accountIdArray<String>外部账号ID列表,用于查询产品用户ID。输入的账号ID最多为16位数字。
identityProviderIdString 支持的身份供应商。 可用的值包括: Amazon, apple, discord, epicgames, gog, google, itchio, nintendo, oculus, Openid, psn, steam, xbl
environment字符串 如果外部账号系统使用了独立的账号环境,就必须指定一个环境。请查看平台供应商的文档,了解可用的环境值。否则请勿填入该栏位。

如果是Xbox,请使用 xbl_retail

响应示例

QueryExternalAccounts响应

HTTP 响应 200 - OK: 成功。
HTTP头
名称
Content-Typeapplication/json
JSON Payload
名称类型描述
idsObject <String, String>用于将外部账户ID映射到产品用户ID的对象。键是外部账户ID,值是产品用户ID。如果外部账户ID没有与产品用户ID相关联,它将被从响应中排除。

响应示例

查询产品用户

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

策略

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

授权

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

QueryProductUsers请求

HTTP请求GET /user/v1/product-users
HTTP头
名称名称
AuthorizationBearer <EOS client access token>
HTTP查询参数
名称类型描述
productUserIdArray <String>用于查询账户的产品用户ID列表。产品用户ID的最大输入数量是16。

响应示例

QueryProductUsers响应

HTTP 响应 200 - OK: 成功。
HTTP头
名称
Content-Typeapplication/json
JSON Payload
名称类型描述
productUsersObject <String, ProductUser>

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

ProductUser架构

ProductUser
名称类型描述
accountsArray<Account>产品用户的关联账户。

账户架构

账户(Account)
名称类型描述
accountIdString外部账户ID。
identityProviderId字符串

外部账户的身份提供者。新的身份提供者可能会被添加到列表中。支持的提供方默认包括:

  • amazon
  • apple
  • discord
  • epicgames
  • gog
  • google
  • itchio
  • nintendo
  • oculus
  • openid
  • psn
  • steam
  • xbl
displayName字符串 (可选)用户的显示名称。
lastLogin字符串最后登录时间,采用ISO 8601定义。

响应示例