> ## 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.

# PlayFab API 통합

> 타이틀 비밀 키 대신 Microsoft Entra ID 개발자 자격 증명을 사용하여 터미널에서 PlayFab API를 찾고 호출합니다.

XBOX CLI는 타이틀 비밀 키 또는 타이틀 엔터티 토큰을 허용하는 모든 PlayFab API를
대신 Microsoft Entra ID 개발자 자격 증명을 사용하여 호출할 수 있습니다. 플레이어 또는 게임 서버
엔터티 토큰만 허용하는 API는 이 방식으로 권한이 부여되지 않습니다.

PlayFab 타이틀에 대한 **Admin** 권한이 필요합니다.
[PlayFab 인증 작동 방식](https://docs.xbox.com/ko/tools/xbox-cli/authentication.md#how-playfab-authentication-works)을 참조하세요.

## 설정

로그인하고, PlayFab 타이틀 ID를 기본값으로 저장하고, 읽기 전용 요청을 보냅니다.
`ABC123`을 사용자의 타이틀 ID로 바꾸세요.

```bash theme={null}
xbox auth login
xbox context set playfab-title-id ABC123
xbox playfab api /Admin/GetTitleData
```

명령 하나에 다른 타이틀을 사용하려면 `--playfab-title-id`를 전달합니다.
[컨텍스트](https://docs.xbox.com/ko/tools/xbox-cli/commands/context.md)를 참조하세요.

## API 찾기

PlayFab은 모든 작업과 해당 요청 및 응답 스키마, 필수 필드,
허용되는 자격 증명을 문서화합니다.

* [PlayFab REST API 참조](https://learn.microsoft.com/rest/api/playfab/)는
  사람을 위해 작성되었습니다.
* [PlayFab Swagger 사양](https://github.com/PlayFab/API_Specs/tree/master/Swagger/PlayFab)은
  컴퓨터가 읽을 수 있는 형식입니다. 파일 이름은 경로의 첫 번째 세그먼트가 아니라 PlayFab의 API 그룹을
  기준으로 지정되므로, 파일의 `paths`에서 작업을 검색하세요. 예를 들어 `/Catalog`
  및 `/Inventory`는 `Economy.swagger.json`에 있고, `/Match`, `/Lobby` 및
  `/MultiplayerServer`는 `Multiplayer.swagger.json`에 있습니다.
* 각 작업의 `security` 필드는 허용되는 자격 증명을 지정합니다. `SecretKey`(타이틀
  비밀 키), `EntityToken`, `SessionTicket`(플레이어 세션) 또는 `None`입니다. 일부
  작업은 설명에 허용되는 엔터티 토큰 유형도 나열합니다.

API 경로는 `/Admin/GetTitleData`와 같은 `/<Prefix>/<Operation>`이며, 요청
본문은 작업의 JSON 요청 개체입니다.

## 예

이 예에서는 전체 옵션 참조가 있는 [`playfab api`](https://docs.xbox.com/ko/tools/xbox-cli/commands/playfab/api)로
API를 호출합니다. `Delete*` 및 `Shutdown*` 작업은 터미널에서는 먼저 확인을 요청하고, 그 외의 환경에서는
`--confirm`이 필요합니다. [안전 및 파괴적 작업](https://docs.xbox.com/ko/tools/xbox-cli/safety.md)을 참조하세요.

### 타이틀 데이터 가져오기

```bash theme={null}
xbox --playfab-title-id ABC123 playfab api /Admin/GetTitleData
```

```json theme={null}
{
  "code": 200,
  "status": "OK",
  "data": {
    "Data": {
      "SettingA": "the value",
      "SettingB": "another value"
    }
  }
}
```

### 타이틀 데이터 키 하나 가져오기

```bash theme={null}
xbox --playfab-title-id ABC123 playfab api /Admin/GetTitleData --body '{"Keys":["MyKey"]}'
```

### 타이틀 데이터 설정

`--body`로 요청 본문을 인라인으로 전달합니다.

```bash theme={null}
xbox --playfab-title-id ABC123 playfab api /Admin/SetTitleData --body '{ "Key": "MyKey", "Value": "my-value" }'
```

```json theme={null}
{
  "code": 200,
  "status": "OK",
  "data": {}
}
```

또는 `--body-file`로 파일에서 읽습니다. 다음은 PowerShell의 예입니다.

```powershell theme={null}
'{ "Key": "MyKey", "Value": "my-value" }' > data.json
xbox --playfab-title-id ABC123 playfab api /Admin/SetTitleData --body-file data.json
```

### 데이터만 한 줄로 가져오기

`--data-only`는 응답 봉투를 제거하고, `--output json-compact`는 파이프용 한 줄
JSON을 작성합니다.

```bash theme={null}
xbox --playfab-title-id ABC123 --data-only --output json-compact playfab api /Admin/GetTitleData
```

```json theme={null}
{"Data":{"MyKey":"my-value"}}
```

## 오류 응답

실패한 호출은 코드 `1`로 종료합니다.

* PlayFab이 오류를 반환하면 명령은 `--output`에 따라 서식이 지정된 PlayFab의 오류 JSON을
  stderr에 작성합니다.
* 네트워크 오류와 같은 다른 실패는 일반 텍스트 메시지를 stderr에 작성합니다.
* `--data-only`를 사용하면 오류 시 stdout이 비어 있습니다.


## Related topics

- [C# PlayFab SDK](https://docs.xbox.com/ko/services/playfab/sdks/c-sharp/index.md)
- [PlayFab 통합 SDK](https://docs.xbox.com/ko/services/playfab/sdks/unified-sdk/overview.md)
- [빠른 시작 (Windows) - PlayFab 서비스 호출](https://docs.xbox.com/ko/services/playfab/sdks/unified-sdk/quickstart-services.md)
- [XBOX services 타이틀을 위한 PlayFab 통합](https://docs.xbox.com/ko/services/xbox-services/playfab-integration.md)
- [다른 PlayFab 서비스와 실험 통합](https://docs.xbox.com/ko/services/playfab/live-service-management/game-configuration/experiments/experiments-other-services.md)
