本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 调用 Amazon Rekognition Video 操作
Amazon Rekognition Video 是一个异步 API，可用于分析存储在 Amazon Simple Storage Service (Amazon S3) 存储桶的视频。您可以通过调用 Amazon Rekognit `Start` ion Video 操作开始分析视频，例如。[StartPersonTracking](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_StartPersonTracking.html)Amazon Rekognition Video 将分析请求的结果发布到 Amazon Simple Notification Service (Amazon SNS) 主题。您可以使用亚马逊简单队列服务 (Amazon SQS) Simple Queue 队列或 AWS Lambda 函数来获取来自亚马逊 SNS 主题的视频分析请求的完成状态。最后，您可以通过调用 Amazon Rekognit `Get` ion 操作来获取视频分析请求结果，例如。[GetPersonTracking](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_GetPersonTracking.html)
以下各节中的信息使用标签检测操作来展示 Amazon Rekognition Video 如何在存储于 Amazon S3 存储桶的视频中检测标签（对象、事件、概念和活动）。同样的方法也适用于其他 Amazon Rekognition Video 操作——例如，和。[StartFaceDetection[StartPersonTracking](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_StartPersonTracking.html)](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_StartFaceDetection.html)示例 [使用 Java 或 Python 分析存储在 Amazon S3 存储桶中的视频 (SDK)](video-analyzing-with-sqs.md) 说明了如何通过使用 Amazon SQS 队列从 Amazon SNS 主题获取完成状态来分析视频。它还用作其他 Amazon Rekognition Video 示例（如[人物的轨迹](persons.md)）的基础。有关 AWS CLI 示例，请参阅[使用分析视频 AWS Command Line Interface](video-cli-commands.md)。
**Topics**
+ [
## 启动视频分析
](#api-video-start)
+ [
## 获取 Amazon Rekognition Video 分析请求的完成状态
](#api-video-get-status)
+ [
## 获取 Amazon Rekognition Video 分析结果
](#api-video-get)
## 启动视频分析
您可以通过致电来启动亚马逊 Rekognition Video 标签检测请求。[StartLabelDetection](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_StartLabelDetection.html)下面是由 `StartLabelDetection` 传递的 JSON 请求的示例。
```
{
"Video": {
"S3Object": {
"Bucket": "amzn-s3-demo-bucket",
"Name": "video.mp4"
}
},
"ClientRequestToken": "LabelDetectionToken",
"MinConfidence": 50,
"NotificationChannel": {
"SNSTopicArn": "arn:aws:sns:us-east-1:nnnnnnnnnn:topic",
"RoleArn": "arn:aws:iam::nnnnnnnnnn:role/roleopic"
},
"JobTag": "DetectingLabels"
}
```
输入参数 `Video` 提供视频文件名以及从中检索此文件的 Amazon S3 存储桶。`NotificationChannel` 包含 Amazon Rekognition Video 在视频分析请求完成时通知的 Amazon SNS 主题的 Amazon 资源名称 (ARN)。Amazon SNS 主题必须与您调用的 Amazon Rekognition Video 端点位于同一 AWS 区域。`NotificationChannel` 还包含允许 Amazon Rekognition Video 向 Amazon SNS 主题进行发布的角色的 ARN。您通过创建 IAM 服务角色为 Amazon Rekognition 提供向您的 Amazon SNS 主题进行发布的权限。有关更多信息，请参阅 [配置 Amazon Rekognition Video](api-video-roles.md)。
您也可以指定一个可选输入参数 `JobTag`，该参数使您能够标识处于已发布到 Amazon SNS 主题的完成状态的任务。
为防止分析任务意外重复，您可以选择性地提供幂等令牌 `ClientRequestToken`。如果您为 `ClientRequestToken` 提供了一个值，`Start` 操作将为对 start 操作的多个相同调用（如 `StartLabelDetection`）返回相同的 `JobId`。`ClientRequestToken` 令牌的使用期限为 7 天。7 天后，您可以重复使用它。如果您在令牌使用期限内重复使用令牌，则会出现以下情况：
+ 如果您通过相同的 `Start` 操作和相同的输入参数重复使用此令牌，则将返回相同的 `JobId`。此任务不会再次执行，Amazon Rekognition Video 不会向注册的 Amazon SNS 主题发送完成状态。
+ 如果您对相同的 `Start` 操作重复使用此令牌，并且只进行了细微的输入参数更改，则会引发 `IdempotentParameterMismatchException`（HTTP 状态代码：400）异常。
+ 您不应该通过其他 `Start` 操作重复使用令牌，因为从 Amazon Rekognition 会得到不可预测的结果。
对 `StartLabelDetection` 操作的响应是作业标识符 (`JobId`)。使用 `JobId` 可跟踪请求并在 Amazon Rekognition Video 将完成状态发布到 Amazon SNS 主题之后获取分析结果。例如：
```
{"JobId":"270c1cc5e1d0ea2fbc59d97cb69a72a5495da75851976b14a1784ca90fc180e3"}
```
如果您以并发方式启动的作业过多，则调用 `StartLabelDetection` 会引发 `LimitExceededException`（HTTP 状态代码：400），直到并发运行的作业数量低于 Amazon Rekognition 服务限制。
如果您发现活动量陡增时会引发 `LimitExceededException` 异常，请考虑使用 Amazon SQS 队列管理传入请求。如果您发现 Amazon SQS 队列无法管理您的平均并发请求数，并且仍然收到`LimitExceededException`异常，请联系 AWS 支持人员。
## 获取 Amazon Rekognition Video 分析请求的完成状态
Amazon Rekognition Video 会将分析完成通知发送到注册的 Amazon SNS 主题。通知将在 JSON 字符串中包含操作的任务标识符和完成状态。成功的视频分析请求具有 `SUCCEEDED` 状态。例如，以下结果展示了标签检测任务的成功处理。
```
{
"JobId": "270c1cc5e1d0ea2fbc59d97cb69a72a5495da75851976b14a1nnnnnnnnnnnn",
"Status": "SUCCEEDED",
"API": "StartLabelDetection",
"JobTag": "DetectingLabels",
"Timestamp": 1510865364756,
"Video": {
"S3ObjectName": "video.mp4",
"S3Bucket": "amzn-s3-demo-bucket"
}
}
```
有关更多信息，请参阅 [参考：视频分析结果通知](video-notification-payload.md)。
要获取由 Amazon Rekognition Video 发布到 Amazon SNS 主题的状态信息，请使用以下选项之一：
+ **AWS Lambda** – 您可订阅写入到 Amazon SNS 主题的 AWS Lambda 函数。此函数在 Amazon Rekognition 通知 Amazon SNS 主题请求已完成时调用。如果您希望服务器端代码处理视频分析请求的结果，请使用 Lambda 函数。例如，在将信息返回到客户端应用程序之前，您可能希望使用服务器端代码来注释视频或创建有关视频内容的报告。我们还建议对大型视频进行服务器端处理，因为 Amazon Rekognition API 可能返回大量数据。
+ **Amazon Simple Queue Service** – 您可以为 Amazon SQS 队列订阅 Amazon SNS 主题。您随后将轮询 Amazon SQS 队列以检索 Amazon Rekognition 在视频分析请求完成后发布的完成状态。有关更多信息，请参阅 [使用 Java 或 Python 分析存储在 Amazon S3 存储桶中的视频 (SDK)](video-analyzing-with-sqs.md)。如果您希望仅从客户端应用程序调用 Amazon Rekognition Video 操作，请使用 Amazon SQS 队列。
**重要**
我们建议不要通过反复调用 Amazon Rekognition Video `Get` 操作来获取请求完成状态。这是因为 Amazon Rekognition Video 会在发出的请求过多时限制 `Get` 操作。如果您同时处理多个视频，那么监控一个 SQS 队列中的完成通知比为每个视频的状态分别轮询 Amazon Rekognition Video 更加简单有效。
## 获取 Amazon Rekognition Video 分析结果
要获取视频分析请求的结果，请先确保从 Amazon SNS 主题检索的完成状态为 `SUCCEEDED`。然后调用 `GetLabelDetection`，它将传递从 `StartLabelDetection` 返回的 `JobId` 值。请求 JSON 类似于以下示例：
```
{
"JobId": "270c1cc5e1d0ea2fbc59d97cb69a72a5495da75851976b14a1784ca90fc180e3",
"MaxResults": 10,
"SortBy": "TIMESTAMP"
}
```
JobId 是视频分析操作的标识符。由于视频分析会生成大量数据，请使用 `MaxResults` 指定要在单个 Get 操作中返回的结果的最大数量。`MaxResults` 的默认值为 1000。如果您指定的值大于 1000，则返回最多 1000 个结果。如果该操作未返回整个结果集，下一页的分页令牌将在操作响应中返回。如果您来自上一个 Get 请求的分页令牌，请将它与 `NextToken` 结合使用以获取下一页结果。
**注意**
Amazon Rekognition 将保留视频分析操作的结果 7 天。此时间过后，您将无法检索分析结果。
`GetLabelDetection` 操作响应 JSON 与以下内容类似：
```
{
"Labels": [
{
"Timestamp": 0,
"Label": {
"Instances": [],
"Confidence": 60.51791763305664,
"Parents": [],
"Name": "Electronics"
}
},
{
"Timestamp": 0,
"Label": {
"Instances": [],
"Confidence": 99.53411102294922,
"Parents": [],
"Name": "Human"
}
},
{
"Timestamp": 0,
"Label": {
"Instances": [
{
"BoundingBox": {
"Width": 0.11109819263219833,
"Top": 0.08098889887332916,
"Left": 0.8881205320358276,
"Height": 0.9073750972747803
},
"Confidence": 99.5831298828125
},
{
"BoundingBox": {
"Width": 0.1268676072359085,
"Top": 0.14018426835536957,
"Left": 0.0003282368124928324,
"Height": 0.7993982434272766
},
"Confidence": 99.46029663085938
}
],
"Confidence": 99.53411102294922,
"Parents": [],
"Name": "Person"
}
},
.
.
.
{
"Timestamp": 166,
"Label": {
"Instances": [],
"Confidence": 73.6471176147461,
"Parents": [
{
"Name": "Clothing"
}
],
"Name": "Sleeve"
}
}
],
"LabelModelVersion": "2.0",
"JobStatus": "SUCCEEDED",
"VideoMetadata": {
"Format": "QuickTime / MOV",
"FrameRate": 23.976024627685547,
"Codec": "h264",
"DurationMillis": 5005,
"FrameHeight": 674,
"FrameWidth": 1280
}
}
```
`GetLabelDetection` 和 `GetContentModeration` 操作允许您按时间戳或标签名称对分析结果进行分类。您还可以按视频片段或时间戳汇总结果。
您可按检测时间 (视频开始的时间 (毫秒)) 或检测到的实体 (物体、人脸、名人、审阅标签或人员) 的字母顺序为结果排序。要按时间排序，请将 `SortBy` 输入参数的值设置为 `TIMESTAMP`。如果未指定 `SortBy`，则默认行为是按时间排序。上述示例是按时间排序的。要按实体排序，请将 `SortBy` 输入参数与适用于您执行的操作的值结合使用。例如，要按在对 `GetLabelDetection` 的调用中检测到的标签排序，请使用值 `NAME`。
要按时间戳汇总结果，请将 `AggregateBy` 参数的值设置为 `TIMESTAMPS`。要按视频片段进行汇总，请将 `AggregateBy` 的值设置为 `SEGMENTS`。`SEGMENTS` 汇总模式将随着时间的推移汇总标签，同时`TIMESTAMPS`给出检测到标签的时间戳，使用 2 FPS 采样和每帧输出（注意：当前采样率可能会发生变化，不应假设当前的采样率）。如果未指定值，则默认汇总方法为 `TIMESTAMPS`。