> ## 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 遥测密钥作为轻量级凭据，从你的游戏客户端调用 WriteTelemetryEvents，而无需暴露实体令牌（Entity Token）或标题密钥（Title Secret）。

遥测密钥（Telemetry Keys）使你能够通过直接从游戏客户端引入自定义遥测事件来使用 PlayFab 强大的分析功能。你现在可以使用 [WriteTelemetryEvents API](https://learn.microsoft.com/en-us/rest/api/playfab/events/play-stream-events/write-telemetry-events) 来简化客户端在发送遥测数据时对 PlayFab 的身份验证过程。

遥测密钥是一种凭据，可用于替代调用 [PlayFab 实体 API](/services/playfab/live-service-management/game-configuration/entities) 通常所需的实体令牌。这意味着即使没有玩家登录，你也可以利用 PlayFab 的遥测引入功能。此外，与标题密钥（Title Secret）不同，遥测密钥不授予对管理 API 的访问权限；它们只能用于发送遥测数据。你可以放心地将遥测密钥直接分享给你的游戏客户端。

## 使用遥测密钥

你可以在 GameManager 中 `Data` 部分下的 `Telemetry Keys` 选项卡管理为标题配置的密钥。

创建密钥后，你可以在从游戏客户端调用 [WriteTelemetryEvents](https://learn.microsoft.com/en-us/rest/api/playfab/events/play-stream-events/write-telemetry-events) 时使用它，通过 HTTP 请求头 `X-TelemetryKey` 传入：

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

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

<Note>
  *调用方应提供遥测密钥或实体令牌其中之一。如果两者都提供，则遥测密钥将被忽略，请求将被视为未提供遥测密钥进行处理。*
</Note>

## 限制

使用遥测密钥时适用以下限制：

* 每个标题最多可以配置五个遥测密钥。
* 遥测密钥只能用于通过 [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 保留期](/services/playfab/data-analytics/legacy/insights/performance-retention)设置为大于 30 天的标题目前无法配置遥测密钥。

## 为事件指定实体

PlayFab 事件通过其 `Entity` 属性指明事件的主体。当你使用实体令牌身份验证发送遥测数据时，此字段会自动填充有关已登录实体的信息。但是，当你使用遥测密钥时，没有实体处于登录状态。因此，使用遥测密钥发送的遥测事件不允许将 [PlayFab 内置实体](/services/playfab/live-service-management/game-configuration/entities/available-built-in-entity-types)指定为其主体。

在使用遥测密钥时，你可能仍希望将遥测事件与某个主体（例如游戏中使用的自定义玩家标识符）关联起来。为此，你可以在客户端构造事件时指定一个*外部*实体。

外部实体只是你将 `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` 属性将包含用于引入该事件的密钥名称。如果你配置了多个遥测密钥，可以使用此属性查看事件是通过哪个密钥引入的。*
</Note>


## Related topics

- [遥测](/zh-CN/services/playfab/data-analytics/ingest-data/telemetry-overview.md)
- [删除遥测密钥](/zh-CN/services/playfab/data-analytics/ingest-data/ht-telemetry-keys-delete.md)
- [遥测密钥快速入门](/zh-CN/services/playfab/data-analytics/ingest-data/telemetry-keys-qs.md)
- [激活或停用遥测密钥](/zh-CN/services/playfab/data-analytics/ingest-data/ht-activate-deactivate-telemetry-keys.md)
- [PlayFab Services SDK - 事件管道](/zh-CN/services/playfab/sdks/c/event-pipeline/eventpipeline.md)