Ereignispipeline

Die Ereignispipeline ist ein Feature, das Teil des PlayFab Services SDK ist, und der Standard Zweck besteht darin, Spieleentwicklern das Senden von Ereignissen zu ermöglichen, die in PlayFab Insights gespeichert werden sollen. Damit kann der Entwickler die Batchgröße, die Sendehäufigkeit und andere Aspekte einer geeigneten Telemetrielösung angeben.

Es hilft, diese Belastung für den Spieleentwickler zu erleichtern und all diese Aspekte in ihrem Namen zu behandeln. Es gibt Unterstützung für konfigurierbare Ereignispipelines. Ein Titel kann eine oder mehrere dieser Pipelines enthalten, und jede kann mit eigenen Eigenschaften konfiguriert werden.

Sehen wir uns einige der grundlegenden Konzepte der Pipeline an.

Pipelinetypen

Der Pipelinetyp steht in direktem Zusammenhang mit dem Typ der Ereignisse, die eine Pipeline ausgibt. Es gibt zwei verschiedene Arten von Pipelines, die ein Entwickler instanziieren kann:

• Telemetrieereignispipeline: Kann nur Telemetrieereignisse ausgeben und verwendet die REST-API für Schreibtelemetrieereignisse .

• PlayStream-Ereignispipeline: Kann nur PlayStream-Ereignisse ausgeben und verwendet die REST-API für Schreibereignisse .

Sie können mehrere Pipelines mit unterschiedlichen Typen und Konfigurationen verwenden, aber es ist erwähnenswert, dass der Pipelinetyp nach der Erstellung nicht geändert werden kann . Eine Pipeline-Neuanstellung wäre erforderlich.

Authentifizierungstypen

Ein weiterer wichtiger Bestandteil der Pipelineerstellung ist der Authentifizierungstyp. Es gibt zwei unterstützte Authentifizierungsmechanismen für PlayFab-Ereignisse: Entitätsauthentifizierung und Telemetrieschlüsselauthentifizierung.

Die Entitätsauthentifizierung wird verwendet, wenn der Spieleentwickler seine Ereignisse mit einer bestimmten Entität zur weiteren Aggregation oder Analyse verknüpfen möchte. Beispielsweise könnte der Spieleentwickler Ereignisse im Zusammenhang mit den Aktionen des Spielers protokollieren, um eine weitere Verhaltensanalyse Ihrer Titelspieler durchzuführen, die eine Segmentierung ermöglichen.

Die Telemetrieschlüsselauthentifizierung wird verwendet, wenn der Spieleentwickler Ereignisse protokollieren möchte, die nicht unbedingt mit einer Entität verknüpft werden müssen. Beispielsweise kann der Titel vor einem angemeldeten Player damit beginnen, Ereignisse im Zusammenhang mit der Leistung oder bestimmten Metriken zu senden, die zur weiteren Analyse gesammelt werden sollen. Dies kann erfolgen, ohne den regulären Authentifizierungsprozess für Entitäten durchlaufen zu müssen.

Unterstützte Kombinationen aus Authentifizierungstyp und Ereignistyp

	Entitätsauthentifizierung	Telemetrieschlüsselauthentifizierung
Telemetrieereignisse	Gültig	Gültig
PlayStream-Ereignisse	Gültig	Ungültig

Entitätsauthentifizierung

Dieser Authentifizierungstyp ist die normale und am häufigsten verwendete PlayFab-Authentifizierungsmethode. Es ist eng mit einer bestimmten Entität verknüpft und erfordert, dass Sie die entsprechenden PlayFab-Anmelde-APIs aufrufen, um ein Entitätstoken für nachfolgende Aufrufe zu erhalten. Die folgende Liste stellt die verschiedenen Typen von Entitäten dar, die mit der Entitätsauthentifizierung verwendet werden können.

• namespace: Die Namespaceentität bezieht sich auf alle globalen Informationen für alle Titel in Ihrem Studio.
• title: Die Title-Entität bezieht sich auf alle globalen Informationen für diesen Titel.
• master_player_account: Die master_player_account ist eine Spielerentität, die von allen Titeln in Ihrem Studio gemeinsam genutzt wird.
• title_player_account: Für die meisten Entwickler repräsentiert title_player_account den Spieler auf die traditionellste Weise.
• character: Die Zeichenentität ist eine untergeordnete Entität von title_player_account.
• group: Die Gruppenentität ist ein Container für andere Entitäten. Es ist derzeit auf Spieler und Charaktere beschränkt.

