Tutorial zur Ereignispipeline
Dieses Dokument ist ein kurzes Schritt-für-Schritt-Tutorial zur Verwendung des Features "Ereignispipeline" im PlayFab Services SDK.
Schritt 1: Initialisieren des PlayFab Services SDK
Der erste Schritt besteht darin, das PF Service SDK mithilfe der APIs PFServicesInitialize und PFServiceConfigCreateHandle zu initialisieren.
Die PFServiceConfigCreateHandle-API empfängt eine Verbindungszeichenfolge und eine Titel-ID, die von Ihrem Titel im PlayFab Game Manager abgerufen werden kann.
Der dritte Parameter ist eine PFServiceConfigHandle-Struktur , die die konfiguration darstellt, die erstellt wird. Dieses Dienstkonfigurationshandle wird im nächsten Schritt verwendet.
PFServiceConfigHandle serviceConfigHandle;
PFServicesInitialize(nullptr);
PFServiceConfigCreateHandle(
"titleConnectionString",
"titleId",
&serviceConfigHandle
);
Schritt 2: Erstellen einer Telemetrieereignispipeline
Als Nächstes erstellen wir eine Telemetrieereignispipeline mit einem Telemetrieschlüssel mithilfe der PFEventPipelineCreateTelemetryPipelineHandleWithKey-API . Telemetrieschlüssel werden über playFab Game Manager erstellt und verwaltet.
Beim Erstellen der PFEventPipelineTelemetryKeyConfig-Struktur übergeben wir den tatsächlichen Telemetrieschlüssel und das Dienstkonfigurationshandle, das wir während der SDK-Initialisierung erhalten haben.
PFEventPipelineHandle handle;
XTaskQueueHandle taskQueueHandle;
XTaskQueueCreate(XTaskQueueDispatchMode::ThreadPool, XTaskQueueDispatchMode::Manual, &taskQueueHandle);
PFEventPipelineTelemetryKeyConfig telemetryKeyConfig
{
"myTelemetryKey",
serviceConfigHandle,
};
HRESULT hr = PFEventPipelineCreateTelemetryPipelineHandleWithKey(
&telemetryKeyConfig,
taskQueueHandle,
nullptr,
nullptr,
nullptr,
&handle
);
if (FAILED(hr))
{
printf("Failed creating event pipeline: 0x%x\r\n", hr);
return;
}
Schritt 3: Aktualisieren der Pipelinekonfiguration
Aktualisieren wir die Pipelinekonfiguration. In diesem Beispiel möchten wir Batches mit maximal 10 Ereignissen senden (Standardwert: 5).
Da wir außerdem maxWaitTimeInSeconds und pollDelayInMs als NULL-Zeiger senden, verwenden sie den Standardwert für den jeweiligen Pipelinetyp.
Wir geben auch eine Komprimierungsstufe "Mittel" an. Durch das Festlegen dieser Eigenschaft werden die Textnutzlasten komprimiert und die Auslastung von Netzwerkressourcen optimiert.
Anschließend rufen wir PFEventPipelineUpdateConfiguration auf und übergeben das PFEventPipelineHandle , das wir aus dem vorherigen Schritt erhalten haben, und die PFEventPipelineConfig-Struktur .
uint32_t maxEvents = 10;
PFHCCompressionLevel compressionLevel = PFHCCompressionLevel::Medium;
PFEventPipelineConfig eventPipelineConfig
{
&maxEvents, // maxEventsPerBatch
nullptr, // maxWaitTimeInSeconds
nullptr, // pollDelayInMs
&compressionLevel // compressionLevel
};
HRESULT hr = PFEventPipelineUpdateConfiguration(
handle,
eventPipelineConfig
);
if (FAILED(hr))
{
printf("Failed updating event pipeline configuration: 0x%x\r\n", hr);
return;
};
Schritt 4: Ausgeben des Ereignisses
In diesem Schritt wird nur ein Ereignis mit dem Namen "TelemetryKeyEvent" über die PFEventPipelineEmitEvent-API ausgegeben.
Dieses Ereignis ist nicht mit Entitäten verknüpft, da wir bisher keine Entitätsauthentifizierung bereitgestellt haben.
PFEvent myEvent
{
nullptr,
"custom.playfab.events.PlayFab.Test.TelemetryEventPipelineTests",
"TelemetryKeyEvent",
nullptr,
"{}"
};
HRESULT hr = PFEventPipelineEmitEvent(
handle,
&myEvent
);
if (FAILED(hr))
{
printf("Failed emitting event: 0x%x\r\n", hr);
return;
}
Schritt 5: Abrufen der Entität
Hier möchten wir eine Entität abrufen, die wir verwenden können, um mit unseren Ereignissen zu verknüpfen.
Für dieses Tutorial rufen wir die PFAuthenticationReLoginWithXUserAsync-API auf, um eine gültige PFEntityHandle abzurufen.
Notiz
Das userHandle-Objekt, das als Teil der PFAuthenticationLoginWithXUserRequest übergeben wird, ist vom Typ XUserHandle. Die Schritte zum Abrufen eines gültigen XUserHandle liegen außerhalb des Gültigkeitsbereichs dieses Tutorials. Weitere Informationen zu diesem Thema finden Sie in der Dokumentation zu XUserAddAsync .
PFEntityHandle entityHandle;
PFAuthenticationLoginWithXUserRequest request{};
request.createAccount = true;
request.user = userHandle; // An XUserHandle obtained from XUserAddAsync
XAsyncBlock async{};
HRESULT hr = PFAuthenticationReLoginWithXUserAsync(entityHandle, &request, &async);
if (FAILED(hr))
{
printf("Failed PFAuthenticationReLoginWithXUserAsync: 0x%x\r\n", hr);
return;
}
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
if (FAILED(hr))
{
printf("Failed XAsyncGetStatus: 0x%x\r\n", hr);
return;
}
Schritt 6: Hinzufügen einer Entität zur Pipeline
Da wir bereits eine gültige Entität erhalten haben, können wir PFEventPipelineAddUploadingEntity aufrufen und das Ereignispipelinehandle und das Entitätshandle aus dem vorherigen Schritt übergeben. Durch diese Aktion kann die Pipeline zur Verwendung der Entitätsauthentifizierung wechseln.
HRESULT hr = PFEventPipelineAddUploadingEntity(
handle,
entityHandle
);
if (FAILED(hr))
{
printf("Failed adding uploading entity: 0x%x\r\n", hr);
return;
}
Schritt 7: Ausgeben des Ereignisses
Dieses Verfahren ist identisch mit der vorherigen Ereignisübermittlung.
Die einzigen zwei Unterschiede sind:
- Wir markieren dieses Ereignis mit einem anderen Namen ("EntityEvent"), um es deutlicher zu machen.
- Dieses Ereignis wird protokolliert und mit der Entität verknüpft, die wir zuvor abgerufen haben.
PFEvent myEvent
{
nullptr,
"custom.playfab.events.PlayFab.Test.TelemetryEventPipelineTests",
"EntityEvent",
nullptr,
"{}"
};
hr = PFEventPipelineEmitEvent(
handle,
&myEvent
);
if (FAILED(hr))
{
printf("Failed emitting event: 0x%x\r\n", hr);
return;
}
Schritt 8: Schließen des Ereignispipelinehandles
Wenn wir mit dem Hochladen von Ereignissen fertig sind, müssen wir nur PFEventPipelineCloseHandle aufrufen und unser Pipelinehandle übergeben.
PFEventPipelineCloseHandle(handle);