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

# Início rápido (Windows) - Chamando o PlayFab Services

> Use o PFEntityHandle autenticado do SDK unificado do PlayFab para recuperar chaves de entidade e chamar APIs de serviço do PlayFab a partir de um título do Windows.

Este guia mostra como fazer chamadas às APIs de serviço do PlayFab usando o SDK unificado. Você aprenderá a chamar vários serviços do PlayFab para gerenciar os dados do jogador, recuperar arquivos e interagir com outros recursos do PlayFab.

## Pré-requisitos

Antes de começar, verifique se você:

* Concluiu a [configuração e autenticação do SDK Core](/pt-BR/services/playfab/sdks/unified-sdk/quickstart-core)
* Tem um `PFEntityHandle` autenticado obtido no processo de logon
* Configurou o ID do título e a configuração de serviço do PlayFab

<Note>
  Este guia pressupõe que você já inicializou o SDK do PlayFab e autenticou um jogador seguindo o [guia de início rápido do Core](/pt-BR/services/playfab/sdks/unified-sdk/quickstart-core). Se ainda não fez isso, conclua esse guia primeiro.
</Note>

## O que você vai realizar

Ao final deste início rápido, você terá:

* Recuperado a chave de entidade de um jogador autenticado
* Feito sua primeira chamada à API de serviço do PlayFab
* Processado a resposta de um serviço do PlayFab

## Fazendo sua primeira chamada à API de serviço

Após a autenticação bem-sucedida, você pode fazer chamadas à API do PlayFab usando o `PFEntityHandle` obtido durante o logon. Este exemplo mostra como recuperar os arquivos armazenados para o jogador atual.

### Etapa 1: Obter a chave de entidade

Primeiro, recupere a chave de entidade a partir do seu identificador de entidade autenticado:

```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;
```

### Etapa 2: Chamar a API GetFiles

Agora faça sua primeira chamada de serviço do PlayFab para obter os arquivos associados ao jogador:

```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;
}
```

🎉 **Parabéns!** Você fez com sucesso sua primeira chamada à API de serviço do PlayFab usando o SDK unificado.

## Entendendo o padrão de chamada à API

Todas as chamadas às APIs de serviço do PlayFab seguem um padrão semelhante:

1. **Preparar a requisição** - Crie e preencha uma estrutura de requisição
2. **Iniciar a chamada assíncrona** - Chame a função `*Async`
3. **Aguardar a conclusão** - Use `XAsyncGetStatus` para aguardar a operação
4. **Obter o tamanho do resultado** - Chame `*GetResultSize` para determinar o tamanho do buffer necessário
5. **Recuperar o resultado** - Chame `*GetResult` para obter os dados reais

Esse padrão se aplica a todas as APIs de serviço do PlayFab, o que facilita o trabalho com diferentes serviços depois que você entende o básico.

## Próximas etapas

Agora que você chamou com sucesso um serviço do PlayFab, explore estes recursos adicionais:

### APIs de serviço comuns

* **Gerenciamento de dados do jogador** - Armazene e recupere dados personalizados do jogador
* **Estatísticas do jogador** - Acompanhe as estatísticas e conquistas do jogador
* **Dados do título** - Acesse os dados de configuração do jogo
* **Cloud Script** - Execute lógica do lado do servidor

### Recursos avançados

* **Placares** - Implemente recursos competitivos com classificações
* **Economia e monetização** - Adicione moedas virtuais e itens
* **Multiplayer** - Integre os serviços de matchmaking e lobby
* **Análise** - Acompanhe o comportamento dos jogadores e as métricas do jogo

### Práticas recomendadas

* [Operações assíncronas](/pt-BR/services/playfab/sdks/unified-sdk/async-model) - Entendendo o modelo de programação assíncrona do PlayFab
* [Gerenciamento de memória](/pt-BR/services/playfab/sdks/unified-sdk/memory-management) - Práticas recomendadas para gerenciar a memória do SDK
* [Rastreamento e diagnóstico](/pt-BR/services/playfab/sdks/unified-sdk/debug-trace) - Depuração e monitoramento da sua integração

## Solução de problemas

**Problemas comuns e soluções:**

| Problema | Solução |
| - | - |
| Identificador de entidade inválido | Verifique se você concluiu a autenticação com sucesso |
| Tempo limite da chamada à API | Verifique a conectividade de rede e o status do serviço do PlayFab |
| Erros de acesso negado | Verifique o ID do título e as permissões da entidade |
| Erros de tamanho de buffer | Sempre chame `*GetResultSize` antes de `*GetResult` |

Para obter informações de erro mais detalhadas, habilite o [rastreamento e diagnóstico](/pt-BR/services/playfab/sdks/unified-sdk/debug-trace) no seu aplicativo.

## Documentação de referência

* [Referência da API do SDK unificado do PlayFab](/pt-BR/services/playfab/api-references/c/pfauthentication/pfauthentication_members)
* [Referência da API do PlayFab Services](/pt-BR/services/playfab/api-references)
* [Documentação da API Data do PlayFab](https://docs.microsoft.com/gaming/playfab/api-references/data/)


## Related topics

- [Início rápido](/pt-BR/services/playfab/economy-monetization/economy-v2/quickstart.md)
- [Início rápido (Windows) - Configuração do SDK Core](/pt-BR/services/playfab/sdks/unified-sdk/quickstart-core.md)
- [Início rápido Android](/pt-BR/services/playfab/sdks/c/quickstart-android.md)
- [Início rápido GDK](/pt-BR/services/playfab/sdks/c/quickstart-gdk.md)
- [Início rápido iOS](/pt-BR/services/playfab/sdks/c/quickstart-ios.md)