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

# 빠른 시작 (Windows) - PlayFab 서비스 호출

> PlayFab 통합 SDK에서 인증된 PFEntityHandle을 사용하여 Windows 타이틀에서 엔티티 키를 검색하고 PlayFab 서비스 API를 호출합니다.

이 가이드에서는 통합 SDK를 사용하여 PlayFab 서비스 API 호출을 만드는 방법을 안내합니다. 다양한 PlayFab 서비스를 호출하여 플레이어 데이터를 관리하고, 파일을 검색하며, 다른 PlayFab 기능과 상호 작용하는 방법을 배웁니다.

## 필수 조건

시작하기 전에 다음을 준비했는지 확인하세요:

* [Core SDK 설정 및 인증](/services/playfab/sdks/unified-sdk/quickstart-core) 완료
* 로그인 프로세스에서 인증된 `PFEntityHandle`
* PlayFab 타이틀 ID 및 서비스 구성 설정

<Note>
  이 가이드는 [Core 빠른 시작 가이드](/services/playfab/sdks/unified-sdk/quickstart-core)에 따라 이미 PlayFab SDK를 초기화하고 플레이어를 인증했다고 가정합니다. 아직 완료하지 않았다면, 먼저 해당 가이드를 완료하세요.
</Note>

## 달성하게 될 내용

이 빠른 시작이 끝나면 다음을 완료하게 됩니다:

* 인증된 플레이어의 엔티티 키 검색
* 첫 번째 PlayFab 서비스 API 호출 수행
* PlayFab 서비스의 응답 처리

## 첫 번째 서비스 API 호출 만들기

인증에 성공한 후, 로그인 시 얻은 `PFEntityHandle`을 사용하여 PlayFab API 호출을 만들 수 있습니다. 이 예제는 현재 플레이어에 대해 저장된 파일을 검색하는 방법을 보여줍니다.

### 1단계: 엔티티 키 얻기

먼저 인증된 엔티티 핸들에서 엔티티 키를 검색합니다:

```cpp theme={null}
PFEntityKey const* pEntityKey{};
std::vector<char> entityKeyBuffer;
size_t size{};
HRESULT hr = PFEntityGetEntityKeySize(entityHandle, &size);
if (FAILED(hr))
{
    std::wcerr << L"Failed to get entity key size: 0x" << std::hex << hr << std::endl;
    return hr;
}

entityKeyBuffer.resize(size);
hr = PFEntityGetEntityKey(entityHandle, entityKeyBuffer.size(), 
    entityKeyBuffer.data(), &pEntityKey, nullptr);
if (FAILED(hr))
{
    std::wcerr << L"Failed to get entity key: 0x" << std::hex << hr << std::endl;
    return hr;
}

std::wcout << L"Entity ID: " << pEntityKey->id << std::endl;
```

### 2단계: GetFiles API 호출

이제 플레이어와 연관된 파일을 얻기 위해 첫 번째 PlayFab 서비스 호출을 만듭니다:

```cpp theme={null}
// Prepare the request
XAsyncBlock async{};
PFDataGetFilesRequest requestFiles{};
requestFiles.entity = pEntityKey;  // Use the entity key from above

// Make the async API call
HRESULT hr = PFDataGetFilesAsync(entityHandle, &requestFiles, &async);
if (FAILED(hr))
{
    std::wcerr << L"Failed to start GetFiles request: 0x" << std::hex << hr << std::endl;
    return hr;
}

// Wait for the call to complete
hr = XAsyncGetStatus(&async, true);
if (FAILED(hr))
{
    std::wcerr << L"GetFiles request failed: 0x" << std::hex << hr << std::endl;
    return hr;
}

// Get the result size and allocate buffer
size_t resultSize;
hr = PFDataGetFilesGetResultSize(&async, &resultSize);
if (FAILED(hr))
{
    std::wcerr << L"Failed to get result size: 0x" << std::hex << hr << std::endl;
    return hr;
}

// Retrieve the actual result
std::vector<char> getFilesResultBuffer(resultSize);
PFDataGetFilesResponse* getFilesResponseResult{ nullptr };
hr = PFDataGetFilesGetResult(&async, getFilesResultBuffer.size(), 
    getFilesResultBuffer.data(), &getFilesResponseResult, nullptr);
if (SUCCEEDED(hr))
{
    std::wcout << L"Successfully retrieved files. Count: " 
               << (getFilesResponseResult->metadata ? getFilesResponseResult->metadataCount : 0) 
               << std::endl;
    
    // Process the files as needed
    if (getFilesResponseResult->metadata)
    {
        for (uint32_t i = 0; i < getFilesResponseResult->metadataCount; ++i)
        {
            std::wcout << L"File: " << getFilesResponseResult->metadata[i].fileName << std::endl;
        }
    }
}
else
{
    std::wcerr << L"Failed to get GetFiles result: 0x" << std::hex << hr << std::endl;
}
```

