身份验证
各个 Multiplay Hosting 服务中所要求的身份验证方法略有不同。
服务 | 身份验证类型 |
Unity Services Gatewayhttps://services.api.unity.com | 使用服务帐户密钥的基本身份验证。 |
Unity Game Gatewayhttps://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)>
这意味着您需要创建一个字符串,其中 KeyID 和 Secret key 用冒号分隔,然后对其进行 base64 编码。
许多 HTTP 库和工具内置了对基本身份验证的支持。在这种情况下,您可以使用 KeyID 作为用户名,Secret key 作为密码。
示例(列出版本)
以下示例介绍了如何创建标头并在 curl 请求中使用它来列出版本:
密钥 ID | Secret key |
9250f578-9ff1-4b75-afcc-7eca1e94db56 | 5d7f1a66-f29d-45c8-a6aa-a84242aa805f |
创建一个字符串,其中密钥 ID 和 Secret key 用冒号分隔,然后对其进行 base64 编码。
这样便会得到以下值:
OTI1MGY1NzgtOWZmMS00Yjc1LWFmY2MtN2VjYTFlOTRkYjU2OjVkN2YxYTY2LWYyOWQtNDVjOC1hNmFhLWE4NDI0MmFhODA1Zg==
现在可以将其用作授权标头,如下所示:
curl -X GET 'https://services.api.unity.com/multiplay/builds/v1/projects/<projectID>/environments/<environmentID>/builds \
--header 'Authorization: Basic OTI1MGY1NzgtOWZmMS00Yjc1LWFmY2MtN2VjYTFlOTRkYjU2OjVkN2YxYTY2LWYyOWQtNDVjOC1hNmFhLWE4NDI0MmFhODA1Zg=='
有关此终端以及 projectID
、environmentID
等所使用参数的更多信息,请参阅游戏服务器 API 文档。
Unity Game Gateway
Unity Game Gateway 使用持有者令牌进行身份验证。要获取持有者令牌,您必须先使用服务帐户从 Unity Game Gateway 请求一个具有时间限制的令牌。
- 通过令牌交换来检索访问令牌。请参阅身份验证 API 文档以了解更多信息。
- 使用访问令牌和持有者身份验证来向 Unity Game Gateway 终端发出请求。
- 推荐的最佳做法是重复使用令牌;但是,令牌会在一小时后过期,因此您必须在过期之前进行刷新。
该访问令牌是遵循 RFC 7519 的 JWT,可以由任何 JWT 库解析以提取准确的过期时间。
示例(列出分配):
以下示例展示了如何发出请求到列出分配终端。这包括两个步骤:
- 通过令牌交换来检索访问令牌。请参阅身份验证 API 文档以了解更多信息。
- 使用访问令牌和持有者身份验证来向列出分配终端发出请求。
# 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>'
有关此终端以及 projectID
、environmentID
和 fleetID
等所使用参数的更多信息,请参阅游戏服务器 API 文档。