View a markdown version of this page

Amazon EC2 的查詢請求 - Amazon Elastic Compute Cloud
GET 請求的結構查詢參數查詢 API 身分驗證查詢回應結構分頁防止透過 HTTP 提出請求

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

Amazon EC2 的查詢請求

查詢請求是使用 HTTP 動詞 GET 或 POST 的 HTTP 或 HTTPS 請求，以及名為 的查詢參數Action。對於每個 Amazon EC2 API 動作，您可以選擇使用 GET 或 POST。無論您選擇哪個動詞，都會傳送和接收相同的資料。如需 Amazon EC2 API 動作的清單，請參閱動作。

GET 請求的結構

Amazon EC2 文件會將 GET 請求顯示為 URLs，可直接在瀏覽器中使用。

注意

由於 GET 請求是 URLs，您必須對參數值進行 URL 編碼。在 Amazon EC2 文件中，我們會將範例 GET 請求保留為未編碼，以便於閱讀。

請求包含下列項目：

  • 端點：做為 Web 服務進入點的 URL。如需詳細資訊，請參閱 Amazon EC2 服務端點。

  • 動作：您要執行的動作；例如，使用 RunInstances啟動執行個體。

  • 參數：動作的任何參數；每個參數都以 ampersand (&) 分隔。

  • 版本：要使用的 API 版本。對於 Amazon EC2 API，版本為 2016-11-15。

  • 授權參數： AWS 用來確保請求有效性和真實性的授權參數。Amazon EC2 支援 Signature 第 2 版和 Signature 第 4 版。我們建議您使用 Signature 第 4 版。如需詳細資訊，請參閱《IAM 使用者指南》中的簽署 AWS API 請求。

下列選用參數可以包含在請求中：

  • DryRun：檢查您是否具有動作所需的許可，而無需實際提出請求。如果您有必要的許可，請求會傳回 DryRunOperation，否則會傳回 UnauthorizedOperation。

  • SecurityToken：透過呼叫 取得的臨時安全字符 AWS Security Token Service。

如需 API 請求常見參數的詳細資訊，請參閱常見查詢參數。

以下是啟動執行個體的範例請求：

https://ec2.amazonaws.com/?Action=RunInstances&ImageId=ami-2bb65342&MaxCount=3&MinCount=1&Placement.AvailabilityZone=us-east-1a&Monitoring.Enabled=true&Version=2016-11-15&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIDEXAMPLE%2F20130813%2Fus-east-1%2Fec2%2Faws4_request&X-Amz-Date=20130813T150206Z&X-Amz-SignedHeaders=content-type%3Bhost%3Bx-amz-date&X-Amz-Signature=525d1a96c69b5549dd78dbbec8efe264102288b83ba87b7d58d4b76b71f59fd2
Content-type: application/json
host:ec2.amazonaws.com

為了讓這些範例請求更易於讀取， AWS 文件可能會以下列格式呈現：

https://ec2.amazonaws.com/?Action=RunInstances
&ImageId=ami-2bb65342
&MaxCount=3
&MinCount=1
&Placement.AvailabilityZone=us-east-1a
&Monitoring.Enabled=true
&Version=2016-11-15
&X-Amz-Algorithm=AWS4-HMAC-SHA256
&X-Amz-Credential=AKIAIOSFODNN7EXAMPLEus-east-1%2Fec2%2Faws4_request
&X-Amz-Date=20130813T150206Z
&X-Amz-SignedHeaders=content-type%3Bhost%3Bx-amz-date
&X-Amz-Signature=ced6826de92d2bdeed8f846f0bf508e8559e98e4b0194b84example54174deb456c
Content-type: application/json
host:ec2.amazonaws.com

第一行指定請求的端點。端點後方為問號 (?)，將端點與參數區分開來。如需 Amazon EC2 端點的詳細資訊，請參閱 Amazon EC2 服務端點。

此 Action 參數指出要執行的動作。如需動作的完整清單，請參閱動作。剩餘行會指定請求的其他參數。

在 Amazon EC2 API 文件中呈現的查詢請求範例中，我們省略標頭、常見必要參數和身分驗證參數，讓您更輕鬆地專注於 動作的參數。我們將它們取代為&AUTHPARAMS常值字串，以提醒您必須在請求中包含這些參數；例如：

https://ec2.amazonaws.com/?Action=RunInstances
&ImageId=ami-2bb65342
&MaxCount=3
&MinCount=1
&Placement.AvailabilityZone=us-east-1a
&Monitoring.Enabled=true
&AUTHPARAMS
重要

在您為 AWSAccessKeyId或 Credential 參數指定存取金鑰 ID 之前，請檢閱並遵循AWS 安全登入資料中的指引。

查詢參數

每個查詢請求都必須包含必要的常見參數，才能處理 動作的身分驗證和選取。查詢參數區分大小寫。

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

下列範例會使用BlockDeviceMapping參數清單，將多個裝置新增至區塊型設備映射。

