身份验证

各个 Multiplay Hosting 服务中所要求的身份验证方法略有不同。

服务身份验证类型
Unity Services Gateway
https://services.api.unity.com
使用服务帐户密钥的基本身份验证。
Unity Game Gateway
https://multiplay.services.api.unity.com
来自令牌交换的持有者令牌。

变更 Multiplay Hosting 资源的管理 API 调用使用 Unity Service Gateway

游戏生命周期 API 调用(例如分配和取消分配)使用 Unity Game Gateway

服务器身份验证

服务器身份验证与服务器相关联,可以在 Multiplay Hosting 机器上运行时实现。

这种身份验证可用于游戏网关。

您可以通过以下方式检索 Multiplay Hosting 令牌:

  • 使用脚本 API 和 Authentication 包
  • 通过本地请求手动检索

使用脚本 API 和 Authentication 包

使用 Authentication 包中的以下调用:

await ServerAuthenticationService.Instance.SignInFromServerAsync();
var token = ServerAuthenticationService.Instance.AccessToken;

还可以使用服务帐户进行身份验证:

await ServerAuthenticationService.Instance.SignInWithServiceAccountAsync(apiKeyIdentifier, apiKeySecret);

注意:服务帐户必须具有 Unity Environments Viewer(Unity 环境查看者)角色才能查找可用的环境。

请参阅服务帐户

手动获取令牌

也可以通过本地请求手动获取令牌:

curl -X GET http://localhost:8086/v4/token

该请求将返回以下格式的响应:

{"token":"<BEARER_TOKEN>", "error":""}

服务帐户

所有 API 身份验证都需要服务帐户。

如果您没有具有合适角色的服务帐户来执行所需的请求,请参阅创建服务帐户

服务帐户和身份验证主要用于获取管理权限。服务器身份验证代替了可信游戏服务。

Unity Services Gateway

使用 Unity Services Gateway (USG) 来对各种管理 API 进行认证,例如管理版本、版本配置、机群以及其他 Multiplay Hosting 资源。

使用基本身份验证来对 API 调用进行认证。

Authorization: Basic <base64(keyID:keySecret)>

这意味着您需要创建一个字符串,其中 KeyIDSecret key 用冒号分隔,然后对其进行 base64 编码。

许多 HTTP 库和工具内置了对基本身份验证的支持。在这种情况下,您可以使用 KeyID 作为用户名,Secret key 作为密码。

示例(列出版本)

以下示例介绍了如何创建标头并在 curl 请求中使用它来列出版本:

密钥 IDSecret key
9250f578-9ff1-4b75-afcc-7eca1e94db565d7f1a66-f29d-45c8-a6aa-a84242aa805f

创建一个字符串,其中密钥 IDSecret key 用冒号分隔,然后对其进行 base64 编码。

这样便会得到以下值:

OTI1MGY1NzgtOWZmMS00Yjc1LWFmY2MtN2VjYTFlOTRkYjU2OjVkN2YxYTY2LWYyOWQtNDVjOC1hNmFhLWE4NDI0MmFhODA1Zg==

现在可以将其用作授权标头,如下所示:

curl -X GET 'https://services.api.unity.com/multiplay/builds/v1/projects/<projectID>/environments/<environmentID>/builds \
--header 'Authorization: Basic OTI1MGY1NzgtOWZmMS00Yjc1LWFmY2MtN2VjYTFlOTRkYjU2OjVkN2YxYTY2LWYyOWQtNDVjOC1hNmFhLWE4NDI0MmFhODA1Zg=='

有关此终端以及 projectIDenvironmentID 等所使用参数的更多信息,请参阅游戏服务器 API 文档

Unity Game Gateway

Unity Game Gateway 使用持有者令牌进行身份验证。要获取持有者令牌,您必须先使用服务帐户从 Unity Game Gateway 请求一个具有时间限制的令牌。

  1. 通过令牌交换来检索访问令牌。请参阅身份验证 API 文档以了解更多信息。
  2. 使用访问令牌和持有者身份验证来向 Unity Game Gateway 终端发出请求。
  3. 推荐的最佳做法是重复使用令牌;但是,令牌会在一小时后过期,因此您必须在过期之前进行刷新。

该访问令牌是遵循 RFC 7519 的 JWT,可以由任何 JWT 库解析以提取准确的过期时间。

示例(列出分配):

以下示例展示了如何发出请求到列出分配终端。这包括两个步骤:

  1. 通过令牌交换来检索访问令牌。请参阅身份验证 API 文档以了解更多信息。
  2. 使用访问令牌和持有者身份验证来向列出分配终端发出请求。
# Get the token from the token exchange endpoint
curl -X POST 'https://services.api.unity.com/auth/v1/token-exchange?projectId=<projectID>&environmentId=<environmentID>' \
--header 'Authorization: Basic  <base64(keyID:keySecret)>' \
--header 'Content-Type: application/json' \
--data-raw '{
   "scopes": []
}'

并收到以下响应:

{
    "accessToken": <accessToken>
}

在向 Unity Game Gateway 服务发出的后续请求中,可以将 accessToken 字符串与持有者身份验证一起使用。例如,要列出分配,请执行以下操作:

# Make the list allocations request
curl -X GET 'https://multiplay.services.api.unity.com/v1/allocations/projects/<projectID>/environments/<environmentID>/fleets/<fleetID>/allocations \
--header 'Authorization: Bearer <accessToken>'

有关此终端以及 projectIDenvironmentIDfleetID 等所使用参数的更多信息,请参阅游戏服务器 API 文档