Freigeben über


Schnellstart: GDK

Erste Schritte mit dem PlayFab Services SDK für das Microsoft Game Development Kit (GDK). Führen Sie die folgenden Schritte aus, um die Bibliotheken in Ihr Projekt einzuschließen und den Beispielcode für die grundlegende PlayFab-Funktionalität auszuprobieren.

In dieser Schnellstartanleitung erfahren Sie, wie Sie Ihren ersten PlayFab-API-Aufruf mithilfe des GDK ausführen. Bevor Sie fortfahren, stellen Sie sicher, dass Sie die Schritte unter Schnellstart: Game Manager ausgeführt haben, um sicherzustellen, dass Sie über ein PlayFab-Konto verfügen und mit dem PlayFab-Spiel-Manager vertraut sind.

Voraussetzungen

Projekteinrichtung

Fügen Sie ähnlich wie bei anderen GDK-Erweiterungsbibliotheken das PlayFab Services SDK über Projekteigenschaften hinzu. Wählen Sie in den Konfigurationseigenschaften Ihres Projekts unter Gaming Desktop>Allgemein die Option Gaming-Erweiterungsbibliotheken aus. Überprüfen Sie an der Eingabeaufforderung PlayFab.Services.C.

Auswählen der PlayFab.Services.C-Erweiterungsbibliothek

Initialisieren und Anmelden

Header

Fügen Sie PFServices.h ein, um Zugriff auf alle enthaltenen PlayFab-Funktionen zu erhalten:

#include <playfab/services/PFServices.h>

Initialisierung

Für die PlayFab-Initialisierung sind zwei Funktionsaufrufe erforderlich: PFServicesInitialize und PFServiceConfigCreateHandle. Das Ergebnis dieser Initialisierung ist pfServiceConfigHandle. Sie stellen dieses Handle für einen nachfolgenden Anmeldeaufruf bereit und leiten den Aufruf an den richtigen Titel im PlayFab-Back-End weiter.

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

Anmelden

Sobald Sie über eine PFServiceConfigHandle verfügen, können Sie es verwenden, um einen Spieleranmeldeanruf zu tätigen. Verwenden Sie im GDK PFAuthenticationLoginWithXUserAsync. Mit dieser Funktion können Sie sich mit einem XUserHandle bei PlayFab anmelden. Weitere Informationen zum Abrufen und Verwalten eines XUserHandle-Elements finden Sie unter Benutzeridentität und XUser.

Nach dem Tätigen eines Anmeldeaufrufs können Sie die status des Anrufs mit XAsyncGetStatus überprüfen. Die status beginnt als E_PENDING und ändert sich in S_OK, nachdem der Aufruf erfolgreich abgeschlossen wurde. Wenn der Aufruf aus irgendeinem Grund fehlschlägt, spiegelt die status diesen Fehler wider. Die Fehlerbehandlung bei allen PlayFab Services-Aufrufen funktioniert auf diese Weise.

Zusammen mit einem S_OK Ergebnis erhalten Sie ein PFEntityHandle zurück. Sie verwenden dieses Handle, um nachfolgende PlayFab-Aufrufe als angemeldeter Spieler zu tätigen. Es enthält alle Materialien, die für die Authentifizierung beim PlayFab-Dienst als betreffenden Spieler erforderlich sind.

    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<char> 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);

Dienstaufrufe

Nach der Anmeldung des Players können Sie jetzt Aufrufe an das PlayFab-Back-End senden. Hier sehen Sie ein Beispiel für einen Aufruf zum Abrufen von Dateien, die in PlayFab für den aktuellen Player gespeichert sind.

Abrufen des EntityKey

Eine Sache, die für einige Aufrufe an PlayFab nützlich sein kann, ist die Kenntnis des PFEntityKey des Spielers. Sobald Sie über ein PFEntityToken verfügen, können Sie einen PFEntityKey mit PFEntityGetEntityKey abrufen.

    PFEntityKey const* pEntityKey{};
    std::vector<char> 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);

Aufrufen von GetFiles

Alle PlayFab-Aufrufe folgen einem ähnlichen Muster: Vorbereiten des Anforderungsobjekts, Ausführen des Aufrufs (mit PFEntityHandle von login), Erstellen eines Objekts zum Empfangen der Antwort und aufrufen dann eine GetResult-Funktion , um den neu erstellten Container auszufüllen.

    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<char> getFilesResultBuffer(resultSize);
    PFDataGetFilesResponse* getFilesResponseResult{ nullptr };
    hr = PFDataGetFilesGetResult(&async, getFilesResultBuffer.size(), getFilesResultBuffer.data(), &getFilesResponseResult, nullptr);

Bereinigen

Wenn Ihr Spiel zum Herunterfahren bereit ist oder Sie PlayFab aus einem anderen Grund sauber müssen, stellen Sie sicher, dass Sie alle geöffneten Handles schließen und PFServicesUninitializeAsync aufrufen.

    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

Asynchrones API-Muster

Das PlayFab Services SDK für das GDK folgt dem im GDK implementierten asynchronen Programmiermodell . Dieses Programmiermodell umfasst die Verwendung von Aufgaben und Aufgabenwarteschlangen, die von der XAsync-Bibliothek bereitgestellt werden. Dieses Modell ist konsistent mit anderen GDK-Funktionen und -Erweiterungen (z. B. der Xbox Services-API). Dies führt zwar zu einer gewissen Komplexität, bietet aber auch ein hohes Maß an Kontrolle über asynchrone Vorgänge.

In diesem Beispiel wird gezeigt, wie Sie pfDataGetFilesAsync asynchron aufrufen.

    auto async = std::make_unique<XAsyncBlock>();
    async->callback = [](XAsyncBlock* async)
    {
        std::unique_ptr<XAsyncBlock> asyncBlockPtr{ async }; // take ownership of XAsyncBlock

        size_t resultSize;
        HRESULT hr = PFDataGetFilesGetResultSize(async, &resultSize);
        if (SUCCEEDED(hr))
        {
            std::vector<char> 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
    }

Fehlerbehandlung

Abgeschlossene XAsync-Vorgänge geben HTTP-status-Codes zurück. Ein Fehler status Code manifestiert sich als Fehler-HRESULT, z. B. HTTP_E_STATUS_NOT_FOUND beim Aufrufen von XAsyncGetStatus() oder einer der PF*Get()-APIs.

Ausführliche Fehlermeldungen, die vom Dienst zurückgegeben werden, finden Sie im nächsten Abschnitt zum Debuggen. Diese detaillierten Fehlermeldungen können während der Entwicklung nützlich sein, um besser zu verstehen, wie der PlayFab-Dienst auf Anforderungen vom Client reagiert.

Debuggen

Die einfachste Möglichkeit, die Ergebnisse anzuzeigen und Aufrufe im PlayFab Services SDK zu debuggen, besteht darin, die Debugablaufverfolgung zu aktivieren. Wenn Sie die Debugablaufverfolgung aktivieren, können Sie sowohl die Ergebnisse im Ausgabefenster des Debuggers anzeigen als auch die Ergebnisse in die eigenen Protokolle Ihres Spiels einbinden.

Referenzen

API-Referenzdokumentation