🎉 **축하합니다!** 통합 SDK를 사용하여 첫 번째 PlayFab 서비스 API 호출을 성공적으로 만들었습니다.

## API 호출 패턴 이해하기

모든 PlayFab 서비스 API 호출은 유사한 패턴을 따릅니다:

1. **요청 준비** - 요청 구조체를 만들고 채우기
2. **비동기 호출 시작** - `*Async` 함수 호출
3. **완료 대기** - `XAsyncGetStatus`를 사용하여 작업 대기
4. **결과 크기 얻기** - 버퍼 요구 사항을 결정하기 위해 `*GetResultSize` 호출
5. **결과 검색** - 실제 데이터를 얻기 위해 `*GetResult` 호출

이 패턴은 모든 PlayFab 서비스 API에 적용되므로, 기본 사항을 이해하면 다양한 서비스와 쉽게 작업할 수 있습니다.

## 다음 단계

이제 PlayFab 서비스를 성공적으로 호출했으므로, 이러한 추가 기능을 살펴보세요:

### 일반 서비스 API

* **플레이어 데이터 관리** - 사용자 정의 플레이어 데이터 저장 및 검색
* **플레이어 통계** - 플레이어 통계 및 업적 추적
* **타이틀 데이터** - 게임 구성 데이터에 액세스
* **Cloud Script** - 서버 측 로직 실행

### 고급 기능

* **리더보드** - 순위와 함께 경쟁 기능 구현
* **이코노미 및 수익화** - 가상 통화 및 아이템 추가
* **멀티플레이어** - 매치메이킹 및 로비 서비스 통합
* **분석** - 플레이어 행동 및 게임 지표 추적

### 모범 사례

* [비동기 작업](/services/playfab/sdks/unified-sdk/async-model) - PlayFab의 비동기 프로그래밍 모델 이해
* [메모리 관리](/services/playfab/sdks/unified-sdk/memory-management) - SDK 메모리 관리를 위한 모범 사례
* [추적 및 진단](/services/playfab/sdks/unified-sdk/debug-trace) - 통합 디버깅 및 모니터링

## 문제 해결

**일반적인 문제 및 해결 방법:**

| 문제          | 해결 방법                                      |
| ----------- | ------------------------------------------ |
| 잘못된 엔티티 핸들  | 인증을 성공적으로 완료했는지 확인하세요                      |
| API 호출 타임아웃 | 네트워크 연결 및 PlayFab 서비스 상태를 확인하세요            |
| 액세스 거부 오류   | 타이틀 ID 및 엔티티 권한을 확인하세요                     |
| 버퍼 크기 오류    | `*GetResult` 전에 항상 `*GetResultSize`를 호출하세요 |

더 자세한 오류 정보를 확인하려면, 애플리케이션에서 [추적 및 진단](/services/playfab/sdks/unified-sdk/debug-trace)을 활성화하세요.

## 참조 문서

* [PlayFab 통합 SDK API 참조](/services/playfab/api-references/c/pfauthentication/pfauthentication_members)
* [PlayFab Services API 참조](/services/playfab/api-references)
* [PlayFab Data API 문서](https://docs.microsoft.com/gaming/playfab/api-references/data/)


## Related topics

- [PlayFab 라이브 서비스 관리 문서](/ko/services/playfab/live-service-management/index.md)
- [다른 PlayFab 서비스와 실험 통합](/ko/services/playfab/live-service-management/game-configuration/experiments/experiments-other-services.md)
- [PlayFab로 백엔드 서비스 추가하기](/ko/home/build-first-title/add-backend-services.md)
- [Unity 빠른 시작](/ko/services/playfab/sdks/unity3d/quickstart.md)
- [빠른 시작 (Windows) - Core SDK 설정](/ko/services/playfab/sdks/unified-sdk/quickstart-core.md)