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

# 編程 Amazon Rekognition 人臉活體 API
<a name="face-liveness-programming-api"></a>

若要使用 Amazon Rekognition 人臉活體 API，您必須建立執行下列步驟的後端：

1. 呼叫 [CreateFaceLivenessSession](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_CreateFaceLivenessSession.html) 以啟動人臉活體工作階段。`CreateFaceLivenessSession` 操作完成後，UI 會提示使用者提交影片自拍照。然後，AWS Amplify 的 FaceLivenessDetector 元件會呼叫 [StartFaceLivenessSession](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_rekognitionstreaming_StartFaceLivenessSession.html) 來執行活體偵測。

1. 呼叫 [GetFaceLivenessSessionResults](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_GetFaceLivenessSessionResults.html)，以傳回與人臉活體工作階段相關聯的偵測結果。

1. 按照 [Amplify 活体指南](https://ui.docs.amplify.aws/react/connected-components/liveness)中的步驟，繼續設定您的 React 應用程式以使用 FaceLivenessDetector 元件。

使用人臉活體之前，請確定您已建立 AWS 帳戶、設定 AWS CLI 和 AWS SDK，以及設定 AWS Amplify。您還應確保後端 API 的 IAM 政策具有涵蓋以下內容的權限：`GetFaceLivenessSessionResults` 和 `CreateFaceLivenessSession`。如需詳細資訊，請參閱 [先決條件](face-liveness-prerequisites.md) 一節。

## 步驟 1：CreateFaceLivenessSession
<a name="face-liveness-programming-api-create-session"></a>

CreateFaceLivenessSession API 操作會建立一個人臉活體工作階段，並傳回唯一的 `SessionId`。

作為此操作輸入的一部分，也可以指定 Amazon S3 儲存貯體位置。這允許儲存參考映像並審核在人臉活體工作階段期間生成的映像。Amazon S3 儲存貯體必須在呼叫者的 AWS 帳戶中，與人臉活體端點位於同一區域。此外，S3 物件金鑰是由人臉活體系統所產生。

也可以提供 `AuditImagesLimit`，其是一個介於 0 和 4 之間的數字。預設會設定為 0。傳回的映像數量是盡最大努力的結果，並以自拍影片的持續時間為基礎。

最後，您可以提供 ChallengePreference，包括您希望工作階段預設的挑戰類型和版本。根據預設，這會使用 FaceLivenessMovementAndLightChallenge，但可以設定為 FaceMovementChallenge。

**請求範例**

```
{
   "ClientRequestToken": "string",
   "KmsKeyId": "string",
   "Settings": { 
      "AuditImagesLimit": number,
      "ChallengePreferences": [ 
         { 
            "Type": "string",
            "Versions": { 
               "Maximum": "string",
               "Minimum": "string"
            }
         }
      ],
      "OutputConfig": { 
         "S3Bucket": "string",
         "S3KeyPrefix": "string"
      }
   }
}
```

**回應範例**

```
{
    {"SessionId": "0f959dbb-37cc-45d8-a08d-dc42cce85fa8"}
}
```

## 步驟 2：StartFaceLivenessSession
<a name="face-liveness-programming-api-start-session"></a>

當 CreateFaceLivenessSession API 操作完成時，AWS Amplify 元件會執行 StartFaceLivenessSession API 操作。系統會提示使用者擷取影片自拍照。為了進行成功的檢查，使用者必須將人臉放置於熒幕上的橢圓形內，同時保持良好的照明。如需詳細資訊，請參閱 [人臉活體的使用建議](recommendations-liveness.md)。

此 API 操作需要人臉活體工作階段期間擷取的影片、從 CreateFaceLivenessSession API 操作取得的 sessionId，以及 `onAnalysisComplete` 回呼。回呼可用於向後端發出訊號，以呼叫 GetFaceLivenessSessionResults API 操作，該操作會傳回可信度分數、參考和稽核映像。

請注意，此步驟是由使用者端應用程式上的 AWS Amplify FaceLivenessDetector 元件執行。您不需要執行其他設定即可呼叫 `StartFaceLivenessSession`。

## 步驟 3：GetFaceLivenessSessionResults
<a name="face-liveness-programming-api-get-session-results"></a>

GetFaceLivenessSessionResults API 操作會擷取特定人臉活體工作階段的結果。該操作需要輸入 sessionId，並傳回相應的人臉活性可信度分數。其還提供包括人臉邊界框的參考映像，以及檢核也包含人臉邊界框的映像。人臉活體的可信度得分範圍為 0 至 100。

**請求範例**

```
{"SessionId": "0f959dbb-37cc-45d8-a08d-dc42cce85fa8"}
```

**回應範例**

```
{
    "SessionId": "0f959dbb-37cc-45d8-a08d-dc42cce85fa8",
    "Confidence": 98.9735,
    "ReferenceImage": {
        "S3Object": { 
            "Bucket": "s3-bucket-name",
            "Name": "file-name",
        },
        "BoundingBox": { 
           "Height": 0.4943420886993408, 
            "Left": 0.8435328006744385, 
            "Top": 0.8435328006744385, 
            "Width": 0.9521094560623169}
    },
    "AuditImages": [{
        "S3Object": { 
            "Bucket": "s3-bucket-name",
            "Name": "audit-image-name",
        },
        "BoundingBox": { 
           "Width": 0.6399999856948853,
           "Height": 0.47999998927116394,
           "Left": 0.1644444465637207,
           "Top": 0.17666666209697723}
    }],
    "Status": "SUCCEEDED"
}
```

## 步驟 4：回應結果
<a name="face-liveness-programming-api-respond-results"></a>

在人臉活體工作階段之後，將檢查的可信度分數與指定的臨界值進行比較。如果分數高於閾值，則使用者可以轉到下一個螢幕或任務。如果檢查失敗，系統會通知使用者並提示您再試一次。