> ## 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 GDK > Adicione a biblioteca de extensão do SDK do PlayFab Services para C a um título do Microsoft GDK e faça sua primeira chamada à API do PlayFab a partir de código do GDK para XBOX ou Windows. # Início rápido: GDK Comece a usar o SDK do PlayFab Services para o Microsoft Game Development Kit (GDK). Siga estas etapas para incluir as bibliotecas no seu projeto e experimentar o código de exemplo da funcionalidade básica do PlayFab. Este início rápido ajuda você a fazer sua primeira chamada à API do PlayFab usando o GDK. Antes de continuar, verifique se você concluiu as etapas de [Início rápido: Game Manager](/pt-BR/services/playfab/live-service-management/gamemanager/quickstart), que garantem que você tenha uma conta do PlayFab e esteja familiarizado com o PlayFab Game Manager. ## Requisitos * Uma [conta de desenvolvedor do PlayFab](https://developer.playfab.com). * [Visual Studio 2019 ou 2022](https://visualstudio.microsoft.com/) instalado. * Para obter mais informações sobre os requisitos do Visual Studio para o desenvolvimento com o GDK, consulte [Requisitos do SDK e das ferramentas](https://learn.microsoft.com/en-us/gaming/gdk/_content/gc/getstarted/overviews/sdk-and-tools#install-visual-studio). ## Configuração do projeto Assim como outras bibliotecas de extensão do GDK, adicione o SDK do PlayFab Services pelas propriedades do projeto. Nas Configuration Properties do projeto, em **Gaming Desktop** > **General**, selecione **Gaming Extension Libraries**. No prompt, marque **PlayFab.Services.C**. Selecionar a biblioteca de extensão PlayFab.Services.C ## Inicialização e login ### Cabeçalhos Inclua **PFServices.h** para ter acesso a toda a funcionalidade do PlayFab incluída: ```cpp theme={null} #include ``` ### Inicialização A inicialização do PlayFab requer duas chamadas de função: **PFServicesInitialize** e **PFServiceConfigCreateHandle**. O resultado dessa inicialização é um **PFServiceConfigHandle**. Você fornece esse identificador a uma chamada de login subsequente, direcionando a chamada para o título correto no back-end do PlayFab. ```cpp theme={null} HRESULT hr = PFServicesInitialize(nullptr); // Add your own error handling when FAILED(hr) == true PFServiceConfigHandle serviceConfigHandle{ nullptr }; hr = PFServiceConfigCreateHandle( "https://ABCDEF.playfabapi.com", // PlayFab API endpoint - obtained in the Game Manager "ABCDEF", // PlayFab Title id - obtained in the Game Manager &serviceConfigHandle); ``` ### Fazendo login Depois de ter um **PFServiceConfigHandle**, você pode usá-lo para fazer uma chamada de login de jogador. No GDK, use **PFAuthenticationLoginWithXUserAsync**. Essa função permite fazer login de um jogador no PlayFab usando um **XUserHandle**. Para saber mais sobre como obter e gerenciar um **XUserHandle**, consulte [Identidade do usuário e XUser](/pt-BR/build/core-features/common/user/player-identity-xuser). Depois de fazer uma chamada de login, você pode verificar o status da chamada com **XAsyncGetStatus**. O status começa como **E\_PENDING** e muda para **S\_OK** depois que a chamada é concluída com êxito. Se a chamada falhar por algum motivo, o status refletirá essa falha. O tratamento de erros em todas as chamadas do PlayFab Services funciona dessa forma. Junto com um resultado **S\_OK**, você recebe um **PFEntityHandle**. Use esse identificador para fazer as chamadas subsequentes do PlayFab como o jogador conectado. Ele inclui todo o material necessário para se autenticar no serviço PlayFab como esse jogador. ```cpp theme={null} PFAuthenticationLoginWithXUserRequest request{}; request.createAccount = true; request.user = userHandle; // An XUserHandle obtained from XUserAddAsync XAsyncBlock async{}; HRESULT hr = PFAuthenticationLoginWithXUserAsync(serviceConfigHandle, &request, &async); // Add your own error handling when FAILED(hr) == true hr = XAsyncGetStatus(&async, true); // This is doing a blocking wait for completion, but you can use the XAsyncBlock to set a callback instead for async style usage std::vector loginResultBuffer; PFAuthenticationLoginResult const* loginResult; size_t bufferSize; hr = PFAuthenticationLoginWithXUserGetResultSize(&async, &bufferSize); loginResultBuffer.resize(bufferSize); PFEntityHandle entityHandle{ nullptr }; hr = PFAuthenticationLoginWithXUserGetResult(&async, &entityHandle, loginResultBuffer.size(), loginResultBuffer.data(), &loginResult, nullptr); ``` ## Tratando a suspensão e a retomada Os jogos do GDK podem ficar suspensos por longos períodos (por exemplo, por meio do Quick Resume). Se o token de entidade expirar durante a suspensão, o SDK detectará isso na retomada e notificará seu jogo. Você deve se registrar no **TokenExpiredHandler** no início do ciclo de vida do jogo para poder se autenticar novamente e reconectar os serviços quando necessário. Para obter todos os detalhes, consulte [Tratando a expiração de tokens](/pt-BR/services/playfab/sdks/c/relogin). ## Chamadas de serviço Depois de fazer login do jogador, você pode fazer chamadas ao back-end do PlayFab. Veja um exemplo de chamada para obter os arquivos armazenados no PlayFab para o jogador atual. ### Obtendo a EntityKey Algo que pode ser útil em algumas chamadas ao PlayFab é conhecer a **PFEntityKey** do jogador. Depois de ter um **PFEntityToken**, você pode recuperar uma **PFEntityKey** com **PFEntityGetEntityKey**. ```cpp theme={null} PFEntityKey const* pEntityKey{}; std::vector entityKeyBuffer; size_t size{}; HRESULT hr = PFEntityGetEntityKeySize(entityHandle, &size); // Add your own error handling when FAILED(hr) == true entityKeyBuffer.resize(size); hr = PFEntityGetEntityKey(entityHandle, entityKeyBuffer.size(), entityKeyBuffer.data(), &pEntityKey, nullptr); ``` ### Chamando GetFiles Todas as chamadas do PlayFab seguem um padrão semelhante: preparar o objeto de solicitação, fazer a chamada (usando o **PFEntityHandle** do login), criar um objeto para receber a resposta e, em seguida, chamar uma função **GetResult** para preencher o contêiner recém-criado. ```cpp theme={null} XAsyncBlock async{}; PFDataGetFilesRequest requestFiles{}; requestFiles.entity = pEntityKey; HRESULT hr = PFDataGetFilesAsync(entityHandle, &requestFiles, &async); // Add your own error handling when FAILED(hr) == true hr = XAsyncGetStatus(&async, true); // This is doing a blocking wait for completion, but you can use the XAsyncBlock to set a callback instead for async style usage size_t resultSize; hr = PFDataGetFilesGetResultSize(&async, &resultSize); std::vector getFilesResultBuffer(resultSize); PFDataGetFilesResponse* getFilesResponseResult{ nullptr }; hr = PFDataGetFilesGetResult(&async, getFilesResultBuffer.size(), getFilesResultBuffer.data(), &getFilesResponseResult, nullptr); ``` ## Limpeza Quando seu jogo estiver pronto para ser desligado ou você precisar limpar o PlayFab por algum outro motivo, feche todos os identificadores abertos e chame **PFServicesUninitializeAsync**. ```cpp theme={null} PFEntityCloseHandle(entityHandle); entityHandle = nullptr; PFServiceConfigCloseHandle(serviceConfigHandle); serviceConfigHandle = nullptr; XAsyncBlock async{}; HRESULT hr = PFServicesUninitializeAsync(&async); // Add your own error handling when FAILED(hr) == true hr = XAsyncGetStatus(&async, true); // This is doing a blocking wait for completion, but you can use the XAsyncBlock to set a callback instead for async style usage ``` ## Padrão de API assíncrona O SDK do PlayFab Services para o GDK segue o [modelo de programação assíncrona](https://learn.microsoft.com/en-us/gaming/gdk/_content/gc/system/overviews/async-programming-model) implementado no GDK. Esse modelo de programação envolve o uso de tarefas e filas de tarefas fornecidas pela [biblioteca XAsync](/pt-BR/build/core-features/common/async/async-libraries/async-library-xasync). Esse modelo é consistente com outras funções e extensões do GDK (como a API do XBOX Services). Embora introduza alguma complexidade, ele também oferece um alto grau de controle sobre as operações assíncronas. Este exemplo mostra como fazer uma chamada assíncrona a **PFDataGetFilesAsync**. ```cpp theme={null} auto async = std::make_unique(); async->callback = [](XAsyncBlock* async) { std::unique_ptr asyncBlockPtr{ async }; // take ownership of XAsyncBlock size_t resultSize; HRESULT hr = PFDataGetFilesGetResultSize(async, &resultSize); if (SUCCEEDED(hr)) { std::vector getFilesResultBuffer(resultSize); PFDataGetFilesResponse* getFilesResponseResult{ nullptr }; PFDataGetFilesGetResult(async, getFilesResultBuffer.size(), getFilesResultBuffer.data(), &getFilesResponseResult, nullptr); } }; PFDataGetFilesRequest requestFiles{}; requestFiles.entity = m_pEntityKey; HRESULT hr = PFDataGetFilesAsync(m_entityHandle, &requestFiles, async.get()); if (SUCCEEDED(hr)) { async.release(); // at this point, the callback will be called so release the unique ptr } ``` ## Tratamento de erros As operações **XAsync** concluídas retornam códigos de status HTTP. Um código de status de erro se manifesta como um **HRESULT** de falha, como **HTTP\_E\_STATUS\_NOT\_FOUND**, ao chamar **XAsyncGetStatus()** ou uma das APIs **PF\*Get()**. Para ver as mensagens de erro detalhadas retornadas pelo serviço, consulte a próxima seção sobre depuração. Essas mensagens de erro detalhadas podem ser úteis durante o desenvolvimento para entender melhor como o serviço PlayFab reage às solicitações do cliente. ## Depuração A maneira mais fácil de ver os resultados e depurar qualquer chamada no SDK do PlayFab Services é habilitar o [rastreamento de depuração](/pt-BR/services/playfab/sdks/c/tracing). Habilitar o rastreamento de depuração permite tanto ver os resultados na janela de saída do depurador quanto conectar os resultados aos logs do próprio jogo. ## Referência [Documentação de referência da API](/pt-BR/services/playfab/api-references/c/pfauthentication/pfauthentication_members) ## Related topics - [Início rápido](/pt-BR/services/playfab/economy-monetization/economy-v2/quickstart.md) - [Início rápido Linux](/pt-BR/services/playfab/sdks/c/quickstart-linux.md) - [Início rápido Android](/pt-BR/services/playfab/sdks/c/quickstart-android.md) - [Início rápido iOS](/pt-BR/services/playfab/sdks/c/quickstart-ios.md) - [Início rápido Win32](/pt-BR/services/playfab/sdks/c/quickstart-win32.md)