Anfragen für Amazon EC2 abfragen

Abfrageanforderungen sind HTTP- oder HTTPS-Anfragen, die das HTTP-Verb GET oder POST und einen Abfrageparameter namens verwenden. Action Für jede Amazon EC2-API-Aktion können Sie wählen, ob Sie GET oder POST verwenden möchten. Unabhängig davon, welches Verb Sie wählen, werden dieselben Daten gesendet und empfangen. Eine Liste der Amazon EC2-API-Aktionen finden Sie unter Aktionen.

Struktur einer GET-Anforderung

In der Amazon EC2-Dokumentation werden die GET-Anfragen als URLs dargestellt, die direkt in einem Browser verwendet werden können.

Anmerkung

Da es sich bei den GET-Anfragen um URLs handelt, müssen Sie die Parameterwerte per URL codieren. In der Amazon EC2-Dokumentation belassen wir die Beispiel-GET-Anfragen unverschlüsselt, um sie leichter lesbar zu machen.

Die Anfrage besteht aus den folgenden Elementen:

• Endpunkt: Die URL, die als Einstiegspunkt für den Webservice dient. Weitere Informationen finden Sie unter Amazon EC2-Serviceendpunkte.

• Aktion: Die Aktion, die Sie ausführen möchten, z. B. RunInstances zum Starten einer Instance verwenden.

• Parameter: Alle Parameter für die Aktion; jeder Parameter ist durch ein Und-Zeichen (&) getrennt.

• Version: Die zu verwendende API-Version. Für die Amazon EC2-API lautet die Version 2016-11-15.

• Autorisierungsparameter: Die Autorisierungsparameter, die AWS verwendet werden, um die Gültigkeit und Authentizität der Anfrage sicherzustellen. Amazon EC2 unterstützt Signature Version 2 und Signature Version 4. Wir empfehlen, dass Sie Signature Version 4 verwenden. Weitere Informationen finden Sie im IAM-Benutzerhandbuch unter Signieren von AWS API-Anfragen.

Die folgenden optionalen Parameter können in Ihrer Anfrage enthalten sein:

• DryRun: Prüft, ob Sie über die erforderlichen Berechtigungen für die Aktion verfügen, ohne die Anfrage tatsächlich zu stellen. Wenn Sie über die erforderlichen Berechtigungen verfügen, wird die Anfrage zurückgegeben. DryRunOperation Andernfalls wird sie zurückgegebenUnauthorizedOperation.

• SecurityToken: Das temporäre Sicherheitstoken, das durch einen Aufruf von abgerufen wurde AWS -Security-Token-Service.

Weitere Informationen zu allgemeinen Parametern für API-Anfragen finden Sie unter Allgemeine Abfrageparameter.

Im Folgenden finden Sie ein Beispiel für eine Anfrage, die Instanzen startet:

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

Um diese Beispielanfragen noch einfacher lesbar zu machen, kann die AWS Dokumentation sie im folgenden Format präsentieren:

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

Die erste Zeile gibt den Endpunkt der Anfrage an. Nach dem Endpunkt folgt ein Fragezeichen (?), das den Endpunkt von den Parametern trennt. Weitere Informationen zu Amazon EC2-Endpunkten finden Sie unter Amazon EC2-Serviceendpunkte.

Der Parameter Action gibt die auszuführende Aktion an. Eine vollständige Liste der Aktionen finden Sie unter Aktionen. https://docs.aws.amazon.com/AWSEC2/latest/APIReference/query-apis.html Die verbleibenden Zeilen geben zusätzliche Parameter für die Anforderung an.

In den Beispielabfrageanforderungen, die wir in der Amazon EC2-API-Dokumentation vorstellen, lassen wir die Header, häufig erforderliche Parameter und Authentifizierungsparameter weg, damit Sie sich leichter auf die Parameter für die Aktion konzentrieren können. Wir ersetzen sie durch die &AUTHPARAMS Literalzeichenfolge, um Sie daran zu erinnern, dass Sie diese Parameter in Ihre Anfrage aufnehmen müssen; zum Beispiel:

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

Wichtig

Bevor Sie Ihre Zugriffsschlüssel-ID für den Credential Parameter AWSAccessKeyId oder angeben, lesen Sie die Hinweise in den AWS Sicherheitsinformationen und folgen Sie ihnen.

Abfrageparameter

Jede Abfrageanforderung muss die erforderlichen gemeinsamen Parameter für die Authentifizierung und die Auswahl einer Aktion enthalten. Abfrageparameter unterscheiden zwischen Groß- und Kleinschreibung.

Einige Operationen verwenden Parameterlisten. Diese Listen werden mit der Param.n-Notation angegeben, wobei n eine Ganzzahl ist, die bei 1 beginnt.

Im folgenden Beispiel werden einer Blockgerätezuordnung mithilfe einer Liste von BlockDeviceMapping Parametern mehrere Geräte hinzugefügt.

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-Authentifizierung abfragen

Sie können Query-Anfragen entweder über das HTTP- oder das HTTPS-Protokoll senden.

