连接网络API

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

阅读时间7分钟

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

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

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

EOS连接令牌端点如下：

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

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

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

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

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令牌授权。

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`。

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

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

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

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

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

HTTP 响应 200 - OK: 成功。
HTTP头
名称	值
`Content-Type`	`application/json`
JSON Payload
名称	类型	描述
`productUsers`	Object <String, ProductUser>	用于将产品用户ID映射到账户的对象。如果没有找到产品用户ID，它将被排除在响应外。

ProductUser架构

账户架构

账户（Account）
名称	类型	描述
`accountId`	String	外部账户ID。
`identityProviderId`	字符串	外部账户的身份提供者。新的身份提供者可能会被添加到列表中。支持的提供方默认包括： `amazon` `apple` `discord` `epicgames` `gog` `google` `itchio` `nintendo` `oculus` `openid` `psn` `steam` `xbl`
`displayName`	字符串 (可选)	用户的显示名称。
`lastLogin`	字符串	最后登录时间，采用ISO 8601定义。