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

# 提出 API 請求
<a name="making-api-requests"></a>

Amazon Verified Permissions 的查詢請求是使用 `POST`方法的 HTTP 或 HTTPS 請求。

## 已驗證的許可端點
<a name="avp-endpoints"></a>

*端點*是做為 Web 服務進入點的 URL。您可以在提出減少延遲的請求時，選取適當的 AWS 區域 端點。如需 Verified Permissions 所用端點的資訊，請參閱 中的 [Amazon Verified Permissions](https://docs.aws.amazon.com/general/latest/gr/verified-permissions.html)*Amazon Web Services 一般參考*。

## 請求參數
<a name="request-parameters"></a>

Amazon Verified Permissions 使用 JSON 型通訊協定。您可以在 HTTP 請求內文中以 JSON 形式傳遞請求參數。清單會以 JSON 陣列表示。如需詳細資訊，請參閱《*Amazon Verified Permissions API 參考*》中的[常見參數](https://docs.aws.amazon.com/verifiedpermissions/latest/apireference/CommonParameters.html)。

## 請求識別符
<a name="request-identifiers"></a>

在每個回應中， 會透過 `x-amzn-RequestId` HTTP 回應標頭 AWS 傳回請求 ID。此字串是 AWS 指派的唯一識別符，可提供追蹤資訊。雖然請求 ID 包含在每個回應中，但不會列在個別 API 文件頁面上，以改善可讀性並減少備援。

## 查詢 API 身分驗證
<a name="query-authentication"></a>

您可以透過 HTTPS 傳送查詢請求。您必須在每個查詢請求中包含簽章。如需建立和包含簽章的詳細資訊，請參閱《》中的[簽署 AWS API 請求](https://docs.aws.amazon.com/general/latest/gr/signing_aws_api_requests.html)*Amazon Web Services 一般參考*。

## 可用程式庫
<a name="using-libraries"></a>

AWS 為偏好使用特定語言 APIs 而非命令列工具和查詢 API 建置應用程式的軟體開發人員提供程式庫、範例程式碼、教學課程和其他資源。這些程式庫提供基本函數 （不包含在 APIs中），例如請求身分驗證、請求重試和錯誤處理，以便更輕鬆地開始使用。Verified Permissions 程式庫和資源可用於下列語言和平台：
+  [適用於 Go 的 AWS SDK](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/service/verifiedpermissions) 
+  [AWS 適用於 Java 的 SDK 2.x](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/verifiedpermissions/package-summary.html) 
+  [適用於 Java 的 AWS SDK 1.x](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/verifiedpermissions/package-summary.html) 
+  [適用於 JavaScript 的 AWS SDK](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/VerifiedPermissions.html) 
+  [適用於 .NET 的 AWS SDK](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/VerifiedPermissions/NVerifiedPermissions.html) 
+  [適用於 PHP 的 AWS SDK](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-verifiedpermissions-2022-07-28.html) 
+  [適用於 Python (Boto) 的 AWS SDK](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/verifiedpermissions.html) 
+  [適用於 Ruby 的 AWS SDK](https://github.com/aws/aws-sdk-ruby/tree/version-3/apis/verifiedpermissions/2021-12-01) 

如需所有語言的程式庫和範本程式碼的詳細資訊，請參閱[範例程式碼和程式庫](https://docs.aws.amazon.com/code-library)。

## 使用 `POST`方法提出 API 請求
<a name="avp-API-requests-using-post-method"></a>

如果您不使用其中一個 AWS SDKs，則可以使用 請求方法透過 HTTPS 提出 Verified Permissions `POST`請求。`POST` 方法會要求您在請求的 標頭中指定 操作，並在請求內文中提供 JSON 格式的操作資料。


| 標頭名稱 | 標頭值 | 
| --- | --- | 
| Host | Amazon Verified Permissions 端點。例如：`verifiedpermissions.us-east-1.amazonaws.com` | 
| X-Amz-Date | 您必須提供 HTTP 日期標頭或 the AWS *x-amz-date* 標頭中的時間戳記。有些 HTTP 用戶端程式庫不允許您設定日期標頭。當 *x-amz-date* 標頭存在時，系統會在請求身分驗證期間忽略任何日期標頭。<br />*x-amz-date* 標頭必須以 ISO 8601 基本格式指定。例如：`20130315T092054Z` | 
| Authorization | 一組授權參數， AWS 用於確保請求的有效性和真實性。如需建構此標頭的詳細資訊，請參閱《》中的[簽章第 4 版簽署程序](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html)*Amazon Web Services 一般參考*。 | 
| X-Amz-Target | 指定您要執行的 Verified Permissions 操作。<br />`VerifiedPermissions.{{API_Name}}`<br />例如，若要呼叫 `CreatePolicy`操作，請使用下列目標值。<br />`VerifiedPermissions.CreatePolicy` | 
| Content-Type | 指定輸入格式。使用下列值。<br />`application/x-amz-json-1.0` | 
| Accept | 指定回應格式。使用下列值。<br />`application/x-amz-json-1.0` | 
| Content-Length | 承載的大小，以位元組為單位。 | 
| Content-Encoding | 指定輸入和輸出的編碼格式。使用下列值。<br />`amz-1.0` | 

以下是 HTTP 請求的範例標頭，可在 中傳回指定政策存放區中所有政策的清單 AWS 帳戶 ，其中 `Principal`參考`User`名為 的 `alice`。在此範例中，該`Authorization`行在此處以單字包裝，以便於閱讀。不要用單字將其包裝在實際請求中。

```
POST / HTTP/1.1
Host: verifiedpermissions.us-east-1.amazonaws.com
X-Amz-Date: 20230101T200059Z
Accept-Encoding: identity
Content-Type: application/x-amz-json-1.0
X-Amz-Target: VerifiedPermissions.ListPolicies
User-Agent: <UserAgentString>
Authorization: AWS4-HMAC-SHA256 Credential=<Credential>, SignedHeaders=<Headers>, Signature=<Signature>
Content-Length: <PayloadSizeBytes>

{
    "PolicyStoreId": "PSExAmPLE222222222",
    "Filter": {
        "Principal": {
            "Id": {
                "EntityType": "User",
                "EntityId": "alice"
            }
        }
    }
}
```