GET リクエストの構造クエリパラメータクエリ API 認証クエリレスポンス構造 Pagination (ページ分割)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 リクエストをエンコードしません。

リクエストは、以下で構成されます。

エンドポイント: ウェブサービスのエントリポイントとして機能する URL。詳細については、Amazon EC2 サービスエンドポイント」を参照してください。
アクション: 実行するアクション。たとえば、を使用してインスタンスを起動RunInstancesします。
パラメータ: アクションのパラメータ。各パラメータはアンパサンド (&) で区切られます。
バージョン: 使用する API バージョン。Amazon EC2 API の場合、バージョンは 2016-11-15 です。
認可パラメータ: リクエストの有効性と信頼性を確保するためにが AWS 使用する認可パラメータ。Amazon EC2 は、署名バージョン 2 と署名バージョン 4 をサポートしています。署名バージョン 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 は、署名バージョン 2 と署名バージョン 4 をサポートしています。署名バージョン 4 を使用することをお勧めします。詳細については、IAM ユーザーガイドの AWS API リクエストの署名を参照してください。

署名バージョン 4 リクエストでは、1 つのヘッダーですべての認可パラメータを指定できます。次に例を示します。


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

クエリレスポンス構造

クエリリクエストに応答して、サービスは Amazon EC2 に定義された XML スキーマに準拠する 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 データ構造に新しい行とインデントが含まれなくなります。この変更により、レスポンスのサイズが小さくなります。カスタムクライアントを使用する場合は、新しい行やインデントなどのレスポンスに依存していないことを確認してください。
ネストされた構造内の要素を含む、レスポンス内の要素の順序は異なる場合があります。アプリケーションは、要素が特定の順序で表示されると想定しないでください。

Pagination (ページ分割)

項目の長いリストを返すことができるアクションの場合、Amazon EC2 API にはページ分割をサポートするパラメータ MaxResults、 NextToken (入力）、 nextToken (出力) が含まれます。ページ分割では、のサイズを指定しMaxResults、各呼び出しがMaxResults項目に 0 を返し、を設定しますnextToken。反復する追加の項目がある場合、 nextTokenは null ではなく、後続の呼び出しの NextTokenパラメータでその値を指定して、次の項目のセットを取得できます。ページ分割では、 nextTokenが null になるまでアクションを呼び出し続けます。ゼロMaxResults項目を含む未満の項目を受信した場合も同様です。

IDs のリストとの両方を使用して describe API アクションを呼び出すとMaxResults、リクエストはエラーで失敗しますInvalidParameterCombination。

など、多数の結果を返す可能性のある describe アクションを使用する場合は、ページ分割を使用することをお勧めしますDescribeInstances。ページ分割を使用すると、返される項目の数と、これらの呼び出しが戻るのにかかる時間が制限されます。

詳細については、Amazon EC2 デベロッパーガイド」の「ページ分割」を参照してください。

HTTP 経由のリクエストの防止

ワークロードで HTTP を使用する必要がない場合は、暗号化されていないデータの送受信を防ぎ、代わりに HTTPS を使用するように、HTTP を使用しないことをお勧めします。IAM ポリシーでaws:SecureTransportグローバル IAM 条件キーを使用して、ユーザーが HTTP 経由でリクエストを送信できないようにすることができます。

次のポリシー例では、ユーザーが HTTP 経由でリクエストを送信できないようにします。


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

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

AWS Wavelength アクション

CORS サポート