本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 範例 3：內容中繼資料
<a name="monetization-functions-examples-contextual-metadata"></a>

本節提供使用 Elemental Inference `GetMetadata`回應時常見模式的JSONata表達式。在`AWS_SERVICE_REQUEST`函數的 `Output`區塊中使用這些項目。

**注意**  
`GetMetadata` 傳回`items`陣列，其中每個項目代表具有IAB分類類別和GARM品牌安全評估的分析鏡頭。當您的查詢時間範圍跨越多個鏡頭時，回應會包含多個項目。以下各節中的表達式會透過彙總所有鏡頭來處理此問題。  
如需完整的 Elemental Inference `GetMetadata`回應結構描述，請參閱 Elemental Inference API 參考。

## 建置查詢時段
<a name="monetization-functions-examples-contextual-metadata-timewindow"></a>

將下列表達式用於`AWS_SERVICE_REQUEST`函數的 `Body` 欄位：

```
{%'{"outputName": "my-contextual-output", "timeSpecification": {"ptsBased": {"startPts": ' & $string(($exists(inference.previousBreakEndPts) and inference.previousBreakEndPts > inference.pts - 30 * inference.timescale ? inference.previousBreakEndPts : inference.pts - 30 * inference.timescale)) & ', "endPts": ' & $string(inference.pts + 1) & ', "timescale": ' & $string(inference.timescale) & '}}, "parameters": {"contextualMetadata": {}}}' %}
```

此表達式會選取較新的 `inference.previousBreakEndPts`和 30 秒回顧，確保查詢時段永遠不會超過 30 秒。如果 `inference.previousBreakEndPts` 無法使用 （例如，第一個廣告休息時間），則表達式預設為 30 秒回顧。

**注意**  
`my-contextual-output` 將 取代為 Elemental Inference 摘要內容中繼資料輸出的名稱。

## 擷取IAB類別 IDs
<a name="monetization-functions-examples-contextual-metadata-iab-ids"></a>

```
{%response.statusCode = 200 ? $join($distinct(response.body.items.metadata.contextualMetadata.iabTaxonomy.categories.uniqueId), ',') : ''%}
```

結果：`"641,645,324"`— IAB Content Taxonomy IDs，適合做為查詢參數傳遞 （例如，`iab_cats=641,645,324`)。

## 擷取IAB類別路徑
<a name="monetization-functions-examples-contextual-metadata-iab-paths"></a>

```
{%response.statusCode = 200 ? $join($distinct(response.body.items.metadata.contextualMetadata.iabTaxonomy.categories.($join(path, ' > '))), '|') : ''%}
```

結果：`"Genres > Animation & Anime|Genres > Family/Children|Entertainment > Movies"`— 人類可讀取的分類路徑。

## 擷取標記的GARM類別
<a name="monetization-functions-examples-contextual-metadata-garm-flagged"></a>

```
{%response.statusCode = 200 ? $join($distinct(response.body.items.metadata.contextualMetadata.garm.suitability.categories[flagged = true].category), ',') : ''%}
```

結果：`"ILLEGAL_DRUGS_TOBACCO_ALCOHOL"`— 要排除廣告目標或向廣告決策伺服器發出品牌安全問題訊號的類別。

## 判斷最高GARM風險層級
<a name="monetization-functions-examples-contextual-metadata-garm-risk"></a>

```
{%response.statusCode = 200 and $exists(response.body.items) ? ($names := ['NONE','LOW','MEDIUM','HIGH']; $flagged := response.body.items.metadata.contextualMetadata.garm.suitability.categories[flagged = true].risk; $scores := $map($flagged, function($r){ $r = 'HIGH' ? 3 : $r = 'MEDIUM' ? 2 : $r = 'LOW' ? 1 : 0 }); $count($scores) > 0 ? $names[$max($scores)] : 'NONE') : ''%}
```

結果：`"MEDIUM"`— 所有分析鏡頭和GARM類別的最壞情況風險等級。如果請求失敗或回應內文遺失，則傳回空字串，以便不會將遺失的資料報告為 `NONE`。

## 檢查品牌安全
<a name="monetization-functions-examples-contextual-metadata-brand-safe"></a>

```
{%response.statusCode = 200 and $exists(response.body.items) ? $string($not($exists(response.body.items.metadata.contextualMetadata.garm.suitability.categories[flagged = true]))) : ''%}
```

結果：`"false"`如果標記任何GARM類別，`"true"`如果內容是品牌安全。如果請求失敗或回應內文遺失，則傳回空字串。

**重要**  
需要 `$exists(response.body.items)` 防護。回應可以傳回狀態碼 200，而 `response.body`是 `null` — 例如，當內文超過 20，000 個字元或不是有效的 JSON 時。如果沒有保護，即使從未收到GARM分類，表達式仍會傳回`"true"`並將內容報告為品牌安全。

## 合併內容訊號
<a name="monetization-functions-examples-contextual-metadata-combined"></a>

```
{%response.statusCode = 200 ? $string({'categories': $distinct(response.body.items.metadata.contextualMetadata.iabTaxonomy.categories.($join(path, ' > '))), 'category_ids': $distinct(response.body.items.metadata.contextualMetadata.iabTaxonomy.categories.uniqueId), 'garm_flagged': $distinct(response.body.items.metadata.contextualMetadata.garm.suitability.categories[flagged = true].category)}) : ''%}
```

結果：將所有內容訊號組合成單一結構化承載的 JSON 字串。

## 每次拍攝詳細資訊
<a name="monetization-functions-examples-contextual-metadata-per-shot"></a>

```
{%response.statusCode = 200 ? $string(response.body.items.{'pts': pts, 'categories': metadata.contextualMetadata.iabTaxonomy.categories.($join(path, ' > ')), 'garm_flagged': metadata.contextualMetadata.garm.suitability.categories[flagged = true].category}) : ''%}
```

結果：每個鏡頭物件的陣列會保留 PTS 觸發哪些分類的內容。當您的廣告決策邏輯需要時間精細程度時使用 。

## 使用秘訣與最佳實務
<a name="monetization-functions-examples-contextual-metadata-tips"></a>

在建置元素推論回應的輸出表達式時，請使用下列秘訣。
+ 處理內文`response.statusCode`之前，請務必檢查 。如果呼叫失敗，則 `response.body`為 `null`。
+ 使用 `$distinct()`跨多個鏡頭刪除重複類別。
+ Elemental Inference 會傳回每個鏡頭的多個IAB類別和一組GARM品牌安全類別。如需目前的限制，請參閱元素推論文件。
+ 當時間範圍跨越多個鏡頭時，回應會在`items`陣列中包含多個項目。
+ 回應大小上限為 20，000 個字元。如果您收到截斷的回應，請縮短時間範圍。
+ 使用 中的其他函數鏈結時`SEQUENTIAL_EXECUTOR`，以及將值直接傳遞至廣告決策伺服器 URL `player_params.*`時，請使用`temp.*`輸出金鑰。
+ 如需支援JSONata函數和運算子的完整清單，請參閱 [JSONata 函數的表達式參考](monetization-functions-jsonata.md)。

如需包含先決條件和資源政策的完整設定指南，請參閱 [Elemental Inference 整合](monetization-functions-elemental-inference-integration.md)。如需函數類型參考，請參閱 [AWS 服務請求](monetization-functions-types-aws-service-request.md)。