View a markdown version of this page

範例 3：內容中繼資料 - AWS Elemental MediaTailor
建置查詢時段擷取IAB類別 IDs擷取IAB類別路徑擷取標記的GARM類別判斷最高GARM風險層級檢查品牌安全合併內容訊號每次拍攝詳細資訊使用秘訣與最佳實務

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

範例 3：內容中繼資料

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

注意

GetMetadata 傳回items陣列，其中每個項目代表具有IAB分類類別和GARM品牌安全評估的分析鏡頭。當您的查詢時間範圍跨越多個鏡頭時，回應會包含多個項目。以下各節中的表達式會透過彙總所有鏡頭來處理此問題。

如需完整的 Elemental Inference GetMetadata回應結構描述，請參閱 Elemental Inference API 參考。

建置查詢時段

將下列表達式用於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

{%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類別路徑

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

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

擷取標記的GARM類別

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

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

判斷最高GARM風險層級

{%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。

檢查品牌安全

{%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"並將內容報告為品牌安全。

合併內容訊號

{%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 字串。

每次拍攝詳細資訊

{%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 觸發哪些分類的內容。當您的廣告決策邏輯需要時間精細程度時使用 。

使用秘訣與最佳實務

在建置元素推論回應的輸出表達式時，請使用下列秘訣。

  • 處理內文response.statusCode之前，請務必檢查 。如果呼叫失敗，則 response.body為 null。

  • 使用 $distinct()跨多個鏡頭刪除重複類別。

  • Elemental Inference 會傳回每個鏡頭的多個IAB類別和一組GARM品牌安全類別。如需目前的限制，請參閱元素推論文件。

  • 當時間範圍跨越多個鏡頭時，回應會在items陣列中包含多個項目。

  • 回應大小上限為 20，000 個字元。如果您收到截斷的回應，請縮短時間範圍。

  • 使用 中的其他函數鏈結時SEQUENTIAL_EXECUTOR，以及將值直接傳遞至廣告決策伺服器 URL player_params.*時，請使用temp.*輸出金鑰。

  • 如需支援JSONata函數和運算子的完整清單，請參閱 JSONata 函數的表達式參考。

如需包含先決條件和資源政策的完整設定指南，請參閱 Elemental Inference 整合。如需函數類型參考，請參閱 AWS 服務請求。