http://ec2.amazonaws.com/?Action=RunInstances
&ImageId.1=ami-72aa081b
...
&BlockDeviceMapping.1.DeviceName=/dev/sdj
&BlockDeviceMapping.1.Ebs.NoDevice=true
&BlockDeviceMapping.2.DeviceName=/dev/sdh
&BlockDeviceMapping.2.Ebs.VolumeSize=300
&BlockDeviceMapping.3.DeviceName=/dev/sdc
&BlockDeviceMapping.3.VirtualName=ephemeral1
&AUTHPARAMS

查詢 API 身分驗證

您可以透過 HTTP 或 HTTPS 通訊協定傳送查詢請求。

無論您使用哪種通訊協定，都必須在每個查詢請求中包含簽章。Amazon EC2 支援 Signature 第 2 版和 Signature 第 4 版。我們建議您使用 Signature 第 4 版。如需詳細資訊，請參閱《IAM 使用者指南》中的簽署 AWS API 請求。

Signature 第 4 版請求可讓您在單一標頭中指定所有授權參數，例如：

Content-Type: application/x-www-form-urlencoded; charset=UTF-8
X-Amz-Date: 20130813T150211Z
Host: ec2.amazonaws.com
Authorization: AWS4-HMAC-SHA256 Credential=AKIDEXAMPLE/202230813/us-east-1/ec2/aws4_request, SignedHeaders=content-type;host;x-amz-date, Signature=ced6826de92d2bdeed8f846f0bf508e8559e98e4b0194b84example54174deb456c

http://ec2.amazonaws.com/?Action=RunInstances
ImageId=ami-2bb65342
&MaxCount=3
&MinCount=1
&Monitoring.Enabled=true
&Placement.AvailabilityZone=us-east-1a
&Version=2016-11-15

查詢回應結構

為了回應查詢請求，服務會傳回 XML 資料結構，以符合為 Amazon EC2 定義的 XML 結構描述。XML 回應的結構專屬於相關聯的請求。一般而言，回應資料類型是根據執行的操作，以及資料類型是否為容器 （可以有子系） 來命名。容器的範例包括groupSet用於安全群組的 和keySet用於金鑰對的 （請參閱以下範例）。項目元素是容器的子項，其內容會根據容器的角色而有所不同。

每個成功的回應都會在 requestId 元素中包含請求 ID，而每個失敗的回應都會在 RequestID元素中包含請求 ID。此值是 AWS 指派的唯一字串。如果您遇到特定請求的問題， AWS 會要求請求 ID，以協助對問題進行故障診斷。以下顯示範例回應。

<DescribeKeyPairsResponse xmlns="http://ec2.amazonaws.com/doc/2016-11-15/">
  <requestId>7a62c49f-347e-4fc4-9331-6e8eEXAMPLE</requestId>
  <keySet>
    <item>
      <keyName>gsg-keypair</keyName>
      <keyFingerprint>
         00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00
      </keyFingerprint>
    </item>
  </keySet>
</DescribeKeyPairsResponse>
考量事項

  • 自 2024 年 7 月 31 日起，對於任何新的 Amazon EC2 API 動作或新支援的 AWS 區域，回應中的 XML 資料結構將不會包含新的行和縮排。如果您使用自訂用戶端，請確保它不依賴回應，包括新行和縮排。

  • 自 2025 年 7 月 31 日起，回應中的 XML 資料結構將不再包含新的行和縮排。此變更將減少回應的大小。如果您使用自訂用戶端，請確保它不依賴回應，包括新行和縮排。

  • 回應中的元素順序可能會有所不同，包括巢狀結構中的元素。應用程式不應假設元素以特定順序顯示。

分頁

對於可以傳回長項目清單的動作，Amazon EC2 API 包含支援分頁的參數：MaxResults、 NextToken（輸入） 和 nextToken（輸出）。使用分頁時，您可以指定 的大小，MaxResults然後每個呼叫都會傳回 0 到MaxResults項目並設定 nextToken。如果還有其他項目需要反覆運算，nextToken則 為非空值，您可以在後續呼叫的 NextToken 參數中指定其值，以取得下一組項目。透過分頁，您可以繼續呼叫 動作，直到 nextToken 為 null，即使您接收的項目少於 MaxResults 個項目，包括零個項目。

如果您使用 IDs 和 的清單呼叫描述 API 動作MaxResults，請求會失敗並顯示錯誤 InvalidParameterCombination。

我們建議您在使用描述可能傳回大量結果的動作時使用分頁，例如 DescribeInstances。使用分頁會限制傳回的項目數量，以及這些呼叫傳回所需的時間。

如需詳細資訊，請參閱《Amazon EC2 開發人員指南》中的分頁。

防止透過 HTTP 提出請求

如果您的工作負載不需要您使用 HTTP，建議您避免使用它來防止傳輸和接收未加密的資料，並改用 HTTPS。您可以在 IAM 政策中使用aws:SecureTransport全域 IAM 條件金鑰，以防止使用者透過 HTTP 傳送請求。

下列範例政策可防止使用者透過 HTTP 傳送請求。

{
    "Statement": [
        {
            "Sid": "AllowAllEC2HttpsRequests",
            "Effect": "Allow",
            "Action": "ec2:*",
            "Resource": "*",
            "Condition": {
                "StringEqualsIgnoreCase": {
                    "aws:SecureTransport": "true"
                }
            }
        }
    ]
}