As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

# Exemplo 3: metadados contextuais
<a name="monetization-functions-examples-contextual-metadata"></a>

Esta seção fornece JSONata expressões para padrões comuns ao trabalhar com respostas de inferência `GetMetadata` elementar. Use-os no `Output` bloco de sua `AWS_SERVICE_REQUEST` função.

**nota**  
`GetMetadata`retorna uma `items` matriz em que cada item representa uma foto analisada com categorias de IAB taxonomia e avaliações de segurança GARM da marca. Quando sua janela de tempo de consulta abrange várias capturas, a resposta inclui vários itens. As expressões nas seções a seguir tratam disso agregando todas as capturas.  
Para ver o esquema de `GetMetadata` resposta completo do Elemental Inference, consulte a referência da API Elemental Inference.

## Crie a janela de tempo de consulta
<a name="monetization-functions-examples-contextual-metadata-timewindow"></a>

Use a seguinte expressão para o `Body` campo da sua `AWS_SERVICE_REQUEST` função:

```
{%'{"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": {}}}' %}
```

Essa expressão seleciona o lookback mais recente `inference.previousBreakEndPts` e um de 30 segundos, garantindo que a janela de consulta nunca exceda 30 segundos. Se não `inference.previousBreakEndPts` estiver disponível (por exemplo, o primeiro intervalo de anúncio), a expressão assumirá como padrão o lookback de 30 segundos.

**nota**  
`my-contextual-output`Substitua pelo nome da saída de metadados contextuais do seu feed de inferência elementar.

## Extract IAB IDs de categoria
<a name="monetization-functions-examples-contextual-metadata-iab-ids"></a>

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

Resultado: `"641,645,324"` — IDs exclusivos de taxonomia de IAB conteúdo, adequados para serem passados como um parâmetro de consulta (por exemplo,`iab_cats=641,645,324`).

## Extract IAB caminhos de categoria
<a name="monetization-functions-examples-contextual-metadata-iab-paths"></a>

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

Resultado: `"Genres > Animation & Anime|Genres > Family/Children|Entertainment > Movies"` — caminhos de taxonomia legíveis por humanos.

## Extrato sinalizado GRÃO categories
<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), ',') : ''%}
```

Resultado: `"ILLEGAL_DRUGS_TOBACCO_ALCOHOL"` — categorias a serem excluídas da segmentação de anúncios ou para sinalizar questões de segurança da marca para seu servidor de decisões de anúncios.

## Determine o mais alto GRÃO nível de risco
<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') : ''%}
```

Resultado: `"MEDIUM"` — o pior nível de risco em todas as fotos e GARM categorias analisadas. Retorna uma string vazia se a solicitação falhar ou se o corpo da resposta estiver ausente, para que os dados ausentes não sejam relatados como`NONE`.

## Verifique a segurança da marca
<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]))) : ''%}
```

Resultado: `"false"` se alguma GARM categoria for sinalizada, `"true"` se o conteúdo for seguro para a marca. Retorna uma string vazia se a solicitação falhar ou se o corpo da resposta estiver ausente.

**Importante**  
O `$exists(response.body.items)` guarda é necessário. Uma resposta pode retornar o código de status 200 enquanto `response.body` é `null` — por exemplo, quando o corpo excede 20.000 caracteres ou não é um JSON válido. Sem o guarda, a expressão retorna `"true"` e relata que o conteúdo é seguro para a marca, mesmo que GARM as classificações nunca tenham sido recebidas.

## Sinal contextual combinado
<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)}) : ''%}
```

Resultado: uma string JSON combinando todos os sinais contextuais em uma única carga estruturada.

## Per-shot detalhe
<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}) : ''%}
```

Resultado: matriz de objetos por foto preservando qual conteúdo em que o PTS acionou quais classificações. Use quando sua lógica de decisão de anúncios precisar de granularidade temporal.

## Dicas e práticas recomendadas
<a name="monetization-functions-examples-contextual-metadata-tips"></a>

Use as dicas a seguir ao criar expressões de saída para respostas de inferência elementar.
+ Sempre verifique `response.statusCode` antes de processar o corpo. Se a chamada falhar, `response.body` é`null`.
+ Use `$distinct()` para desduplicar categorias em várias capturas.
+ A inferência elementar retorna várias IAB categorias por foto e um conjunto de categorias de segurança da GARM marca. Para saber os limites atuais, consulte a documentação da Inferência Elemental.
+ Quando a janela de tempo abrange vários disparos, a resposta contém vários itens na `items` matriz.
+ O tamanho máximo da resposta é de 20.000 caracteres. Se você receber respostas truncadas, reduza a janela de tempo.
+ Use as chaves `temp.*` de saída ao fazer o encadeamento com outras funções em a `SEQUENTIAL_EXECUTOR` e `player_params.*` ao passar valores diretamente para a URL do servidor de decisão de anúncios.
+ Para ver a lista completa de JSONata funções e operadores compatíveis, consulte[JSONata referência de expressão para funções](monetization-functions-jsonata.md).

Para ver o guia de configuração completo, incluindo pré-requisitos e políticas de recursos, consulte. [Integração com inferência elementar](monetization-functions-elemental-inference-integration.md) Para obter a referência do tipo de função, consulte[AWS solicitação de serviço](monetization-functions-types-aws-service-request.md).