Unabhängig davon, welches Protokoll Sie verwenden, müssen Sie jeder Query-Anfrage eine Signatur beifügen. Amazon EC2 unterstützt Signature Version 2 und Signature Version 4. Wir empfehlen, dass Sie Signature Version 4 verwenden. Weitere Informationen finden Sie im IAM-Benutzerhandbuch unter Signieren von AWS API-Anfragen.

Mit Signature Version 4-Anfragen können Sie alle Autorisierungsparameter in einem einzigen Header angeben, zum Beispiel:

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

Strukturen für Abfragen und Antworten

Als Antwort auf eine Abfrageanforderung gibt der Service eine XML-Datenstruktur zurück, die einem für Amazon EC2 definierten XML-Schema entspricht. Die Struktur einer XML-Antwort ist spezifisch für die zugehörige Anfrage. Im Allgemeinen werden die Antwortdatentypen entsprechend der ausgeführten Operation benannt und danach, ob es sich bei dem Datentyp um einen Container handelt (der untergeordnete Elemente haben kann). Zu den Containern gehören beispielsweise Container groupSet für Sicherheitsgruppen und keySet für Schlüsselpaare (siehe das folgende Beispiel). Elementelemente sind untergeordnete Elemente von Containern, und ihr Inhalt variiert je nach Rolle des Containers.

Jede erfolgreiche Antwort enthält eine Anforderungs-ID in einem requestId Element, und jede erfolglose Antwort enthält eine Anforderungs-ID in einem RequestID Element. Der Wert ist eine eindeutige Zeichenfolge, die AWS zuweist. Wenn Sie jemals Probleme mit einer bestimmten Anfrage haben, AWS werden Sie nach der Anforderungs-ID gefragt, um das Problem zu beheben. Das Folgende zeigt ein Beispiel für eine Antwort.

<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>

Überlegungen

• Ab dem 31. Juli 2024 enthalten die XML-Datenstrukturen in den Antworten für neue Amazon EC2-API-Aktionen oder neu unterstützte AWS Regionen keine neuen Zeilen und Einrückungen. Wenn Sie einen benutzerdefinierten Client verwenden, stellen Sie sicher, dass er sich nicht auf die Antworten einschließlich neuer Zeilen und Einrückungen stützt.

• Ab dem 31. Juli 2025 enthalten die XML-Datenstrukturen in den Antworten keine neuen Zeilen und Einrückungen mehr. Durch diese Änderung wird die Größe der Antworten reduziert. Wenn Sie einen benutzerdefinierten Client verwenden, stellen Sie sicher, dass er sich nicht auf die Antworten einschließlich neuer Zeilen und Einrückungen stützt.

• Die Reihenfolge der Elemente in der Antwort, einschließlich der Elemente innerhalb verschachtelter Strukturen, kann variieren. Anwendungen sollten nicht davon ausgehen, dass die Elemente in einer bestimmten Reihenfolge erscheinen.

Paginierung

Für Aktionen, die eine lange Liste von Elementen zurückgeben können, enthält die Amazon EC2-API Parameter zur Unterstützung der Paginierung:MaxResults, NextToken (Eingabe) und nextToken (Ausgabe). Bei der Paginierung geben Sie eine Größe für an, MaxResults und dann gibt jeder Aufruf 0 für MaxResults Elemente und Sets zurück. nextToken Wenn weitere Elemente iteriert werden müssen, nextToken ist der Wert ungleich Null und Sie können seinen Wert im NextToken Parameter eines nachfolgenden Aufrufs angeben, um den nächsten Satz von Elementen abzurufen. Bei der Paginierung rufen Sie die Aktion so lange auf, bis sie Null nextToken ist, auch wenn Sie weniger als MaxResults Elemente erhalten, einschließlich null Elemente.

Wenn Sie eine Describe-API-Aktion sowohl mit einer Liste von IDs als auch aufrufenMaxResults, schlägt die Anforderung mit dem Fehler InvalidParameterCombination fehl.

Wir empfehlen, die Paginierung zu verwenden, wenn Sie Describe-Aktionen verwenden, die potenziell eine große Anzahl von Ergebnissen zurückgeben können, wie DescribeInstances z. Die Verwendung der Paginierung begrenzt die Anzahl der zurückgegebenen Elemente und die Zeit, die benötigt wird, bis diese Aufrufe zurückgegeben werden.

Weitere Informationen finden Sie unter Paginierung im Amazon EC2 Developer Guide.

Verhinderung von Anfragen über HTTP

Wenn Sie für Ihren Workload HTTP nicht verwenden müssen, empfehlen wir Ihnen, es nicht zu verwenden, um das Senden und Empfangen unverschlüsselter Daten zu verhindern, und stattdessen HTTPS zu verwenden. Sie können den aws:SecureTransport globalen IAM-Bedingungsschlüssel in Ihren IAM-Richtlinien verwenden, um zu verhindern, dass Benutzer Anfragen über HTTP senden.

Die folgende Beispielrichtlinie verhindert, dass Benutzer Anfragen über HTTP senden.

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