Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Richieste di query per Amazon EC2

Le richieste di query sono richieste HTTP o HTTPS che utilizzano il verbo HTTP GET o POST e un parametro Query denominato. Action Per ogni azione dell'API Amazon EC2, puoi scegliere se utilizzare GET o POST. Indipendentemente dal verbo scelto, vengono inviati e ricevuti gli stessi dati. Per un elenco delle azioni API di Amazon EC2, consulta Azioni.

Struttura di una richiesta GET

La documentazione di Amazon EC2 presenta le richieste GET come URL, che possono essere utilizzate direttamente in un browser.

La richiesta è composta da quanto segue:

I seguenti parametri opzionali possono essere inclusi nella richiesta:

Per ulteriori informazioni sui parametri comuni per le richieste API, vedere Parametri di query comuni.

Di seguito è riportato un esempio di richiesta che avvia le istanze:

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

Per rendere queste richieste di esempio ancora più facili da leggere, AWS la documentazione può presentarle nel seguente formato:

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

La prima riga specifica l'endpoint della richiesta. Dopo l'endpoint c'è un punto interrogativo (?), che separa l'endpoint dai parametri. Per ulteriori informazioni sugli endpoint Amazon EC2, consulta Amazon EC2 Service Endpoints.

Il parametro Action indica l'operazione da eseguire. Per un elenco completo delle azioni, consulta Azioni. Le righe rimanenti specificano parametri aggiuntivi per la richiesta.

Negli esempi di richieste di query che presentiamo nella documentazione dell'API Amazon EC2, omettiamo le intestazioni, i parametri richiesti comuni e i parametri di autenticazione per consentirti di concentrarti più facilmente sui parametri dell'azione. Li sostituiamo con la stringa &AUTHPARAMS letterale per ricordarti che devi includere questi parametri nella tua richiesta; ad esempio:

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

Parametri di query

Ogni richiesta di Query deve includere i parametri comuni richiesti per gestire l'autenticazione e la selezione di un'azione. I parametri di query distinguono tra maiuscole e minuscole

Alcune operazioni accettano elenchi di parametri. Questi elenchi vengono specificati utilizzando la notazione param.n, dove n è un numero intero che inizia da 1.

L'esempio seguente aggiunge più dispositivi a una mappatura di dispositivi a blocchi utilizzando un elenco di parametri. 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

Autenticazione tramite API di query

È possibile inviare richieste di Query tramite il protocollo HTTP o HTTPS.

Indipendentemente dal protocollo utilizzato, è necessario includere una firma in ogni richiesta di Query. Amazon EC2 supporta Signature versione 2 e Signature versione 4. Ti consigliamo di utilizzare Signature Version 4. Per ulteriori informazioni, consulta Signing AWS API request nella IAM User Guide.

Le richieste Signature Version 4 consentono di specificare tutti i parametri di autorizzazione in un'unica intestazione, ad esempio:

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

Strutture di risposta alle interrogazioni

In risposta a una richiesta Query, il servizio restituisce una struttura di dati XML conforme a uno schema XML definito per Amazon EC2. La struttura di una risposta XML è specifica della richiesta associata. In generale, i tipi di dati di risposta sono denominati in base all'operazione eseguita e al fatto che il tipo di dati sia un contenitore (può avere figli). Alcuni esempi di contenitori includono groupSet i gruppi di sicurezza e keySet le coppie di chiavi (vedi l'esempio che segue). Gli elementi degli elementi sono elementi secondari dei contenitori e il loro contenuto varia in base al ruolo del contenitore.

Ogni risposta riuscita include un ID di richiesta in un requestId elemento e ogni risposta non riuscita include un ID di richiesta in un RequestID elemento. Il valore è una stringa univoca che AWS assegna. In caso di problemi con una richiesta particolare, ti AWS verrà chiesto l'ID della richiesta per aiutarti a risolvere il problema. Di seguito viene illustrato un esempio di risposta.

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

Paginazione

Per le azioni che possono restituire un lungo elenco di elementi, l'API Amazon EC2 include parametri per supportare l'impaginazione:MaxResults, NextToken (input) e nextToken (output). Con l'impaginazione, si specifica una dimensione per MaxResults e quindi ogni chiamata restituisce 0 a MaxResults elementi e set. nextToken Se ci sono elementi aggiuntivi da iterare, non nextToken è nullo ed è possibile specificarne il valore nel NextToken parametro di una chiamata successiva per ottenere il set di elementi successivo. Con l'impaginazione, continuate a richiamare l'azione finché non diventa nextToken nulla, anche se ricevete meno di MaxResults elementi, inclusi zero elementi.

Se richiami un'azione di descrizione dell'API con un elenco di ID eMaxResults, la richiesta ha esito negativo e viene visualizzato l'errore. InvalidParameterCombination

Si consiglia di utilizzare l'impaginazione quando si utilizzano azioni di descrizione che possono potenzialmente restituire un gran numero di risultati, ad DescribeInstances esempio. L'utilizzo della paginazione limita il numero di articoli restituiti e il tempo necessario per la restituzione di queste chiamate.

Per ulteriori informazioni, consulta Pagination nella Amazon EC2 Developer Guide.

Prevenzione delle richieste tramite HTTP

Se il tuo carico di lavoro non richiede l'utilizzo di HTTP, ti consigliamo di evitarlo per impedire la trasmissione e la ricezione di dati non crittografati e di utilizzare invece HTTPS. Puoi utilizzare la chiave di condizione IAM aws:SecureTransportglobale nelle tue policy IAM per impedire agli utenti di inviare richieste tramite HTTP.

La seguente politica di esempio impedisce agli utenti di inviare richieste tramite HTTP.

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