Weitere Informationen zu den verschiedenen Entitätstypen finden Sie unter Integrierte Entitätstypen.

Außerdem kann die Pipelineentität nach der Erstellung der Pipeline aktualisiert werden, indem eine gültige PFEntityHandle-Instanz bereitgestellt wird. Der Spieleentwickler kann also eine Entität hinzufügen, um damit zu beginnen, seine Ereignisse mit ihr zu verknüpfen (siehe Abschnitt Wechseln zur Entitätsauthentifizierung oder Aktualisieren der Entität), oder sie sogar entfernen, um Dinge zu protokollieren, die nicht mit einer Entität zusammenhängen (siehe Wechseln zur Telemetrieschlüsselauthentifizierung).

Wenn eine Entität in der Pipeline vorhanden ist, hat sie immer Vorrang vor der Authentifizierung des Telemetrieschlüssels.

Telemetrieschlüsselauthentifizierung

Die Telemetrieschlüsselauthentifizierung erfordert kein Entitätstoken, daher ist es nicht an eine bestimmte Entität gebunden.

Wenn die Telemetrieschlüsselauthentifizierung verwendet wird, ist während der Pipelineerstellung eine PFEventPipelineTelemetryKeyConfig-Struktur erforderlich. Es gibt zwei Standard Teile dieser Struktur:

1. Ein Telemetrieschlüssel, der aus einer Zeichenfolge besteht, die über playFab Game Manager erstellt und verwaltet wird.

2. Eine PFServiceConfigHandle , die das SDK informiert, welche Dienstkonfiguration zum Hochladen der Ereignisse verwendet werden sollte. Das Dienstkonfigurationshandle wird während der SDK-Initialisierung durch Aufrufen von PFServiceConfigCreateHandle erstellt.

Wenn der Entwickler einen Telemetrieschlüssel verwenden möchte, ist es wichtig, ihn bei der Pipelineerstellung bereitzustellen, da es keine Möglichkeit gibt, einen Telemetrieschlüssel hinzuzufügen, nachdem die Pipeline instanziiert wurde.

Es ist erwähnenswert, dass die Telemetrieschlüsselauthentifizierung nur für Telemetrieereignisse verfügbar ist. PlayStream-Ereignisse werden nicht unterstützt.

Konfiguration der Ereignispipeline

Wie bereits erwähnt, verfügt die Ereignispipeline über einige konfigurierbare Eigenschaften, die nach der Pipelineerstellung über den STRUKTURparameter PFEventPipelineConfig bereitgestellt werden können.

Die konfigurierbaren Eigenschaften sind:

• maxEventsPerBatch: Die maximale Anzahl von Ereignissen, die vor dem Schreiben in PlayFab im Batch verarbeitet werden.
• maxWaitTimeInSeconds: Die maximale Zeit, die die Pipeline wartet, bevor ein unvollständiger Batch gesendet wird.
• pollDelayInMs: Gibt an, wie lange die Pipeline wartet, um nach dem Leeren erneut aus dem Ereignispuffer zu lesen.
• compressionLevel: Definiert die Komprimierungsebene, die für den Komprimierungsalgorithmus verwendet wird. Weitere Informationen zur Komprimierung finden Sie unter GZIP-Komprimierung.
• retryOnDisconnect: Die Ereignispipeline versucht erneut, Ereignisse zu senden, die aufgrund eines Verbindungsausfalls fehlgeschlagen sind. Nur für Telemetrieereignispipeline verfügbar.
• bufferSize: Der Grenzwert für die Anzahl der Ereignisse im Puffer der Pipeline.

Wenn pfEventPipelineConfig nur einige Eigenschaften angegeben hat, werden die leeren Eigenschaften überschrieben und verwenden die Standardwerte.

Ein Beispiel dafür, wie eine dieser Eigenschaften für die Ereignispipeline aktualisiert werden kann, finden Sie unter Aktualisieren der Pipelinekonfiguration.

GZIP-Komprimierung

Die Ereignispipeline bietet eine Option zum Komprimieren von Textnutzlasten mit dem GZIP-Komprimierungsstandard.

