> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 服务主体

> 授予、检查和撤销 Entra 服务主体对工作室及其游戏的 PlayFab 访问权限。

`playfab service-principal` 命令系列属于实验性功能。其 CLI 接口可能会根据反馈而更改或被删除。

持续集成 (CI) 管道或其他无人参与的作业会以 Microsoft
Entra ID 服务主体身份登录;请参阅
[自动化(服务主体)身份验证](https://docs.xbox.com/zh-CN/tools/xbox-cli/authentication.md#automation-service-principal-authentication)。
只有在某人于 PlayFab 工作室中向服务主体授予访问权限后,PlayFab 才会接受该服务主体。这些命令用于管理这些授权。

只有对工作室拥有 **Admin** 权限且已登录的人员才能运行这些命令。当 `XBOX_AUTHENTICATION__MODE` 选择服务主体模式时,它们会拒绝运行,因此请改为使用 `xbox auth login` 登录。

| 命令 | PlayFab API 路径 | 说明 |
| - | - | - |
| `playfab service-principal list` | `/Studio/ListServicePrincipals` | 列出在工作室中注册的服务主体。 |
| `playfab service-principal get` | `/Studio/GetServicePrincipalAccess` | 显示一个服务主体的授权。 |
| `playfab service-principal set` | `/Studio/SetServicePrincipalAccess` | 根据需要注册服务主体,并**替换**其所有授权。 |
| `playfab service-principal revoke` | `/Studio/DeleteServicePrincipalAccess` | 从工作室中删除服务主体及其所有授权。会先询问;请参阅[安全性和破坏性操作](https://docs.xbox.com/zh-CN/tools/xbox-cli/safety.md)。 |

| 命令 | 选项 |
| - | - |
| `service-principal list` | `--studio-id`(必需)、`--limit`(1-100)、`--continuation-token`。 |
| `service-principal get` | `--studio-id`、`--principal-tenant-id`、`--principal-object-id`(均为必需)。 |
| `service-principal set` | `--studio-id`、`--principal-tenant-id`、`--principal-object-id`、`--display-name`、`--grants-file`(均为必需)、`--expected-version`。 |
| `service-principal revoke` | `--studio-id`、`--principal-tenant-id`、`--principal-object-id`(均为必需)。 |

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

## 授权文件

> [!WARNING]
>
> `set` 会使用 `--grants-file` 的内容替换服务主体的所有授权,并删除文件中未包含的任何工作室权限或游戏。

请从当前授权开始,而不是从头编写文件。保存 `get` 的输出,编辑其 `StudioPermissions` 和 `TitleGrants`,然后将其传递给 `set`,并将其
`Version` 作为 `--expected-version` 传递:

```bash theme={null}
xbox playfab service-principal get \
  --studio-id 1234567890ABCDEF \
  --principal-tenant-id 22222222-3333-4444-5555-666666666666 \
  --principal-object-id 33333333-4444-5555-6666-777777777777 \
  > grants.json
```

授权文件可以是 `get` 的完整输出、其 `data`、其中的 `ServicePrincipal` 对象,或者仅包含授权:

```json theme={null}
{
  "StudioPermissions": [],
  "TitleGrants": [
    { "TitleId": "ABC123", "Permissions": ["Admin"] }
  ]
}
```

* 这两个属性都是必需的。空列表表示不授予该类的任何内容。
* 每个游戏至少需要一个权限。若要删除某个游戏的授权,请不要包含该游戏。
* 属性名称不区分大小写。无法识别的属性会导致错误,因此拼写错误的 `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` 失败

> [!WARNING]
>
> 如果 `set` 失败,则在某次 `set` 成功之前,服务主体可能在工作室中没有任何访问权限,这可能会导致管道中断。

失败并不会说明授权是否已更改,因此不要使用旧版本再次运行 `set`。请运行 `get`,检查其授权和 `Version`;如果它们不是你想要设置的内容,请编辑该输出,并将其传递给 `set`,同时将其 `Version` 作为 `--expected-version` 传递。

## 示例

列出工作室的服务主体,并显示其中一个服务主体的授权:

```bash theme={null}
xbox playfab service-principal list \
  --studio-id 1234567890ABCDEF

xbox playfab service-principal get \
  --studio-id 1234567890ABCDEF \
  --principal-tenant-id 22222222-3333-4444-5555-666666666666 \
  --principal-object-id 33333333-4444-5555-6666-777777777777
```

使用 `grants.json`(你从 `get` 保存并编辑过的文件)中的授权替换服务主体的授权:

```bash theme={null}
xbox playfab service-principal set \
  --studio-id 1234567890ABCDEF \
  --principal-tenant-id 22222222-3333-4444-5555-666666666666 \
  --principal-object-id 33333333-4444-5555-6666-777777777777 \
  --display-name "Nod Publishers build" \
  --grants-file grants.json \
  --expected-version 3
```

从工作室中删除服务主体及其授权:

```bash theme={null}
xbox playfab service-principal revoke \
  --studio-id 1234567890ABCDEF \
  --principal-tenant-id 22222222-3333-4444-5555-666666666666 \
  --principal-object-id 33333333-4444-5555-6666-777777777777 \
  --confirm
```

执行 `revoke` 后,服务主体在该工作室中的下一个 PlayFab 请求会失败。当服务主体已经没有访问权限时,`revoke`
也会成功。若要恢复访问权限,请使用完整的授权集运行 `set`。


## Related topics

- [已知问题](https://docs.xbox.com/zh-CN/tools/xbox-cli/known-issues.md)
- [Auth](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands/auth.md)
- [身份验证](https://docs.xbox.com/zh-CN/tools/xbox-cli/authentication.md)
- [你的第一个游戏测试](https://docs.xbox.com/zh-CN/tools/xbox-cli/first-playtest.md)
- [上下文](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands/context.md)
