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

# 使用查詢 API
<a name="programmingguide.queryapi"></a>

## 查詢參數
<a name="query-parameters"></a>

HTTP 查詢型請求是使用 HTTP 動詞 GET 或 POST，以及名為 `Action` 之查詢參數的 HTTP 請求。

每一個查詢請求都須包括一些常用參數，來處理動作的身分驗證和選取。

部分操作有數個參數清單。這些清單是使用 `param.n` 表示法來指定的。*n* 的值是從 1 開始的整數。

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

您只能透過 HTTPS 傳送查詢請求，而且必須在每一個查詢請求中包括一個簽章。本節說明如何建立簽章。下列程序所述的方法也稱為*「簽章第 4 版」*。

下列為用來對 AWS進行驗證要求的基本步驟。這會假設您已向 註冊， AWS 並具有存取金鑰 ID 和私密存取金鑰。

**查詢身分驗證程序**

1. 寄件者建構 的請求 AWS。

1. 寄件者會計算請求簽章，其為使用 SHA-1 雜湊函數的雜湊型訊息身分驗證程式碼 (HMAC) 的金鑰式雜湊，如本主題下一節所述。

1. 請求的寄件者會將請求資料、簽章和存取金鑰 ID （使用的私密存取金鑰的金鑰識別符） 傳送至 AWS。

1. AWS 使用存取金鑰 ID 來查詢私密存取金鑰。

1. AWS 會使用用於計算請求中簽章的相同演算法，從請求資料和私密存取金鑰產生簽章。

1. 如果簽章相符，則會將請求視為真實請求。若比較失敗，則會捨棄該要求，且 AWS 會傳回錯誤回應。

**注意**  
如果請求包含 `Timestamp` 參數，針對請求計算出的簽章就會在其值的 15 分鐘後過期。  
如果請求包含 `Expires` 參數，簽章就會於 `Expires` 參數指定的時間過期。

**計算請求簽章**

1. 建立標準化查詢字串，以在本程序稍後使用：

   1. 依據參數名稱與自然位元組順序，排序 UTF-8 查詢字串元件。參數可以來自 GET URI 或 POST 內文 (當 Content-Type 為 application/x-www-form-urlencoded 時)。

   1. 根據下列規則，為每個參數名稱和值執行 URL 編碼：

      1. 請不要針對 RFC 3986 所定義的任何未預留字元執行 URL 編碼。這些未預留字元包括 A-Z、a-z、0-9、連字號 (-)、底線 (\$1)、句點 (.) 及波狀符號 (\$1)。

      1. 對所有其他含有 %XY 的字元執行百分比編碼，其中 X 和 Y 是十六進位字元 0-9 和大寫 A-F。

      1. 對 %XY%ZA... 格式的延伸 UTF-8 字元執行百分比編碼。

      1. 將空白字元百分比編碼為 %20 (而非常見編碼機制使用的 \$1)。

   1. 使用等號 (=) (ASCII 字元 61) 分隔編碼過的參數名稱與其編碼值，即使該參數值為空白也是如此。

   1. 使用 & 符號 (ASCII 字碼 38) 分隔名稱值對。

1. 依據下列虛擬語法 ("\$1n" 代表 ASCII 換行符號)，建立要簽署的字串。

   ```
   StringToSign = HTTPVerb + "\n" +
   ValueOfHostHeaderInLowercase + "\n" +
   HTTPRequestURI + "\n" +
   CanonicalizedQueryString <from the preceding step>
   ```

   HTTPRequestURI 元件是 URI 的 HTTP 絕對路徑元件，一直到查詢字串為止 (但不包括查詢字串)。如果 HTTPRequestURI 空白，請使用斜線 (/)。

1. 使用您剛建立的字串、私密存取金鑰做為金鑰，以及 SHA256 或 SHA1 做為雜湊演算法，計算 RFC 2104 相容的 HMAC。

   如需詳細資訊，請參閱 [https://www.ietf.org/rfc/rfc2104.txt](https://www.ietf.org/rfc/rfc2104.txt)。

1. 將結果值轉換成 base64。

1. 將該值包含為請求中的 `Signature` 參數值。

例如，以下是範例請求 (為了清楚起見，已加入分行符號)。

```
https://memory-db.us-east-1.amazonaws.com/
    ?Action=DescribeClusters
    &ClusterName=myCluster
    &SignatureMethod=HmacSHA256
    &SignatureVersion=4
    &Version=2021-01-01
```

針對上述的查詢字串，您可透過下列字串來計算 HMAC 簽章。

```
GET\n
    memory-db.amazonaws.com\n
    Action=DescribeClusters
    &ClusterName=myCluster
    &SignatureMethod=HmacSHA256
    &SignatureVersion=4
    &Version=2021-01-01
    &X-Amz-Algorithm=Amazon4-HMAC-SHA256
    &X-Amz-Credential=AKIADQKE4SARGYLE%2F20140523%2Fus-east-1%2Fmemorydb%2Faws4_request
    &X-Amz-Date=20210801T223649Z
    &X-Amz-SignedHeaders=content-type%3Bhost%3Buser-agent%3Bx-amz-content-sha256%3Bx-amz-date
        content-type:
        host:memory-db.us-east-1.amazonaws.com
        user-agent:ServicesAPICommand_Client
    x-amz-content-sha256:
    x-amz-date:
```

結果為下列簽署的請求。

```
https://memory-db.us-east-1.amazonaws.com/
    ?Action=DescribeClusters
    &ClusterName=myCluster
    &SignatureMethod=HmacSHA256
    &SignatureVersion=4
    &Version=2021-01-01
    &X-Amz-Algorithm=Amazon4-HMAC-SHA256
    &X-Amz-Credential=AKIADQKE4SARGYLE/20141201/us-east-1/memorydb/aws4_request
    &X-Amz-Date=20210801T223649Z
    &X-Amz-SignedHeaders=content-type;host;user-agent;x-amz-content-sha256;x-amz-date
    &X-Amz-Signature=2877960fced9040b41b4feaca835fd5cfeb9264f768e6a0236c9143f915ffa56
```

如需簽署程序和計算請求簽章的詳細資訊，請參閱 Signature 第 [4 版簽署程序](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html)主題及其子主題。