Der gewünschte Komprimierungsgrad kann innerhalb der PFEventPipelineConfig-Struktur angegeben werden, die Teil der PFEventPipelineUpdateConfiguration-API-Parameter ist.

Eine niedrigere Komprimierungsstufe erreicht weniger Komprimierung, hat jedoch die höchste Geschwindigkeit und ein höherer Komprimierungsgrad erzielt bessere Komprimierungsraten, hat jedoch die langsamste Komprimierungsgeschwindigkeit. Der Unterschied bei den Komprimierungsraten hängt vom Typ der gesendeten Daten ab. Je nach Größe und Zufall der Daten können die Komprimierungsraten auch auf verschiedenen Ebenen gleich sein.

Kompromisse:

Die Verwendung der Komprimierung erhöht die CPU-Zeit aufgrund der zusätzlichen Komplexität der Ausführung eines Komprimierungsalgorithmus, aber auf der anderen Seite verringert sich die Nutzlast des Netzwerktexts erheblich. Abhängig von den Anforderungen und Ressourcen des Spiels ist es also die Obkomprimierung soll, liegt beim Entwickler des Spiels.

Basierend auf der internen Überprüfung gibt es einen durchschnittlichen Anstieg der CPU-Zeit um 20 % und einen durchschnittlichen Rückgang von 91 % bei der Nutzlastkörpergröße. Diese Prozentsätze können je nach Nutzlastgröße und Komplexität der komprimierten Daten weitgehend variieren.

Ereignishandler

Im Rahmen der Pipelineerstellung können Spieleentwickler zwei optionale Ereignishandler bereitstellen, die beim Hochladen von Ereignissen aufgerufen werden.

Wenn der Spieleentwickler jedoch eine "Feuer und Vergessen"-Erfahrung wünscht, kann die Bereitstellung der Ereignishandler weglassen.

Die Ereignishandler, die bereitgestellt werden können, sind wie folgt:

• PFEventPipelineBatchUploadSucceededEventHandler: Wie der Name schon sagt, empfängt er alle Ereignisse, die erfolgreich in PlayFab hochgeladen wurden.

• PFEventPipelineBatchUploadFailedEventHandler: Es empfängt alle fehlgeschlagenen Ereignisse, nachdem die Wiederholungslogik der Pipeline durchlaufen wurde.

Beispiele für die Pipelineerstellung

Im Folgenden finden Sie verschiedene Beispiele zum Instanziieren einer Ereignispipeline basierend auf den zuvor erläuterten Themen.

1. Erstellen einer Telemetrieereignispipeline mit Entitätsauthentifizierung

   Wenn der Entwickler Telemetrieereignisse senden möchte und keine Telemetrieschlüsselauthentifizierung verwenden muss, dient die PFEventPipelineCreateTelemetryPipelineHandleWithEntity-API für diesen Zweck, wie im nächsten Beispiel gezeigt:

   void EventPipelineCreation(PFEntityHandle entityHandle, XTaskQueueHandle taskQueueHandle)
   {
       PFEventPipelineHandle handle;
   
       HRESULT hr = PFEventPipelineCreateTelemetryPipelineHandleWithEntity(
           entityHandle,                       // entityHandle
           taskQueueHandle,                    // queue
           nullptr,                            // eventPipelineBatchUploadedEventHandler
           nullptr,                            // eventPipelineBatchFailedEventHandler
           nullptr,                            // handlerContext
           &handle                             // eventPipelineHandle
       );
   
       if (FAILED(hr))
       {
           printf("Failed creating event pipeline: 0x%x\r\n", hr);
           return;
       }
   }
   

   In diesem Beispiel wird gezeigt, wie Sie eine Telemetrieereignispipeline erstellen, die die Entitätsauthentifizierung verwendet und keine Handler enthält. Dies bedeutet, dass die Pipeline die Ereignisse auslöst und das Ergebnis vergisst.

