View a markdown version of this page

Anfragen für Amazon EC2 abfragen - Amazon Elastic Compute Cloud
Struktur einer GET-AnforderungAbfrageparameterAPI-Authentifizierung abfragenAntwortstrukturen abfragenPaginierungAnfragen über HTTP verhindern

Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.

Anfragen für Amazon EC2 abfragen

Abfrageanfragen sind HTTP- oder HTTPS-Anfragen, die das HTTP-Verb GET oder POST und einen Abfrageparameter mit dem Namen verwenden. Action Für jede Amazon EC2 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 EC2-API-Aktionen finden Sie unter Aktionen.

Struktur einer GET-Anforderung

In der Amazon EC2 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 URL-kodieren. In der Amazon EC2 EC2-Dokumentation lassen wir die GET-Beispielanfragen unverschlüsselt, damit sie leichter lesbar sind.

Die Anfrage besteht aus den folgenden Teilen:

  • Endpunkt: Die URL, die als Einstiegspunkt für den Webdienst dient. Weitere Informationen finden Sie unter Amazon EC2 Service Endpoints.

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

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

  • Version: Die zu verwendende API-Version. Für die Amazon EC2 EC2-API ist 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, Signature Version 4 zu verwenden. Weitere Informationen finden Sie im IAM-Benutzerhandbuch unter AWS API-Anfragen signieren.

Die folgenden optionalen Parameter können in Ihre Anfrage aufgenommen werden:

  • 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 kehrt sie zurückUnauthorizedOperation.

  • 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 eine Beispielanforderung, mit der Instances gestartet werden:

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

Damit diese Beispielanfragen noch leichter lesbar sind, können sie in der AWS Dokumentation im folgenden Format dargestellt werden:

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-Service Endpoints.

Der Parameter Action gibt die auszuführende Aktion an. Eine vollständige Liste der Aktionen finden Sie unter Aktionen. In den verbleibenden Zeilen werden zusätzliche Parameter für die Anforderung angegeben.

In den Beispielabfrageanfragen, die wir in der Amazon EC2 EC2-API-Dokumentation präsentieren, lassen wir die Header, häufig erforderlichen Parameter und Authentifizierungsparameter weg, damit Sie sich leichter auf die Parameter für die Aktion konzentrieren können. Wir ersetzen sie durch die &AUTHPARAMS wörtliche Zeichenfolge, 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 und befolgen Sie die Anweisungen unter AWS Sicherheitsnachweise.

Abfrageparameter

Jede Abfrageanforderung muss die erforderlichen gemeinsamen Parameter für die Authentifizierung und Auswahl einer Aktion enthalten. Bei Abfrageparametern wird Groß- und Kleinschreibung beachtet.

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

Im folgenden Beispiel werden mithilfe einer Liste von Parametern mehrere Geräte zu einer Blockgerätezuordnung hinzugefügt. 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-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 hinzufügen. Amazon EC2 unterstützt Signature Version 2 und Signature Version 4. Wir empfehlen, Signature Version 4 zu verwenden. Weitere Informationen finden Sie im IAM-Benutzerhandbuch unter AWS API-Anfragen signieren.

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

Antwortstrukturen abfragen

Als Antwort auf eine Query-Anfrage 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 nach dem ausgeführten Vorgang benannt und danach, ob es sich bei dem Datentyp um einen Container handelt (kann untergeordnete Elemente enthalten). Zu den Containern gehören groupSet beispielsweise Sicherheitsgruppen und keySet Schlüsselpaare (siehe das folgende Beispiel). Elementelemente sind untergeordnete Elemente von Containern, und ihr Inhalt hängt von der Rolle des Containers ab.

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 zugewiesen wird. Wenn Sie jemals Probleme mit einer bestimmten Anfrage haben, AWS werden Sie nach der Anfrage-ID gefragt, um das Problem zu beheben. Im Folgenden finden Sie 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 alle neuen Amazon EC2 EC2-API-Aktionen oder neu unterstützten AWS Regionen keine neuen Zeilen und Einrückungen. Wenn Sie einen benutzerdefinierten Client verwenden, stellen Sie sicher, dass dieser nicht auf die Antworten, einschließlich neuer Zeilen und Einrückungen, angewiesen ist.

  • Ab dem 31. Juli 2025 werden die XML-Datenstrukturen in den Antworten keine neuen Zeilen und Einrückungen mehr enthalten. Diese Änderung wird die Größe der Antworten reduzieren. Wenn Sie einen benutzerdefinierten Client verwenden, stellen Sie sicher, dass dieser nicht auf die Antworten, einschließlich neuer Zeilen und Einrückungen, angewiesen ist.

  • 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 EC2-API Parameter zur Unterstützung der Paginierung:MaxResults, NextToken (Eingabe) und nextToken (Ausgabe). Bei der Seitennummerierung geben Sie eine Größe für an, MaxResults und dann gibt jeder Aufruf 0 für MaxResults Elemente und Sätze zurück. nextToken Wenn es weitere Elemente gibt, die iteriert werden müssen, nextToken ist dieser 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 der Wert Null nextToken ist, auch wenn Sie weniger als MaxResults Elemente erhalten, einschließlich Null.

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

Wir empfehlen, die Paginierung zu verwenden, wenn Sie Beschreibungsaktionen verwenden, die potenziell zu einer großen Anzahl von Ergebnissen führen können, z. B. DescribeInstances Durch die Paginierung werden die Anzahl der zurückgegebenen Elemente und die Zeit, die benötigt wird, bis diese Aufrufe zurückgegeben werden, begrenzt.

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

Anfragen über HTTP verhindern

Wenn Ihr Workload nicht erfordert, dass Sie HTTP verwenden, empfehlen wir, es nicht zu verwenden, um das Senden und Empfangen unverschlüsselter Daten zu verhindern, und stattdessen HTTPS zu verwenden. Sie können den aws:SecureTransportglobalen 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"
                }
            }
        }
    ]
}