本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# AWS 服务请求
<a name="monetization-functions-types-aws-service-request"></a>

## 何时使用
<a name="monetization-functions-types-aws-service-request-when"></a>

使用`AWS_SERVICE_REQUEST`，您可以在清单个性化期间调用支持的 AWS 服务 API。目前，您可以调用 Elemental In GetMetadata ference 进行情境广告定位。

MediaTailor 使用自己的服务凭证对请求进行签名，并自动添加所需的身份验证和安全标头。您无需配置 IAM 角色或管理证书。

有关包括先决条件、资源策略和区域注意事项的指导性演练，请参阅[元素推理集成](monetization-functions-elemental-inference-integration.md)。

## 配置字段
<a name="monetization-functions-types-aws-service-request-fields"></a>

一个`AWS_SERVICE_REQUEST`函数有以下字段：
+ **运行时间**（必填）-表达式语言。将此设置为`JSONATA`。
+ **TargetService**（必填）-目标 AWS 服务。目前仅支持 `elemental-inference`。
+ **TargetRegion**（必填）— 目标服务的 AWS 区域。您可以使用静态值（例如，`us-west-2`）或JSONata表达式来实现动态分辨率（例如，`{%inference.region%}`）。
+ **MethodType**（必填）— HTTP 方法。支持的值为`GET`和`POST`，具体取决于目标服务 API。
+ **网址**（必填）- AWS 服务 API 的 HTTPS 端点。必须是有效的 AWS 端点 URL。您可以使用JSONata表达式来动态构建 URL。
+ **标头**（可选）-请求中包含的其他 HTTP 标头。有关标题限制，请参阅[安全模型](#monetization-functions-types-aws-service-request-security)。
+ **正文**（有条件）-请求正文。当`MethodType`是时为必填项`POST`。您可以使用JSONata表达式根据会话状态动态构建正文。
+ **RequestTimeoutMilliseconds**（必填）— 等待回复的时间。
+ **输出**（可选）-定义调用完成后生成的值。每个条目将输出键映射到可以引用该`response`对象的表达式。输出表达式可以引用中描述的相同`response`对象[响应字段](monetization-functions-types-http-request.md#monetization-functions-types-http-request-response)。

## 安全模型
<a name="monetization-functions-types-aws-service-request-security"></a>

MediaTailor 使用自己的服务角色对出站请求进行签名。您无需创建或配置 IAM 角色 MediaTailor 即可调用目标服务。

目标 AWS 资源必须具有资源策略，向 MediaTailor 服务主体授予访问权限`aws:SourceAccount`和`aws:SourceArn`条件。这些条件通过确保 MediaTailor 只能代表您的账户和特定的播放配置访问资源来提供跨服务访问保护。有关完整的资源策略示例，请参阅[授予对元素推理源的 MediaTailor 访问权限](monetization-functions-elemental-inference-integration.md#monetization-functions-elemental-inference-integration-access)。

**标头限制：**所有带有`X-Amz-`前缀的标头都是保留的。 MediaTailor 使用所需的身份验证和跨服务访问保护值覆盖这些标头。请勿在配置中包含`X-Amz-`标头。

## 请求的处理方式
<a name="monetization-functions-types-aws-service-request-phases"></a>

MediaTailor 分三个步骤处理`AWS_SERVICE_REQUEST`函数：

1. **生成请求 ** — 根据当前 MediaTailor 会话状态计算`Url``Headers`、和`Body`表达式。该 URL 必须是指定服务的有效端点。

1. **签署请求 ** — 使用其自己的指定`TargetService`和`TargetRegion`的服务凭证对请求进行 MediaTailor身份验证。

1. **处理响应 **-调用完成后， MediaTailor 计算 Output 模块中的表达式。这些表达式既可以引用原始会话状态，也可以引用调用返回的`response`对象。

## 响应字段
<a name="monetization-functions-types-aws-service-request-response"></a>

调用完成后，您可以在输出表达式中引用以下字段：


| 字段 | Type | 说明 | 
| --- | --- | --- | 
| response.body | 对象或数组 | 响应正文解析为 JSON。null如果正文超过 20,000 个字符或不是有效的 JSON，则设置为。 | 
| response.statusCode | 整数 |  AWS 服务返回的 HTTP 状态码。null在网络出现故障时设置为。 | 
| response.text | 字符串 | 原始响应正文为字符串，截断为 20,000 个字符。"Internal Error"在网络出现故障时设置为。 | 

**重要**  
最大响应大小为 20,000 个字符。超过此限制的响应会`response.body`导致设置为`null`。

## 错误处理
<a name="monetization-functions-types-aws-service-request-errors"></a>

以下介绍如何 MediaTailor 处理`AWS_SERVICE_REQUEST`函数的错误：
+ 如果请求超时（超过`RequestTimeoutMilliseconds`），则`response.statusCode`为`null`、`response.body`是`null`。您的输出表达式仍在运行。
+ 如果目标服务返回 4xx 或 5xx 错误，则`response.statusCode`包含 HTTP 状态代码并`response.body`包含错误响应（如果 JSON 有效且字符数少于 20,000 个）。
+ 如果响应正文超过 20,000 个字符，`response.body`则`null`即使响应成功。`response.text`用于原始截断内容。
+ 当函数失败或产生空输出时，使用没有该函数贡献的可用值 MediaTailor 继续进行广告插入。广告插播时间未被屏蔽。

**提示**  
请务必检查`response.statusCode`您的输出表达式以妥善处理错误。

## 示例：元素推断 GetMetadata
<a name="monetization-functions-types-aws-service-request-example"></a>

以下函数调用 Elemental Inference `GetMetadata` 来检索当前广告插播时间前后内容窗口的上下文元数据。该`Body`字段使用JSONata表达式从`inference.*`变量动态构造请求 JSON。它提取IAB分类类别和GARM品牌安全信号，然后将其存储为玩家参数，用于广告请求。

```
{
    "FunctionId": "eiContextualMetadata",
    "FunctionType": "AWS_SERVICE_REQUEST",
    "AwsServiceRequestConfiguration": {
        "Runtime": "JSONATA",
        "TargetService": "elemental-inference",
        "TargetRegion": "{%inference.region%}",
        "MethodType": "POST",
        "Url": "{%inference.dataEndpoint & '/v1/feed/' & inference.feedId & '/input/0/metadata'%}",
        "Headers": {
            "Content-Type": "application/json"
        },
        "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\": {}}}' %}",
        "RequestTimeoutMilliseconds": 2000,
        "Output": {
            "player_params.iabCategories": "{%response.statusCode = 200 ? $join($distinct(response.body.items.metadata.contextualMetadata.iabTaxonomy.categories.uniqueId), ',') : ''%}",
            "player_params.garmExcluded": "{%response.statusCode = 200 ? $join($distinct(response.body.items.metadata.contextualMetadata.garm.suitability.categories[flagged = true].category), ',') : ''%}"
        }
    }
}
```

在运行时，该`Body`表达式生成 JSON 负载，如下所示：

```
{
    "outputName": "my-contextual-output",
    "timeSpecification": {
        "ptsBased": {
            "startPts": 162000000,
            "endPts": 163600001,
            "timescale": 90000
        }
    },
    "parameters": {
        "contextualMetadata": {}
    }
}
```

该`startPts`值是以下两者中较晚的值：上一个广告插播时间结束 (`inference.previousBreakEndPts`) 或当前广告插播时间前 30 秒。该`endPts`值是当前休息时间的 PTS 加一。

**注意**  
`my-contextual-output`替换为元素推理源的上下文元数据输出的名称。

**注意**  
MediaTailor 在向元素推断发出的请求中自动包含`x-amzn-elemental-inference-skip-poll`标头。这样可以确保低延迟响应适合广告中断时间。

有关包括先决条件和资源策略在内的完整设置指南，请参阅[元素推理集成](monetization-functions-elemental-inference-integration.md)。