2. Erstellen der Telemetrieereignispipeline mit Authentifizierung des Telemetrieschlüssels

   Wenn der Entwickler Telemetrieereignisse senden möchte und die Authentifizierung des Telemetrieschlüssels verwenden muss, erfüllt die PFEventPipelineCreateTelemetryPipelineHandleWithKey-API diesen Zweck, wie im nächsten Beispiel gezeigt:

   void EventPipelineCreation(PFServiceConfigHandle serviceConfigHandle, XTaskQueueHandle taskQueueHandle)
   {
       PFEventPipelineHandle handle;
   
       PFEventPipelineTelemetryKeyConfig telemetryKeyConfig
       {
           "myTelemetryKey",                   // telemetryKey
           serviceConfigHandle,                // serviceConfigHandle
       };
   
       HRESULT hr = PFEventPipelineCreateTelemetryPipelineHandleWithKey(
           &telemetryKeyConfig,                // eventPipelineTelemetryKeyConfig
           taskQueueHandle,                    // queue
           nullptr,                            // eventPipelineBatchUploadedEventHandler
           nullptr,                            // eventPipelineBatchFailedEventHandler
           nullptr,                            // handlerContext
           &handle                             // eventPipelineHandle
       );
   
       if (FAILED(hr))
       {
           printf("Failed creating event pipeline: 0x%x\r\n", hr);
           return;
       }
   }
   

   In diesem Beispiel wird gezeigt, wie Sie eine Telemetrieereignispipeline erstellen, die keine Entitätsauthentifizierung verwendet.

   Die Ereignispipeline beginnt mit dem Hochladen von Ereignissen mithilfe des Telemetrieschlüssels mit der Möglichkeit, später eine Entität hinzuzufügen. Weitere Informationen finden Sie unter Wechseln zur Entitätsauthentifizierung oder Aktualisieren einer Entität.

3. Erstellen der PlayStream-Ereignispipeline

   Wenn der Entwickler PlayStream-Ereignisse senden möchte, erfüllt die PFEventPipelineCreatePlayStreamPipelineHandle-API diesen Zweck, wie im nächsten Beispiel gezeigt:

   void EventPipelineCreation(PFEntityHandle entityHandle, XTaskQueueHandle taskQueueHandle)
   {
       PFEventPipelineHandle handle;
   
       HRESULT hr = PFEventPipelineCreatePlayStreamPipelineHandle(
           entityHandle,                       // entityHandle
           taskQueueHandle,                    // queue
           nullptr,                            // eventPipelineBatchUploadedEventHandler
           nullptr,                            // eventPipelineBatchFailedEventHandler
           nullptr,                            // handlerContext
           &handle                             // eventPipelineHandle
       );
   
       if (FAILED(hr))
       {
           printf("Failed creating event pipeline: 0x%x\r\n", hr);
           return;
       }
   }
   

   Dieses Beispiel zeigt, wie eine PlayStream-Ereignispipeline erstellt wird, die die Entitätsauthentifizierung verwendet und keine Handler enthält. Dies bedeutet, dass die Pipeline die Ereignisse auslöst und das Ergebnis vergisst.

4. Ereignispipeline mit Ereignishandlern

   Dieses Beispiel zeigt, wie Ereignishandler für die Pipelineerstellungs-APIs bereitgestellt werden.

   void CALLBACK OnBatchUploadedHandler(void* context, PFUploadedEvent const* const* events, size_t eventsCount)
   {
       // Handle response
   }
   
   void CALLBACK OnBatchUploadFailedHandler(void* context, HRESULT hr, const char* errorMessage, PFEvent const* const* events, size_t eventsCount)
   {
       // Handle response
   }
   
   void EventPipelineCreation(PFEntityHandle entityHandle, XTaskQueueHandle taskQueueHandle)
   {
       PFEventPipelineHandle handle;
   
       HRESULT hr = PFEventPipelineCreateTelemetryPipelineHandleWithEntity(
           entityHandle,                       // entityHandle
           taskQueueHandle,                    // queue
           OnBatchUploadedHandler,             // eventPipelineBatchUploadedEventHandler
           OnBatchUploadFailedHandler,         // eventPipelineBatchFailedEventHandler
           nullptr,                            // handlerContext
           &handle                             // eventPipelineHandle
       );
   
       if (FAILED(hr))
       {
           printf("Failed creating event pipeline: 0x%x\r\n", hr);
           return;
       }
   }
   

