本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 呼叫 Amazon Rekognition Video 操作
Amazon Rekognition Video 是一種非同步 API，可以用來分析存放在 Amazon Simple Storage Service (Amazon S3) 儲存貯體中的影片。呼叫如 [StartPersonTracking](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_StartPersonTracking.html) 的 Amazon Rekognition Video `Start` 操作來開始影片分析。Amazon Rekognition Video 會將分析請求的結果發佈至 Amazon Simple Notification Service (Amazon SNS) 主題。您可以使用 Amazon Simple Queue Service (Amazon SQS) 佇列或 AWS Lambda 函數，從 Amazon SNS 主題取得影片分析請求的完成狀態。最後，您可以透過呼叫 Amazon Rekognition `Get` 操作 (如 [GetPersonTracking](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_GetPersonTracking.html)) 來取得影片分析請求結果。
下節中的資訊使用標籤偵測操作來顯示 Amazon Rekognition Video 在儲存於 Amazon S3 儲存貯體中的影片內偵測標籤 (物件、活動、概念與活動) 的方法。相同的方法適用於其他 Amazon Rekognition Video 操作 (例如，[StartFaceDetection](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_StartFaceDetection.html)和[StartPersonTracking](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_StartPersonTracking.html))。範例 [使用 Java 或 Python (SDK) 分析儲存於 Amazon S3 儲存貯體中的影片](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)
## 開始影片分析
[您可以透過呼叫 StartLabelDetection](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_StartLabelDetection.html) 來啟動 Amazon Rekognition Video 標籤偵測請求。以下是由 `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 Resource Name (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` 操作將傳回相同的 `JobId` 以用於對開始操作執行多個相同的呼叫，例如 `StartLabelDetection`。`ClientRequestToken` 符記有 7 天的存留期。在 7 天後，您可以再次使用它。如果您在符記的存留期內重新使用符記，會發生下列情況：
+ 如果您使用相同的 `Start` 操作與相同的輸入參數來重新使用字符，將傳回相同的 `JobId`。不會再次執行任務，而 Amazon Rekognition Video 也不會傳送完成狀態到已註冊的 Amazon SNS 主題。
+ 如果您以相同的 `Start` 操作搭配些微變更的參數來重新使用符記，您會得到一個 `IdempotentParameterMismatchException` (HTTP 狀態碼：400) 例外狀況。
+ 由於您會從 Amazon Rekognition 取得無法預測的結果，因此您不應使用具有不同 `Start` 操作的字符。
對於 `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**：您可以註冊 AWS Lambda 函數，以寫入 Amazon SNS 主題。當 Amazon Rekognition 通知 Amazon SNS 主題請求已完成時，將呼叫此功能。如果您需要伺服器端程式碼來處理影片分析請求的結果，請使用 Lambda 函數。例如，您可能想要使用伺服器端程式碼來標註影片，或在傳回資訊到客戶端應用程式前針對影片內容建立報告。我們也建議使用伺服器端處理大型影片，因為 Amazon Rekognition API 可能會傳回大量資料。
+ **Amazon Simple Queue Service**：您可以訂閱 Amazon SQS 佇列到 Amazon SNS 主題。接著請輪詢 Amazon SQS 佇列以擷取由 Amazon Rekognition 在影片分析請求完成時發佈的完成狀態。如需詳細資訊，請參閱 [使用 Java 或 Python (SDK) 分析儲存於 Amazon S3 儲存貯體中的影片](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` 來指定最大數量的結果，以在單次取得操作中傳回結果。`MaxResults` 的預設值為 1000。如果您指定的值大於 1000，最多只能傳回 1000 個結果。如果操作不會傳回整組結果，將在操作回應中傳回下一頁的分頁符記。如果您自前一個取得請求中獲得一個分頁符記，請搭配 `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` 彙總模式將隨著時間的推移彙總標籤，同時使用 2 FPS 採樣和每幀輸出為標籤 `TIMESTAMPS` 提供偵測到的時間戳 (注意：此當前採樣率可能會發生變化，不應對當前採樣率進行假設)。如未指定任何值，預設為 `TIMESTAMPS`。