playfab service-principal 命令系列属于实验性功能。其 CLI 接口可能会根据反馈而更改或被删除。
持续集成 (CI) 管道或其他无人参与的作业会以 Microsoft
Entra ID 服务主体身份登录;请参阅
自动化(服务主体)身份验证。
只有在某人于 PlayFab 工作室中向服务主体授予访问权限后,PlayFab 才会接受该服务主体。这些命令用于管理这些授权。
只有对工作室拥有 Admin 权限且已登录的人员才能运行这些命令。当 XBOX_AUTHENTICATION__MODE 选择服务主体模式时,它们会拒绝运行,因此请改为使用 xbox auth login 登录。
list 接受 --output table;其他命令不接受。list 返回一页:当存在更多结果时,会设置响应的 ContinuationToken,将
--continuation-token 设置为该值并再次运行 list 即可获取下一页。
标识符
--studio-id指定拥有这些授权的工作室。这些命令不接受 PlayFab 游戏,因此--playfab-title-id和已保存的上下文不适用。--principal-tenant-id和--principal-object-id标识服务主体:其 Entra ID 租户,以及其企业应用程序(而不是其应用注册)的对象 ID。以服务主体身份登录时,xbox auth status会将其报告为objectId。- 你无需传递应用程序(客户端)ID。PlayFab 会从服务主体的第一个令牌中记录它,
list和get会将其报告为ClientId。 - 全局
--tenant-id和--client-id选项用于配置你自己的登录,而不是你要向其授予访问权限的服务主体。
授权文件
请从当前授权开始,而不是从头编写文件。保存get 的输出,编辑其 StudioPermissions 和 TitleGrants,然后将其传递给 set,并将其
Version 作为 --expected-version 传递:
get 的完整输出、其 data、其中的 ServicePrincipal 对象,或者仅包含授权:
- 这两个属性都是必需的。空列表表示不授予该类的任何内容。
- 每个游戏至少需要一个权限。若要删除某个游戏的授权,请不要包含该游戏。
- 属性名称不区分大小写。无法识别的属性会导致错误,因此拼写错误的
TitleGrants不会删除所有游戏授权。 - 文件中的
TenantId、ObjectId和DisplayName(如果存在)必须与--principal-tenant-id、--principal-object-id和--display-name匹配。若要重命名服务主体,请同时更改文件中的DisplayName,或将其删除。
预期版本
每次更改服务主体的授权都会为其赋予新的Version,get 和
set 会返回该版本。使用 --expected-version 时,除非授权仍处于该版本,否则 set 不会进行任何更改,因此它无法撤消他人在你读取授权后所做的更改。
--expected-version 0 要求服务主体尚无任何访问权限。如果不使用
--expected-version,则无论授权当前状态如何,set 都会替换它们。
当授权文件包含 Version 时,--expected-version 是必需的,并且必须与其相等。
如果两者不同,请再次运行 get,并在其输出上重新进行编辑。若要无条件替换授权,请从文件中删除 Version,并省略 --expected-version。
如果 set 失败
失败并不会说明授权是否已更改,因此不要使用旧版本再次运行 set。请运行 get,检查其授权和 Version;如果它们不是你想要设置的内容,请编辑该输出,并将其传递给 set,同时将其 Version 作为 --expected-version 传递。
示例
列出工作室的服务主体,并显示其中一个服务主体的授权:grants.json(你从 get 保存并编辑过的文件)中的授权替换服务主体的授权:
revoke 后,服务主体在该工作室中的下一个 PlayFab 请求会失败。当服务主体已经没有访问权限时,revoke
也会成功。若要恢复访问权限,请使用完整的授权集运行 set。