Wie im Beispiel gezeigt, werden OnBatchUploadedHandler und OnBatchUploadFailedHandler als zwei verschiedene Rückruffunktionen deklariert, die beim Erstellen der Ereignispipeline übergeben werden. Jedes Ergebnis, das einem Ereignis zugeordnet ist, wird für eine dieser beiden Funktionen zurückgegeben, je nachdem, ob das Ergebnis erfolgreich oder fehlerhaft war. Es liegt am Spielentwickler, wie mit dem Ergebnis umgegangen wird.

Ausgeben von Ereignissen

Das Ausgeben von Ereignissen ist ein einfacher Vorgang, nachdem die Ereignispipeline bereits erstellt wurde. Der Spieleentwickler sollte die PFEventPipelineEmitEvent-API aufrufen, die das vorhandene Ereignispipelinehandle und das zu sendende Ereignis empfängt.

void EmitEvent(PFEventPipelineHandle handle)
{
    PFEvent myEvent
    {
        nullptr,
        "custom.playfab.events.PlayFab.Test.TelemetryEventPipelineTests",
        "TelemetryEvent",
        nullptr,
        "{}"
    };

    HRESULT hr = PFEventPipelineEmitEvent(
        handle,
        &myEvent
    );

    if (FAILED(hr))
    {
        printf("Failed emitting event: 0x%x\r\n", hr);
        return;
    }
}

Beachten Sie, dass bei Verwendung der Telemetry Key-Authentifizierung der einzige gültige Wert für entityType als Teil von PFEntityKey"external" ist. Alle anderen Entitätstypen werden abgelehnt, und Ereignisse werden nicht hochgeladen.

Beispiel für einen gültigen PFEntityKey bei Verwendung der Telemetrieschlüsselauthentifizierung:

void EmitEvent(PFEventPipelineHandle handle)
{
    PFEntityKey pfEntityKey{ "my-unique-ID", "external" };  // Note the "external" value

    PFEvent myEvent
    {
        &pfEntityKey,
        "custom.playfab.events.PlayFab.Test.EventsWithTelemetryKey",
        "TelemetryEvent",
        nullptr,
        "{}"
    };

    HRESULT hr = PFEventPipelineEmitEvent(
        handle,
        &myEvent
    );

    if (FAILED(hr))
    {
        printf("Failed emitting event: 0x%x\r\n", hr);
        return;
    }
}

Wenn die Puffergröße beim Ausgeben eines Ereignisses überschritten wird, tritt ein Fehler des SDK wie folgt auf:

• E_PF_API_CLIENT_REQUEST_RATE_LIMIT_EXCEEDED (0x892354dd)

Stellen Sie sicher, dass Sie eine angemessene Größe eines Puffers für Ihre Anforderungen festlegen.

Wechseln zur Entitätsauthentifizierung oder Aktualisieren der Entität

Wenn eine Pipeline nur mit einer Telemetrieschlüsselkonfiguration erstellt wurde, gibt es eine Möglichkeit, zur Entitätsauthentifizierung zu wechseln, oder wenn Sie Ihre Pipeline aktualisieren möchten, um eine andere Entität zu verwenden.

Mithilfe von PFEventPipelineAddUploadingEntity ist es möglich, eine Entität an eine ausgeführte Pipeline anzufügen, ohne sie erneut initialisieren zu müssen. Es ersetzt auch die vorhandene Entität, falls vorhanden.

Beispiel:

Eine Telemetrieereignispipeline wird mit der Konfiguration des Telemetrieschlüssels zu Beginn der Titelausführung erstellt. Mögliche Gründe dafür sind, dass noch keine Spieleridentität vorhanden ist oder wir einfach nichts im Zusammenhang mit einem Spieler protokollieren möchten.

void EventPipelineCreation(PFServiceConfigHandle serviceConfigHandle, XTaskQueueHandle taskQueueHandle)
{
    PFEventPipelineHandle handle;

    PFEventPipelineTelemetryKeyConfig telemetryKeyConfig
    {
        "myTelemetryKey",                   // telemetryKey
        serviceConfigHandle,                // serviceConfigHandle
    };

    HRESULT hr = PFEventPipelineCreateTelemetryPipelineHandleWithKey(
        &telemetryKeyConfig,                // eventPipelineTelemetryKeyConfig
        taskQueueHandle,                    // queue
        nullptr,                            // eventPipelineBatchUploadedEventHandler
        nullptr,                            // eventPipelineBatchFailedEventHandler
        nullptr,                            // handlerContext
        &handle                             // eventPipelineHandle
    );

    if (FAILED(hr))
    {
        printf("Failed creating event pipeline: 0x%x\r\n", hr);
        return;
    }
}

