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

# イベントパイプラインチュートリアル

> PlayFab Services SDK のイベントパイプラインを作成するためのステップバイステップチュートリアル: 初期化、テレメトリキー認証、イベントの発行、エンティティの紐付け、クローズ。

このドキュメントは、PlayFab Services SDK のイベントパイプライン機能の使用方法に関する簡単なステップバイステップチュートリアルです。

## ステップ 1 - PlayFab Services SDK を初期化する

最初のステップは、[**PFServicesInitialize**](/services/playfab/api-references/c/pfservices/functions/pfservicesinitialize) API と [**PFServiceConfigCreateHandle**](/services/playfab/api-references/c/pfserviceconfig/functions/pfserviceconfigcreatehandle) API を使用して PF Service SDK を初期化することです。

**PFServiceConfigCreateHandle** API は、PlayFab Game Manager 上のタイトルから取得できる接続文字列とタイトル ID を受け取ります。

3 番目のパラメーターは、作成される構成を表す **PFServiceConfigHandle** 構造体です。このサービス構成ハンドルは次のステップで使用されます。

```cpp theme={null}
PFServiceConfigHandle serviceConfigHandle;

PFServicesInitialize(nullptr);

PFServiceConfigCreateHandle(
    "titleConnectionString",
    "titleId",
    &serviceConfigHandle
);
```

## ステップ 2 - テレメトリイベントパイプラインを作成する

次に、[**PFEventPipelineCreateTelemetryPipelineHandleWithKey**](/services/playfab/api-references/c/pfeventpipeline/functions/pfeventpipelinecreatetelemetrypipelinehandlewithkey) API を使用して、テレメトリキー付きのテレメトリイベントパイプラインを作成しましょう。テレメトリキーは、PlayFab Game Manager を通じて作成および管理されます。

PFEventPipelineTelemetryKeyConfig 構造体を作成する際、実際のテレメトリキーと、SDK 初期化中に取得したサービス構成ハンドルを渡します。

```cpp theme={null}
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;
}
```

## ステップ 3 - パイプライン構成を更新する

パイプライン構成を更新しましょう。この例では、最大 10 イベントのバッチを送信したいと考えています (デフォルトは 5)。

また、maxWaitTimeInSeconds と pollDelayInMs を null ポインターとして送信しているため、それぞれのパイプラインタイプのデフォルト値が使用されます。

さらに、"Medium" 圧縮レベルを指定しています。このプロパティを設定すると、本文ペイロードが圧縮され、ネットワークリソースの利用を最適化するのに役立ちます。

その後、前のステップで取得した **PFEventPipelineHandle** と **PFEventPipelineConfig** 構造体を渡して、[**PFEventPipelineUpdateConfiguration**](/services/playfab/api-references/c/pfeventpipeline/functions/pfeventpipelineupdateconfiguration) を呼び出します。

```cpp theme={null}
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;
};
```

## ステップ 4 - イベントを発行する

このステップでは、[**PFEventPipelineEmitEvent**](/services/playfab/api-references/c/pfeventpipeline/functions/pfeventpipelineemitevent) API を通じて "TelemetryKeyEvent" という名前の 1 つのイベントのみを発行します。

これまでにエンティティ認証を提供していないため、このイベントはどのエンティティにも紐付けられていません。

```cpp theme={null}
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;
}
```

## ステップ 5 - エンティティを取得する

ここでは、イベントとの紐付けを開始するために使用できるエンティティを取得したいと考えています。

このチュートリアルでは、有効な **PFEntityHandle** を取得するために [**PFAuthenticationReLoginWithXUserAsync**](/services/playfab/api-references/c/pfauthentication/functions/pfauthenticationreloginwithxuserasync) API を呼び出します。

<Note>
  **PFAuthenticationLoginWithXUserRequest** の一部として渡される userHandle オブジェクトは XUserHandle 型です。有効な XUserHandle を取得する方法についてはこのチュートリアルの範囲外です。このトピックの詳細については、[XUserAddAsync](/reference/system/xuser/functions/xuseraddasync) のドキュメントを参照してください。
</Note>

```cpp theme={null}
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;
}
```

## ステップ 6 - エンティティをパイプラインに追加する

すでに有効なエンティティを取得しているため、[**PFEventPipelineAddUploadingEntity**](/services/playfab/api-references/c/pfeventpipeline/functions/pfeventpipelineadduploadingentity) を呼び出し、イベントパイプラインハンドルと前のステップのエンティティハンドルを渡すことができます。このアクションにより、パイプラインはエンティティ認証を使用するように切り替わります。

```cpp theme={null}
HRESULT hr = PFEventPipelineAddUploadingEntity(
    handle,
    entityHandle
);

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

## ステップ 7 - イベントを発行する

この手順は前のイベント送信と同じです。

異なる点は次の 2 つのみです:

* このイベントには、より明確にするために異なる名前 ("EntityEvent") をタグ付けしています。
* このイベントはログに記録され、以前に取得したエンティティに紐付けられます。

```cpp theme={null}
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;
}
```

## ステップ 8 - イベントパイプラインハンドルを閉じる

最後に、イベントのアップロードが完了したら、パイプラインハンドルを渡して [**PFEventPipelineCloseHandle**](/services/playfab/api-references/c/pfeventpipeline/functions/pfeventpipelineclosehandle) を呼び出すだけです。

```cpp theme={null}
PFEventPipelineCloseHandle(handle);
```

## 関連項目

* [イベントパイプラインの概要](/services/playfab/sdks/c/event-pipeline/eventpipeline)


## Related topics

- [PlayFab Services SDK - イベントパイプライン](/ja-jp/services/playfab/sdks/c/event-pipeline/eventpipeline.md)
- [PlayFab と Microsoft Fabric リアルタイム分析チュートリアル](/ja-jp/services/playfab/data-analytics/learn-data/reports/real-time-analytics-tutorial.md)
- [リアルタイム分析の中核概念](/ja-jp/services/playfab/data-analytics/ingest-data/real-time-analytics-core-concepts.md)
- [ソース コードとベスト プラクティス - Winter Starfall](/ja-jp/services/playfab/demo-game/source-code-and-best-practices.md)
- [アクションとルールのクイックスタート](/ja-jp/services/playfab/data-analytics/acting-data/action-rules-quickstart.md)