> ## 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，而不需要實體權杖，也不會暴露遊戲祕密金鑰。

遙測金鑰 (Telemetry Keys) 可讓您直接從遊戲用戶端擷取自訂遙測事件，以使用 PlayFab 強大的分析功能。您現在可以使用 [WriteTelemetryEvents API](https://learn.microsoft.com/en-us/rest/api/playfab/events/play-stream-events/write-telemetry-events)，在傳送遙測時簡化用戶端對 PlayFab 的驗證。

遙測金鑰是一種認證，可用來取代呼叫 [PlayFab 實體 API](/zh-TW/services/playfab/live-service-management/game-configuration/entities) 時通常所需的實體權杖。這表示即使沒有玩家登入，您也可以使用 PlayFab 的遙測擷取功能。此外，與遊戲祕密金鑰 (Title Secret Key) 不同，遙測金鑰不會授與管理 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 保留期](/zh-TW/services/playfab/data-analytics/legacy/insights/performance-retention)設定為
  超過 30 天的遊戲，目前無法設定遙測金鑰。

## 為事件指定實體

PlayFab 事件會透過其 `Entity` 屬性指出事件的主體。當您使用實體權杖驗證傳送遙測時，此欄位會自動填入已登入實體的相關資訊。不過，當您使用遙測金鑰時，並沒有已登入的實體。因此，使用遙測金鑰傳送的遙測事件，不允許指定 [PlayFab 內建實體](/zh-TW/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-TW/services/playfab/data-analytics/ingest-data/telemetry-overview.md)
- [刪除遙測金鑰](/zh-TW/services/playfab/data-analytics/ingest-data/ht-telemetry-keys-delete.md)
- [列出遙測金鑰](/zh-TW/services/playfab/api-references/rest/events/play-stream-events/list-telemetry-keys.md)
- [取得遙測金鑰](/zh-TW/services/playfab/api-references/rest/events/play-stream-events/get-telemetry-key.md)
- [建立遙測金鑰](/zh-TW/services/playfab/api-references/rest/events/play-stream-events/create-telemetry-key.md)