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

# Telemetry Key

> Entity Token や Title Secret を公開せずに、PlayFab Telemetry Key を軽量な認証情報として使用してゲーム クライアントから WriteTelemetryEvents を呼び出します。

Telemetry Keys を使用すると、ゲーム クライアントから直接カスタム テレメトリ イベントを取り込むことで、PlayFab の強力な分析機能を利用できます。[WriteTelemetryEvents API](https://learn.microsoft.com/en-us/rest/api/playfab/events/play-stream-events/write-telemetry-events) を使用して、テレメトリを送信するときに PlayFab に対するクライアントの認証を簡素化できるようになりました。

Telemetry Key は、[PlayFab エンティティ API](/services/playfab/live-service-management/game-configuration/entities) を呼び出すために通常必要な Entity Token の代わりに使用できる認証情報です。これは、プレイヤーがサインインしていない場合でも PlayFab のテレメトリ取り込み機能を利用できることを意味します。さらに、Title Secret Key とは異なり、Telemetry Key は管理 API へのアクセスを許可しません。テレメトリを送信するためにのみ使用できます。Telemetry Key はゲーム クライアントと安全に直接共有できます。

## Telemetry Key の使用

Game Manager の `Data` セクションの下にある `Telemetry Keys` タブから、タイトルに構成されているキーを管理できます。

キーを作成したら、HTTP ヘッダー `X-TelemetryKey` を介して含めることで、[WriteTelemetryEvents](https://learn.microsoft.com/en-us/rest/api/playfab/events/play-stream-events/write-telemetry-events) を呼び出すときにゲーム クライアントから使用できます:

```HTTP theme={null}
POST https://<titleId>.playfabapi.com/Event/WriteTelemetryEvents
X-TelemetryKey: <Your Telemetry Key>

{
  "Events": [
    <Your Events>
  ]
}
```

<Note>
  *呼び出し元は Telemetry Key または Entity Token のいずれかを提供する必要があります。両方が提供された場合、Telemetry Key は無視され、リクエストは提供されていないかのように処理されます。*
</Note>

## 制限事項

Telemetry Key を使用する際に、次の制限が適用されます:

* タイトルは最大 5 つの Telemetry Key を構成できます。
* Telemetry Key は、[WriteTelemetryEvents API](https://learn.microsoft.com/en-us/rest/api/playfab/events/play-stream-events/write-telemetry-events) を介してテレメトリ イベントを送信するためだけに使用できます。[WriteEvents API](https://learn.microsoft.com/en-us/rest/api/playfab/events/play-stream-events/write-events) を介して PlayStream イベントを送信するためには使用できません。
* [Insights Retention](/services/playfab/data-analytics/legacy/insights/performance-retention) を 30 日を超えて設定しているタイトルは、現時点では Telemetry Key を構成できません。

## イベントのエンティティの指定

PlayFab イベントは、`Entity` プロパティを介してイベントのサブジェクトを示します。Entity Token 認証を使用してテレメトリを送信するとき、このフィールドはサインインしているエンティティに関する情報で自動的に入力されます。ただし、Telemetry Key を使用すると、サインインしているエンティティはありません。したがって、Telemetry Key を使用して送信されるテレメトリ イベントでは、[PlayFab の組み込みエンティティ](/services/playfab/live-service-management/game-configuration/entities/available-built-in-entity-types) をサブジェクトとして指定することは許可されていません。

Telemetry Key を使用するときでも、テレメトリ イベントを何らかのサブジェクト (たとえば、ゲームで使用されるカスタム プレイヤー識別子) に関連付けたい場合があります。それを行うには、クライアントでイベントを形成するときに *外部* エンティティを指定できます。

外部エンティティは、単に `type` を `external` に設定して指定するエンティティです。これらは PlayFab のエンティティ システムの正式な部分ではありません。この文脈では、テレメトリ イベントをシステムで意味のあるサブジェクト識別子に関連付けるための便利なメカニズムを提供するためだけに使用されます。

コードでイベントを形成するときに外部エンティティをサブジェクトとして指定するには、次のようにする必要があります:

1. イベントの `Entity.type` フィールドを `external` (大文字と小文字の区別あり) に設定します。
2. イベントの `Entity.id` フィールドをカスタム サブジェクト識別子に設定します (最大 64 文字)。

以下は、外部エンティティを指定するイベントを送信する方法を示す例です:

```HTTP theme={null}
POST https://<titleId>.playfabapi.com/Event/WriteTelemetryEvents
X-TelemetryKey: <Your Telemetry Key>

{
  "Events": [
    {
      "EventNamespace": "custom.MyCustomEventNS",
      "Name": "MyCustomEvent",
      "Entity": {
        "type": "external",
        "id": "<CUSTOM_ID>"
      },
      "Payload": {
         "MyCustomPayloadField": "MyCustomValue",
         "MyCustomScoreValue": 12345
      }
    }
  ]
}
```

イベントが PlayFab によって取り込まれると、次のようになります:

```JSON theme={null}
"EventData": { 
    "SchemaVersion": "2.0.1", 
    "Id": "9bb3a96d0faa4e2d9f74b6c166a44676", 
    "Timestamp": "2022-09-27T19:42:21.7427679Z", 
    "FullName": { 
        "Namespace": "custom.MyCustomEventNS", 
        "Name": "MyCustomEvent" 
    }, 
    "Entity": { 
        "Type": "external",
        "Id": "<CUSTOM_ID>"
    }, 
    "EntityLineage": { 
        "namespace": "B85A7CFE2803D5A2",
        "title": "A5F3",
        "externalId": "<CUSTOM_ID>"
    }, 
    "OriginInfo": { 
        "Timestamp": "2022-09-27T19:42:21.1560000Z",
        "Key": "<NAME_OF_YOUR_TELEMETRY_KEY>"
    }, 
    "PayloadContentType": "Json", 
    "Payload": { 
        "MyCustomPayloadField": "MyCustomValue",
        "MyCustomScoreValue": 12345
    } 
} 
```

<Note>
  *イベントの `OriginInfo.Key` プロパティには、イベントの取り込みに使用されたキーの名前が含まれます。複数の Telemetry Key を構成している場合、このプロパティを使用してイベントの取り込みに使用されたキーを確認できます。*
</Note>


## Related topics

- [Telemetry Key を削除する](/ja-jp/services/playfab/data-analytics/ingest-data/ht-telemetry-keys-delete.md)
- [PFEventPipelineTelemetryKeyConfig](/ja-jp/services/playfab/api-references/c/pfeventpipeline/structs/pfeventpipelinetelemetrykeyconfig.md)
- [Telemetry Key クイックスタート](/ja-jp/services/playfab/data-analytics/ingest-data/telemetry-keys-qs.md)
- [PFEventPipelineCreateTelemetryPipelineHandleWithKey](/ja-jp/services/playfab/api-references/c/pfeventpipeline/functions/pfeventpipelinecreatetelemetrypipelinehandlewithkey.md)
- [Telemetry Key を有効化または無効化する](/ja-jp/services/playfab/data-analytics/ingest-data/ht-activate-deactivate-telemetry-keys.md)