跳转到主要内容
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 选项用于配置你自己的登录,而不是你要向其授予访问权限的服务主体。

授权文件

set 会使用 --grants-file 的内容替换服务主体的所有授权,并删除文件中未包含的任何工作室权限或游戏。
请从当前授权开始,而不是从头编写文件。保存 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 失败,则在某次 set 成功之前,服务主体可能在工作室中没有任何访问权限,这可能会导致管道中断。
失败并不会说明授权是否已更改,因此不要使用旧版本再次运行 set。请运行 get,检查其授权和 Version;如果它们不是你想要设置的内容,请编辑该输出,并将其传递给 set,同时将其 Version 作为 --expected-version 传递。

示例

列出工作室的服务主体,并显示其中一个服务主体的授权:
使用 grants.json(你从 get 保存并编辑过的文件)中的授权替换服务主体的授权:
从工作室中删除服务主体及其授权:
执行 revoke 后,服务主体在该工作室中的下一个 PlayFab 请求会失败。当服务主体已经没有访问权限时,revoke 也会成功。若要恢复访问权限,请使用完整的授权集运行 set。
最后修改于 2026年11月19日