Dann hat sich ein Spieler angemeldet, oder wir möchten einfach mit dem Senden von Ereignissen beginnen, die an eine bestimmte Entität angefügt sind, damit wir PFEventPipelineAddUploadingEntity mit dem vorhandenen Ereignispipelinehandle und dem gewünschten Entitätshandle wie folgt aufrufen können:

void EventPipelineUpdateEntity(PFEventPipelineHandle handle)
{
    HRESULT hr = PFEventPipelineAddUploadingEntity(
        handle,                 // eventPipelineHandle
        entityHandle            // entityHandle
    );

    if (FAILED(hr))
    {
        printf("Failed adding uploading entity: 0x%x\r\n", hr);
        return;
    }
}

Nach diesem Aufruf beginnt die Pipeline mit der Protokollierung aller nachfolgenden Ereignisse, die mit dieser Entität verknüpft sind.

Wechseln zur Telemetrieschlüsselauthentifizierung

Wenn der Entwickler auf das vorherige Szenario zurück zur Telemetrieauthentifizierung wechseln und die Ereignisprotokollierung von der Entität trennen möchte, kann er PFEventPipelineRemoveUploadingEntity aufrufen und das Ereignispipelinehandle wie folgt übergeben:

void EventPipelineRemoveEntity(PFEventPipelineHandle handle)
{
    HRESULT hr = PFEventPipelineRemoveUploadingEntity(
        handle                  // eventPipelineHandle
    );

    if (FAILED(hr))
    {
        printf("Failed removing uploading entity: 0x%x\r\n", hr);
        return;
    }
}

Dieser Aufruf entfernt die Entität und wechselt effektiv zurück zur Telemetrieschlüsselauthentifizierung für alle nachfolgenden Ereignisse.

Aktualisieren der Pipelinekonfiguration

Pipelines können problemlos mithilfe der PFEventPipelineUpdateConfiguration-API aktualisiert werden, die das vorhandene Ereignispipelinehandle und eine neue Konfigurationsstruktur wie folgt empfängt:

void EventPipelineUpdateConfiguration(PFEventPipelineHandle handle)
{
    uint32_t maxEvents = 10;
    uint32_t maxWaitTime = 5;
    uint32_t pollDelay = 50;
    PFHCCompressionLevel compressionLevel = PFHCCompressionLevel::Medium;
    bool retryOnDisconnect = true;
    size_t bufferSize = 2048;

    PFEventPipelineConfig eventPipelineConfig
    {
        &maxEvents,             // maxEventsPerBatch
        &maxWaitTime,           // maxWaitTimeInSeconds
        &pollDelay,             // pollDelayInMs
        &compressionLevel,      // compressionLevel
        &retryOnDisconnect,     // retryOnDisconnect
        &bufferSize,            // bufferSize
    };

    HRESULT hr = PFEventPipelineUpdateConfiguration(
        handle,                 // eventPipelineHandle
        eventPipelineConfig     // eventPipelineConfig
    );

    if (FAILED(hr))
    {
        printf("Failed updating event pipeline configuration: 0x%x\r\n", hr);
        return;
    };
}

Erinnerung: Alle leeren oder NULL-Eigenschaften überschreiben den vorhandenen Konfigurationswert mit dem Standardwert.

Ungültige/deaktivierte Telemetrieschlüssel

Falls ein Telemetrieschlüssel deaktiviert ist oder ein ungültiger Schlüssel bei der Pipelineerstellung bereitgestellt wird, beginnen alle Ereignispipelines, die mit diesem Telemetrieschlüssel ausgeführt werden, fehler, sobald sie feststellen, dass der Schlüssel ungültig oder deaktiviert ist.

In dem Fall, in dem der Kunde den Schlüssel reaktiviert, erkennt die Pipeline dies nicht und sendet weiterhin Fehler über den Fehlerereignishandler zurück. Es ist erwähnenswert, dass dieses Verhalten sitzungsbasiert ist, d. h., wenn der Titel neu gestartet wird, wird eine neue Pipeline erstellt und kann Ereignisse erneut hochladen.

Weitere Informationen

• Tutorial zur Ereignispipeline