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.](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/query-apis.html)
**Topics**
+ [Struttura di una richiesta GET](#structure-of-a-get-request)
+ [Parametri di query](#query-parameters)
+ [Autenticazione tramite API di query](#query-authentication)
+ [Strutture di risposta alle interrogazioni](#api-responses)
+ [Paginazione](#api-pagination)
+ [Prevenzione delle richieste tramite HTTP](#prevent-http-requests)
## Struttura di una richiesta GET
La documentazione di Amazon EC2 presenta le richieste GET come URL, che possono essere utilizzate direttamente in un browser.
**Nota**
Poiché le richieste GET sono URL, è necessario codificare i valori dei parametri tramite URL. Nella documentazione di Amazon EC2, lasciamo le richieste GET di esempio non codificate per renderle più facili da leggere.
La richiesta è composta da quanto segue:
+ **Endpoint**: l'URL che funge da punto di ingresso per il servizio Web. Per ulteriori informazioni, consulta gli [endpoint dei servizi Amazon EC2](https://docs.aws.amazon.com/ec2/latest/devguide/ec2-endpoints.html).
+ **Azione**: L'azione che desideri eseguire; ad esempio, utilizzare per `RunInstances` avviare un'istanza.
+ **Parametri**: qualsiasi parametro dell'azione; ogni parametro è separato da una e commerciale (&).
+ **Versione**: la versione dell'API da utilizzare. Per l'API Amazon EC2, la versione è il 15/11/2016.
+ **Parametri di autorizzazione**: i parametri di autorizzazione AWS utilizzati per garantire la validità e l'autenticità della richiesta. 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](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-signing.html) nella *IAM User Guide*.
I seguenti parametri opzionali possono essere inclusi nella richiesta:
+ **DryRun**: verifica se si dispone delle autorizzazioni necessarie per l'azione, senza effettuare effettivamente la richiesta. Se si dispone delle autorizzazioni richieste, la richiesta viene restituita`DryRunOperation`; in caso contrario, viene restituita. `UnauthorizedOperation`
+ **SecurityToken**: il token di sicurezza temporaneo ottenuto tramite una chiamata a AWS Security Token Service.
Per ulteriori informazioni sui parametri comuni per le richieste API, vedere [Parametri di query comuni](https://docs.aws.amazon.com//AWSEC2/latest/APIReference/CommonParameters.html).
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](https://docs.aws.amazon.com/ec2/latest/devguide/ec2-endpoints.html) EC2 Service Endpoints.
Il parametro `Action` indica l'operazione da eseguire. [Per un elenco completo delle azioni, consulta Azioni.](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/query-apis.html) 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](https://docs.aws.amazon.com//AWSEC2/latest/APIReference/CommonParameters.html) 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
```
**Importante**
Prima di specificare l'ID della chiave di accesso per il `Credential` parametro `AWSAccessKeyId` or, esamina e segui le indicazioni contenute nelle [credenziali AWS di sicurezza](https://docs.aws.amazon.com/IAM/latest/UserGuide/security-creds.html).
## 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](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-signing.html) 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.
```
7a62c49f-347e-4fc4-9331-6e8eEXAMPLE
-
gsg-keypair
00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00
```
**Considerazioni**
+ A partire dal 31 luglio 2024, per tutte le nuove azioni API di Amazon EC2 o le nuove regioni AWS supportate, le strutture di dati XML nelle risposte non includeranno nuove righe e rientri. Se utilizzi un client personalizzato, assicurati che non si basi sulle risposte, incluse nuove righe e rientri.
+ A partire dal 31 luglio 2025, le strutture di dati XML nelle risposte non includeranno più nuove righe e rientri. Questa modifica ridurrà la dimensione delle risposte. Se utilizzi un client personalizzato, assicurati che non si basi sulle risposte, incluse nuove righe e rientri.
+ L'ordine degli elementi nella risposta, inclusi quelli all'interno di strutture annidate, potrebbe variare. Le applicazioni non devono presupporre che gli elementi appaiano in un ordine particolare.
## 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 e`MaxResults`, 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](https://docs.aws.amazon.com/ec2/latest/devguide/ec2-api-pagination.html) 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 [https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-securetransport](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-securetransport)globale 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"
}
}
}
]
}
```