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à.
# API HTTP di Gateway API
REST API e API HTTP sono entrambe prodotti dell'API RESTful. Le REST API supportano più funzionalità rispetto alle API HTTP, mentre le API HTTP sono progettate con funzionalità minime in modo che possano essere offerte a un prezzo inferiore. Per ulteriori informazioni, consulta [Scegli tra REST APIs e HTTP APIs](http-api-vs-rest.md).
È possibile utilizzare le API HTTP per inviare richieste alle funzioni AWS Lambda o a qualsiasi endpoint HTTP instradabile. Ad esempio, puoi creare un'API HTTP che si integra con una funzione Lambda sul back-end. Quando un client chiama l'API, API Gateway invia la richiesta alla funzione Lambda e restituisce la risposta della funzione al client.
API HTTP supportano l'autorizzazione [OpenID Connect](https://openid.net/developers/how-connect-works/) e [OAuth 2.0](https://oauth.net/2/). Sono dotate di supporto integrato per CORS (cross-origin resource sharing) e le distribuzioni automatiche.
Puoi creare API HTTP utilizzando la Console di gestione AWS, la AWS CLI, le API, CloudFormation o gli SDK.
**Topics**
+ [Sviluppa HTTP APIs in API Gateway](http-api-develop.md)
+ [Pubblicazione di API HTTP che i clienti possono invocare](http-api-publish.md)
+ [Protezione delle API HTTP in Gateway API](http-api-protect.md)
+ [Monitora HTTP APIs nell'API Gateway](http-api-monitor.md)
+ [Risoluzione dei problemi con le API HTTP in Gateway API](http-api-troubleshooting.md)
# Sviluppa HTTP APIs in API Gateway
Questa sezione fornisce dettagli sulle funzionalità di API Gateway di cui hai bisogno durante lo sviluppo del tuo API Gateway APIs.
Durante lo sviluppo delle API di API Gateway è possibile impostare una serie di caratteristiche dell'API. Queste caratteristiche dipendono dal caso d'uso dell'API. Ad esempio, è possibile consentire a solo a determinati client di richiamare l'API oppure che questa sia disponibile per tutti. È possibile decidere che una chiamata API esegua una funzione Lambda, una query a un database o richiami un'applicazione.
**Topics**
+ [Creazione di un'API HTTP](#http-api-examples)
+ [Crea percorsi per HTTP APIs in API Gateway](http-api-develop-routes.md)
+ [Tipi di indirizzo IP per API HTTP in Gateway API](http-api-ip-address-type.md)
+ [Controlla e gestisci l'accesso a HTTP APIs in API Gateway](http-api-access-control.md)
+ [Creazione delle integrazioni per API HTTP in Gateway API](http-api-develop-integrations.md)
+ [Configurazione di CORS per HTTP APIs in API Gateway](http-api-cors.md)
+ [Trasformazione delle richieste e delle risposte API per API HTTP in Gateway API](http-api-parameter-mapping.md)
+ [Usa le definizioni OpenAPI per HTTP APIs in API Gateway](http-api-open-api.md)
## Creazione di un'API HTTP
Per creare un'API funzionale, è necessario disporre di almeno una route, integrazione, fase e distribuzione.
Gli esempi seguenti mostrano come creare un'API con un'integrazione AWS Lambda o HTTP, una route e una fase predefinita configurata per distribuire automaticamente le modifiche.
In questa guida si presuppone che tu abbia già familiarità con API Gateway e Lambda. Per una guida più dettagliata, consulta [Nozioni di base su Gateway API](getting-started.md).
**Topics**
+ [Crea un'API HTTP utilizzando il Console di gestione AWS](#apigateway-http-api-create.console)
+ [Crea un'API HTTP utilizzando la AWS CLI](#http-api-examples.cli.quick-create)
### Crea un'API HTTP utilizzando il Console di gestione AWS
1. Apri la [console API Gateway](https://console.aws.amazon.com/apigateway).
1. Seleziona **Create API** (Crea API).
1. In **HTTP API**, scegliere **Build (Compila)**.
1. Scegliere **Add integration (Aggiungi integrazione)**, quindi scegliere una funzione AWS Lambda o immettere un endpoint HTTP.
1. Per **Name (Nome)** immetti un nome per il TAG.
1. Scegliere **Review and create (Rivedi e crea)**.
1. Seleziona **Crea**.
Ora la tua API è pronta per effettuare le chiamate. È possibile testare l'API inserendo il relativo URL di chiamata in un browser o utilizzando Curl.
```
curl https://api-id.execute-api.us-east-2.amazonaws.com
```
### Crea un'API HTTP utilizzando la AWS CLI
È possibile utilizzare la creazione rapida per creare un'API con un'integrazione Lambda o HTTP, una route catch-all di default e una fase predefinita configurata per implementare automaticamente le modifiche. Il comando [create-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-api.html) seguente utilizza la funzione di creazione rapida per creare un’API che si integra con una funzione Lambda sul backend.
**Nota**
Per richiamare un'integrazione Lambda, API Gateway deve disporre delle autorizzazioni necessarie. È possibile utilizzare una policy basata sulle risorse o un ruolo IAM per concedere le autorizzazioni di API Gateway per richiamare una funzione Lambda. Per ulteriori informazioni, consulta [AWS Lambda Autorizzazioni nella Guida](https://docs.aws.amazon.com/lambda/latest/dg/lambda-permissions.html) per gli * AWS Lambda sviluppatori*.
**Example**
```
aws apigatewayv2 create-api --name my-api --protocol-type HTTP --target arn:aws:lambda:us-east-2:123456789012:function:function-name
```
Ora la tua API è pronta per effettuare le chiamate. È possibile testare l'API inserendo il relativo URL di chiamata in un browser o utilizzando Curl.
```
curl https://api-id.execute-api.us-east-2.amazonaws.com
```
# Crea percorsi per HTTP APIs in API Gateway
Esegui il routing delle richieste API in entrata dirette alle risorse di back-end. Le route sono costituite da due parti: un metodo HTTP e un percorso delle risorse, ad esempi, `GET /pets`. È possibile definire metodi HTTP specifici per il percorso. In alternativa, è possibile utilizzare il metodo `ANY` per abbinare tutti i metodi non definiti per una risorsa. È possibile creare una route `$default` che funga da catch-all per le richieste che non corrispondono ad altre route.
**Nota**
Gateway Amazon API decodifica i parametri di richiesta con codifica URL prima di passarli all'integrazione back-end.
## Lavorare con le variabili di percorso
Nelle route delle API HTTP è possibile utilizzare delle variabili di percorso.
Ad esempio, il percorso `GET /pets/{petID}` cattura una richiesta `GET` inviata da un client `https://api-id.execute-api.us-east-2.amazonaws.com/pets/6`.
Una *variabile di percorso greedy* cattura tutte le risorse figlio di un percorso. Per creare una variabile di percorso greedy, aggiungere `+` al nome della variale, ad esempio `{proxy+}`. La variabile di percorso greedy deve trovarsi alla fine del percorso della risorsa.
## Utilizzo dei parametri della stringa di query
Per impostazione predefinita, API Gateway invia i parametri della stringa di query all'integrazione back-end se sono inclusi in una richiesta a un oggetto API HTTP.
Ad esempio, quando un client invia una richiesta a `https://api-id.execute-api.us-east-2.amazonaws.com/pets?id=4&type=dog`, i parametri della stringa di query `?id=4&type=dog` vengono inviati all'integrazione.
## Lavorare con il percorso `$default`
Il percorso `$default` cattura le richieste che non corrispondono esplicitamente ad altri percorsi nell'API.
Quando la route `$default` riceve una richiesta, API Gateway invia il percorso completo della richiesta all'integrazione. Ad esempio, è possibile creare un'API con solo un percorso `$default` e integrarlo nel metodo `ANY` con l'endpoint `https://petstore-demo-endpoint.execute-api.com` HTTP. Quando si invia una richiesta a `https://api-id.execute-api.us-east-2.amazonaws.com/store/checkout`, API Gateway invia una richiesta a `https://petstore-demo-endpoint.execute-api.com/store/checkout`.
Per ulteriori informazioni sulle integrazioni HTTP, consultare [Crea integrazioni proxy HTTP per HTTP APIs](http-api-develop-integrations-http.md).
## Routing delle richieste API
Quando un client invia una richiesta API, API Gateway stabilisce innanzitutto a quale [fase](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-stages.html) instradare la richiesta. Se la richiesta corrisponde esplicitamente a una fase, API Gateway invia la richiesta a tale fase. Se nessuna fase corrisponde completamente alla richiesta, API Gateway invia la richiesta alla fase `$default`. Se non è presente alcuna `$default` fase, l'API restituisce `{"message":"Not Found"}` e non genera CloudWatch log.
Dopo aver selezionato una fase, API Gateway seleziona una route. API Gateway seleziona la route con la corrispondenza più specifica, utilizzando le seguenti priorità:
1. Corrispondenza completa per un percorso e un metodo.
1. Corrispondenza per un percorso e un metodo con una variabile di percorso greedy (`{proxy+}`).
1. Instradamento `$default`.
Se nessuna route corrisponde a una richiesta, API Gateway restituisce al client il valore `{"message":"Not Found"}`.
Ad esempio, si consideri un'API con una fase `$default` e le seguenti route di esempio:
1. `GET /pets/dog/1`
1. `GET /pets/dog/{id}`
1. `GET /pets/{proxy+}`
1. `ANY /{proxy+}`
1. `$default`
Nella tabella seguente viene riepilogato il modo in cui API Gateway instrada le richieste alle route di esempio.
| Richiesta | Percorso selezionato | Spiegazione |
| --- | --- | --- |
| `GET https://api-id.execute-api.region.amazonaws.com/pets/dog/1` | `GET /pets/dog/1` | La richiesta corrisponde completamente a questo instradamento statico. |
| `GET https://api-id.execute-api.region.amazonaws.com/pets/dog/2` | `GET /pets/dog/{id}` | La richiesta corrisponde completamente a questo percorso. |
| `GET https://api-id.execute-api.region.amazonaws.com/pets/cat/1` | `GET /pets/{proxy+}` | La richiesta non corrisponde completamente a un percorso. Il percorso con un metodo `GET` e una variabile di percorso greedy cattura questa richiesta. |
| `POST https://api-id.execute-api.region.amazonaws.com/test/5` | `ANY /{proxy+}` | Il metodo `ANY` corrisponde a tutti i metodi che non sono stati definiti per un percorso. I percorsi con variabili di percorso greedy hanno priorità più alta rispetto al percorso `$default`. |
# Tipi di indirizzo IP per API HTTP in Gateway API
Quando si crea un’API, è possibile specificare il tipo di indirizzo IP che può invocarla. È possibile scegliere IPv4 per risolvere gli indirizzi IPv4 per invocare l’API oppure dualstack per consentire a entrambi gli indirizzi IPv4 e IPv6 di invocare l’API. Si potrebbe voler impostare il tipo di indirizzo IP su dualstack per ridurre l’esaurimento dello spazio IP o per il livello di sicurezza. Per ulteriori informazioni sui vantaggi del tipo di indirizzo IP dualstack, consultare [IPv6 on AWS](https://docs.aws.amazon.com/whitepapers/latest/ipv6-on-aws/internet-protocol-version-6.html).
## Considerazioni sui tipi di indirizzo IP
Le seguenti considerazioni potrebbero influire sull’utilizzo dei tipi di indirizzo IP:
+ Il tipo di indirizzo IP predefinito per le API HTTP è IPv4.
+ Se per un’API esistente si modifica il tipo di indirizzo IP da IPv4 a dualstack, è necessario verificare che tutte le policy che controllano l’accesso alle API siano aggiornate in modo da tenere conto delle chiamate IPv6. Quando si modifica il tipo di indirizzo IP, la modifica diventa immediatamente effettiva.
+ L’API può essere mappata su un nome di dominio personalizzato con un tipo di indirizzo IP diverso da quello dell’API. Se si disabilita l’endpoint API predefinito, si potrebbe influire sul modo in cui i chiamanti possono invocare l’API.
## Modifica del tipo di indirizzo IP di un’API HTTP
È possibile modificare il tipo di indirizzo IP aggiornando la configurazione dell’API. È possibile aggiornare la configurazione dell’API utilizzando la Console di gestione AWS, AWS CLI, CloudFormation o un AWS SDK. Se si modifica il tipo di indirizzo IP dell’API, non è necessario eseguire di nuovo l’implementazione dell’API per rendere effettive le modifiche.
------
#### [ Console di gestione AWS ]
**Per modificare il tipo di indirizzo IP di un’API HTTP**
1. Accedere alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Scegliere un'API HTTP.
1. Per **Impostazioni API**, scegliere **Modifica**.
1. Per Tipo di indirizzo IP, selezionare **IPv4** o **Dualstack**.
1. Selezionare **Salva**.
La modifica alla configurazione dell’API ha effetto immediato.
------
#### [ AWS CLI ]
Il comando [update-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-api.html) seguente aggiorna un’API in modo che abbia un tipo di indirizzo IP dualstack:
```
aws apigatewayv2 update-api \
--api-id abcd1234 \
--ip-address-type dualstack
```
L'output sarà simile al seguente:
```
{
"ApiEndpoint": "https://abcd1234.execute-api.us-east-1.amazonaws.com",
"ApiId": "abcd1234",
"ApiKeySelectionExpression": "$request.header.x-api-key",
"CreatedDate": "2025-02-04T22:20:20+00:00",
"DisableExecuteApiEndpoint": false,
"Name": "My-HTTP-API",
"ProtocolType": "HTTP",
"RouteSelectionExpression": "$request.method $request.path",
"Tags": {},
"NotificationUris": [],
"IpAddressType": "dualstack"
}
```
------
# Controlla e gestisci l'accesso a HTTP APIs in API Gateway
API Gateway supporta più meccanismi per controllare e gestire l'accesso a un'API HTTP:
+ Gli **autorizzatori Lambda utilizzano** le funzioni Lambda per controllare l'accesso a. APIs Per ulteriori informazioni, consulta [Controlla l'accesso a HTTP APIs con gli AWS Lambda autorizzatori](http-api-lambda-authorizer.md).
+ **Gli autorizzatori JWT utilizzano token** web JSON per controllare l'accesso a. APIs Per ulteriori informazioni, consulta [Controlla l'accesso a HTTP APIs con gli autorizzatori JWT in API Gateway](http-api-jwt-authorizer.md).
+ **I ruoli e le politiche AWS IAM standard offrono controlli di** accesso flessibili e robusti. Puoi utilizzare i ruoli e le policy IAM per controllare chi può creare e gestire APIs le tue e chi può richiamarle. Per ulteriori informazioni, consulta [Controlla l'accesso a HTTP APIs con l'autorizzazione IAM in API Gateway](http-api-access-control-iam.md).
Per migliorare il livello di sicurezza, è consigliabile configurare un sistema di autorizzazioni per tutti gli instradamenti per l’API HTTP. Potrebbe essere necessario eseguire questa operazione per rispettare vari framework di conformità. Per ulteriori informazioni, consultare [Amazon API Gateway controls](https://docs.aws.amazon.com/securityhub/latest/userguide/apigateway-controls.html) nella *Guida per l’utente di AWS Security Hub *.
# Controlla l'accesso a HTTP APIs con gli AWS Lambda autorizzatori
Si sfrutta un'autorizzazione Lambda al fine di utilizzare una funzione Lambda per controllare l'accesso all'API HTTP. Quindi, quando un client invoca un'API, API Gateway richiama la funzione Lambda. API Gateway utilizza la risposta dalla funzione Lambda per determinare se il client può accedere all'API.
## Tipo di formato payload
Il tipo di formato del payload dell'autorizzazione specifica il formato dei dati che API Gateway invia a un'autorizzazione Lambda e il modo in cui API Gateway interpreta la risposta ricevuta da Lambda. Se non specifichi una versione del formato di payload, Console di gestione AWS utilizza la versione più recente per impostazione predefinita. Se crei un autorizzatore Lambda utilizzando AWS CLI, o un SDK CloudFormation, devi specificare un. `authorizerPayloadFormatVersion` I valori supportati sono `1.0` e `2.0`.
Se hai bisogno di compatibilità con REST APIs, usa la versione. `1.0`
Gli esempi seguenti mostrano la struttura di ogni tipo di formato payload.
------
#### [ 2.0 ]
```
{
"version": "2.0",
"type": "REQUEST",
"routeArn": "arn:aws:execute-api:us-east-1:123456789012:abcdef123/test/GET/request",
"identitySource": ["user1", "123"],
"routeKey": "$default",
"rawPath": "/my/path",
"rawQueryString": "parameter1=value1¶meter1=value2¶meter2=value",
"cookies": ["cookie1", "cookie2"],
"headers": {
"header1": "value1",
"header2": "value2"
},
"queryStringParameters": {
"parameter1": "value1,value2",
"parameter2": "value"
},
"requestContext": {
"accountId": "123456789012",
"apiId": "api-id",
"authentication": {
"clientCert": {
"clientCertPem": "CERT_CONTENT",
"subjectDN": "www.example.com",
"issuerDN": "Example issuer",
"serialNumber": "1",
"validity": {
"notBefore": "May 28 12:30:02 2019 GMT",
"notAfter": "Aug 5 09:36:04 2021 GMT"
}
}
},
"domainName": "id.execute-api.us-east-1.amazonaws.com",
"domainPrefix": "id",
"http": {
"method": "POST",
"path": "/my/path",
"protocol": "HTTP/1.1",
"sourceIp": "IP",
"userAgent": "agent"
},
"requestId": "id",
"routeKey": "$default",
"stage": "$default",
"time": "12/Mar/2020:19:03:58 +0000",
"timeEpoch": 1583348638390
},
"pathParameters": { "parameter1": "value1" },
"stageVariables": { "stageVariable1": "value1", "stageVariable2": "value2" }
}
```
------
#### [ 1.0 ]
```
{
"version": "1.0",
"type": "REQUEST",
"methodArn": "arn:aws:execute-api:us-east-1:123456789012:abcdef123/test/GET/request",
"identitySource": "user1,123",
"authorizationToken": "user1,123",
"resource": "/request",
"path": "/request",
"httpMethod": "GET",
"headers": {
"X-AMZ-Date": "20170718T062915Z",
"Accept": "*/*",
"HeaderAuth1": "headerValue1",
"CloudFront-Viewer-Country": "US",
"CloudFront-Forwarded-Proto": "https",
"CloudFront-Is-Tablet-Viewer": "false",
"CloudFront-Is-Mobile-Viewer": "false",
"User-Agent": "..."
},
"queryStringParameters": {
"QueryString1": "queryValue1"
},
"pathParameters": {},
"stageVariables": {
"StageVar1": "stageValue1"
},
"requestContext": {
"path": "/request",
"accountId": "123456789012",
"resourceId": "05c7jb",
"stage": "test",
"requestId": "...",
"identity": {
"apiKey": "...",
"sourceIp": "...",
"clientCert": {
"clientCertPem": "CERT_CONTENT",
"subjectDN": "www.example.com",
"issuerDN": "Example issuer",
"serialNumber": "a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1",
"validity": {
"notBefore": "May 28 12:30:02 2019 GMT",
"notAfter": "Aug 5 09:36:04 2021 GMT"
}
}
},
"resourcePath": "/request",
"httpMethod": "GET",
"apiId": "abcdef123"
}
}
```
------
## Formato della risposta dell'autorizzazione
Il tipo di formato del payload determina anche la struttura della risposta che deve essere restituita dalla funzione Lambda.
### Risposta della funzione Lambda per il formato 1.0
Se si sceglie il tipo di formato `1.0`, le autorizzazioni Lambda devono restituire una policy IAM che consenta o rifiuti l'accesso alla route dell'API. Nella policy è possibile utilizzare la sintassi standard delle policy IAM. Per alcuni esempi di policy IAM, consultare [Controllo degli accessi per invocare un'API](api-gateway-control-access-using-iam-policies-to-invoke-api.md). È possibile passare le proprietà del contesto alle integrazioni Lambda o ai log di accesso utilizzando `$context.authorizer.property`. L'oggetto `context` è facoltativo e `claims` è un segnaposto riservato che non può essere utilizzato come oggetto contesto. Per ulteriori informazioni, consulta [Personalizzazione dei log degli accessi delle API HTTP](http-api-logging-variables.md).
**Example**
****
```
{
"principalId": "abcdef",
"policyDocument": {
"Version":"2012-10-17",
"Statement": [
{
"Action": "execute-api:Invoke",
"Effect": "Allow|Deny",
"Resource": "arn:aws:execute-api:{regionId}:{accountId}:{apiId}/{stage}/{httpVerb}/[{resource}/[{child-resources}]]"
}
]
},
"context": {
"exampleKey": "exampleValue"
}
}
```
### Risposta della funzione Lambda per il formato 2.0
Se si sceglie il tipo di formato `2.0`, dalla funzione Lambda è possibile restituire un valore booleano o una policy IAM che utilizza la sintassi standard della policy di IAM. Per restituire un valore booleano, abilitare risposte semplici per l'autorizzazione. Negli esempi seguenti viene illustrato il formato in cui è necessario codificare il risultato restituito dalla funzione Lambda. L'oggetto `context` è facoltativo. È possibile passare le proprietà del contesto alle integrazioni Lambda o ai log di accesso utilizzando `$context.authorizer.property`. Per ulteriori informazioni, consulta [Personalizzazione dei log degli accessi delle API HTTP](http-api-logging-variables.md).
------
#### [ Simple response ]
```
{
"isAuthorized": true/false,
"context": {
"exampleKey": "exampleValue"
}
}
```
------
#### [ IAM policy ]
****
```
{
"principalId": "abcdef",
"policyDocument": {
"Version":"2012-10-17",
"Statement": [
{
"Action": "execute-api:Invoke",
"Effect": "Allow|Deny",
"Resource": "arn:aws:execute-api:{regionId}:{accountId}:{apiId}/{stage}/{httpVerb}/[{resource}/[{child-resources}]]"
}
]
},
"context": {
"exampleKey": "exampleValue"
}
}
```
------
## Esempio di funzioni di autorizzazione Lambda
Le seguenti funzioni Lambda Node.js di esempio illustrano i formati di risposta richiesti che è necessario restituire dalla funzione Lambda per il tipo di formato del payload `2.0`.
------
#### [ Simple response - Node.js ]
```
export const handler = async(event) => {
let response = {
"isAuthorized": false,
"context": {
"stringKey": "value",
"numberKey": 1,
"booleanKey": true,
"arrayKey": ["value1", "value2"],
"mapKey": {"value1": "value2"}
}
};
if (event.headers.authorization === "secretToken") {
console.log("allowed");
response = {
"isAuthorized": true,
"context": {
"stringKey": "value",
"numberKey": 1,
"booleanKey": true,
"arrayKey": ["value1", "value2"],
"mapKey": {"value1": "value2"}
}
};
}
return response;
};
```
------
#### [ Simple response - Python ]
```
import json
def lambda_handler(event, context):
response = {
"isAuthorized": False,
"context": {
"stringKey": "value",
"numberKey": 1,
"booleanKey": True,
"arrayKey": ["value1", "value2"],
"mapKey": {"value1": "value2"}
}
}
try:
if (event["headers"]["authorization"] == "secretToken"):
response = {
"isAuthorized": True,
"context": {
"stringKey": "value",
"numberKey": 1,
"booleanKey": True,
"arrayKey": ["value1", "value2"],
"mapKey": {"value1": "value2"}
}
}
print('allowed')
return response
else:
print('denied')
return response
except BaseException:
print('denied')
return response
```
------
#### [ IAM policy - Node.js ]
```
export const handler = async(event) => {
if (event.headers.authorization == "secretToken") {
console.log("allowed");
return {
"principalId": "abcdef", // The principal user identification associated with the token sent by the client.
"policyDocument": {
"Version": "2012-10-17",
"Statement": [{
"Action": "execute-api:Invoke",
"Effect": "Allow",
"Resource": event.routeArn
}]
},
"context": {
"stringKey": "value",
"numberKey": 1,
"booleanKey": true,
"arrayKey": ["value1", "value2"],
"mapKey": { "value1": "value2" }
}
};
}
else {
console.log("denied");
return {
"principalId": "abcdef", // The principal user identification associated with the token sent by the client.
"policyDocument": {
"Version": "2012-10-17",
"Statement": [{
"Action": "execute-api:Invoke",
"Effect": "Deny",
"Resource": event.routeArn
}]
},
"context": {
"stringKey": "value",
"numberKey": 1,
"booleanKey": true,
"arrayKey": ["value1", "value2"],
"mapKey": { "value1": "value2" }
}
};
}
};
```
------
#### [ IAM policy - Python ]
```
import json
def lambda_handler(event, context):
response = {
# The principal user identification associated with the token sent by
# the client.
"principalId": "abcdef",
"policyDocument": {
"Version": "2012-10-17",
"Statement": [{
"Action": "execute-api:Invoke",
"Effect": "Deny",
"Resource": event["routeArn"]
}]
},
"context": {
"stringKey": "value",
"numberKey": 1,
"booleanKey": True,
"arrayKey": ["value1", "value2"],
"mapKey": {"value1": "value2"}
}
}
try:
if (event["headers"]["authorization"] == "secretToken"):
response = {
# The principal user identification associated with the token
# sent by the client.
"principalId": "abcdef",
"policyDocument": {
"Version": "2012-10-17",
"Statement": [{
"Action": "execute-api:Invoke",
"Effect": "Allow",
"Resource": event["routeArn"]
}]
},
"context": {
"stringKey": "value",
"numberKey": 1,
"booleanKey": True,
"arrayKey": ["value1", "value2"],
"mapKey": {"value1": "value2"}
}
}
print('allowed')
return response
else:
print('denied')
return response
except BaseException:
print('denied')
return response
```
------
## Origini di identità
È facoltativamente possibile specificare le origini di identità per un'autorizzazione Lambda. Le origini di identità specificano la posizione dei dati necessari per autorizzare una richiesta. Ad esempio, è possibile specificare i valori di intestazione o di stringa di query come origini di identità. Se si specificano le origini di identità, i client devono includerle nella richiesta. Se la richiesta del client non include le origini di identità, API Gateway non richiama l'autorizzazione Lambda e il client riceve un errore `401`.
La tabella seguente illustra le origini di identità supportate per un sistema di autorizzazione Lambda.
| **Tipo** | **Esempio** | **Note** |
| --- | --- | --- |
| Valore intestazione | \$1request.header. name | I nomi delle intestazioni non fanno distinzione tra maiuscole e minuscole. |
| Valore della stringa di query | \$1request.querystring. name | I nomi delle stringhe di query fanno distinzione tra maiuscole e minuscole. |
| Variabile di contesto | \$1contesto. variableName | Valore di una [variabile di contesto](http-api-logging-variables.md) supportata. |
| Variabile di fase | \$1stageVariabili. variableName | Il valore di una [variabile di fase](http-api-stages.stage-variables.md). |
È anche possibile ottenere direttamente ` {"errorMessage" : "Unauthorized"}` dalla funzione Lambda per restituire un errore `401` ai client. Se si restituisce direttamente ai client un errore `401` della funzione Lambda, non specificare alcuna origine di identità quando si crea il sistema di autorizzazione Lambda.
## Caching delle risposte delle autorizzazioni
Puoi abilitare la memorizzazione nella cache per un autorizzatore Lambda specificando un. [authorizerResultTtlInSeconds](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-authorizers.html#apis-apiid-authorizers-prop-createauthorizerinput-authorizerresultttlinseconds) Quando il caching è abilitato per un'autorizzazione, API Gateway utilizza le origini di identità dell'autorizzazione come chiave della cache. Se un client specifica gli stessi parametri nelle origini di identità all'interno del TTL configurato, API Gateway utilizza il risultato dell'autorizzazione memorizzato nella cache, anziché richiamare la funzione Lambda.
Per abilitare il caching, l'autorizzazione deve disporre di almeno un'origine di identità.
Se si abilitano risposte semplici per un'autorizzazione, la risposta dell'autorizzazione consente o rifiuta completamente tutte le richieste API che corrispondono ai valori dell'origine di identità memorizzata nella cache. Per autorizzazioni più granulari, disabilitare le risposte semplici e restituire una policy IAM. A seconda del sistema di autorizzazione, la policy IAM potrebbe dover controllare l’accesso a più utenti.
Per impostazione predefinita, API Gateway utilizza la risposta dell'autorizzazione memorizzata nella cache per tutte le route dell'API che utilizzano l'autorizzazione. Per inserire nella cache le risposte per l'instradamento, aggiungere `$context.routeKey` alle origini di identità dell'autorizzazione.
## Creare un'autorizzazione Lambda
Quando si crea un'autorizzazione Lambda, si specifica la funzione Lambda che API Gateway deve utilizzare. È necessario concedere ad API Gateway l'autorizzazione per richiamare la funzione Lambda utilizzando la policy basata su risorse della funzione o un ruolo IAM. Il comando [create-authorizer](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-authorizer.html) seguente crea un sistema di autorizzazione Lambda:
```
aws apigatewayv2 create-authorizer \
--api-id abcdef123 \
--authorizer-type REQUEST \
--identity-source '$request.header.Authorization' \
--name lambda-authorizer \
--authorizer-uri 'arn:aws:apigateway:us-west-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-west-2:123456789012:function:my-function/invocations' \
--authorizer-payload-format-version '2.0' \
--enable-simple-responses
```
Il comando [add-permission](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html) seguente aggiorna la policy di risorse della funzione Lambda per fornire a Gateway API l’autorizzazione per invocare la funzione. Se l'API Gateway non dispone dell'autorizzazione a richiamare la funzione, i client ricevono un errore `500 Internal Server Error`.
```
aws lambda add-permission \
--function-name my-authorizer-function \
--statement-id apigateway-invoke-permissions-abc123 \
--action lambda:InvokeFunction \
--principal apigateway.amazonaws.com \
--source-arn "arn:aws:execute-api:us-west-2:123456789012:api-id/authorizers/authorizer-id"
```
Dopo aver creato un'autorizzazione e concesso ad API Gateway l'autorizzazione per richiamarla, aggiornare la route affinché utilizzi l'autorizzazione. Il comando [update-route](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-route.html) seguente aggiunge il sistema di autorizzazione Lambda all’instradamento. Se il sistema di autorizzazione Lambda utilizza il caching delle policy, è necessario aggiornare la policy per controllare l’accesso all’instradamento aggiuntivo.
```
aws apigatewayv2 update-route \
--api-id abcdef123 \
--route-id abc123 \
--authorization-type CUSTOM \
--authorizer-id def123
```
## Risoluzione dei problemi relativi alle autorizzazioni Lambda
Se l'API Gateway non è in grado di richiamare l'autorizzazione Lambda o l'autorizzazione Lambda restituisce una risposta in un formato non valido, i client ricevono una risposta `500 Internal Server Error`.
Per risolvere gli errori, [abilitare la registrazione degli accessi](http-api-logging.md) per la fase dell'API. Includere la variabile di registrazione `$context.authorizer.error` nel formato di log.
Se i log indicano che API Gateway non dispone dell'autorizzazione per richiamare la funzione, aggiornare la policy basata su risorse della funzione o fornire un ruolo IAM per concedere ad API Gateway il permesso di per richiamare l'autorizzazione.
Se i log indicano che la funzione Lambda restituisce una risposta non valida, verificare che la funzione Lambda restituisca una risposta nel [formato richiesto](#http-api-lambda-authorizer.payload-format-response).
# Controlla l'accesso a HTTP APIs con gli autorizzatori JWT in API Gateway
Puoi utilizzare JSON Web Tokens (JWTs) come parte dei framework OpenID [Connect (OIDC)](https://openid.net/specs/openid-connect-core-1_0.html) e [OAuth 2.0](https://oauth.net/2/) per limitare l'accesso dei client al tuo. APIs
Se configuri un autorizzatore JWT per un instradamento della tua API, API Gateway convalida le richieste API JWTs inviate dai client. API Gateway consente o nega le richieste in base alla convalida dei token e, facoltativamente, gli ambiti nel token. Se si configurano gli ambiti per un percorso, il token deve includere almeno uno degli ambiti del percorso.
È possibile configurare autorizzazioni distinte per ogni percorso di un'API o utilizzare lo stesso autorizzatore per più route.
**Nota**
Non esiste un meccanismo standard per differenziare i token di accesso JWT da altri tipi di token JWTs, come i token ID OpenID Connect. A meno che non si richiedano token ID per l'autorizzazione API, si consiglia di configurare le route per richiedere gli ambiti di autorizzazione. È inoltre possibile configurare gli autorizzatori JWT per richiedere emittenti o gruppi di destinatari che il provider di identità utilizza solo quando si emettono token di accesso JWT.
## Autorizzazione delle richieste API con un provider di autorizzazioni JWT
API Gateway utilizza il seguente flusso di lavoro generale per autorizzare le richieste alle route configurate per l'utilizzo di un'autorizzazione JWT.
1. Controllare la presenza di [https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-authorizers-authorizerid.html#apis-apiid-authorizers-authorizerid-prop-authorizer-identitysource](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-authorizers-authorizerid.html#apis-apiid-authorizers-authorizerid-prop-authorizer-identitysource) per un token. Il `identitySource` può includere solo il token o il token con il prefisso `Bearer`.
1. Decodifica del token.
1. Controlla l'algoritmo e la firma del token utilizzando la chiave pubblica recuperata dal dell'emittent `jwks_uri`. Attualmente sono supportati solo gli algoritmi basati su RSA. Gateway Amazon API può memorizzare la chiave pubblica nella cache per due ore. Come best practice, quando si esegue la rotazione delle chiavi, definire un periodo di tolleranza durante il quale sia la vecchia che la nuova chiave sono valide.
1. Convalida delle richieste. API Gateway valuta le seguenti richieste dei token:
+ [https://datatracker.ietf.org/doc/html/rfc7517#section-4.5](https://datatracker.ietf.org/doc/html/rfc7517#section-4.5): il token deve presentare una richiesta di intestazione che corrisponde alla chiave nel `jwks_uri` che ha firmato il token.
+ [https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.1](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.1): deve corrispondere all'[https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-authorizers-authorizerid.html#apis-apiid-authorizers-authorizerid-model-jwtconfiguration](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-authorizers-authorizerid.html#apis-apiid-authorizers-authorizerid-model-jwtconfiguration) configurato per l'autorizzazione.
+ [https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.3](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.3) o `client_id`: devono corrispondere a una delle voci [https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-authorizers-authorizerid.html#apis-apiid-authorizers-authorizerid-model-jwtconfiguration](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-authorizers-authorizerid.html#apis-apiid-authorizers-authorizerid-model-jwtconfiguration) configurate per l'autorizzazione. Gateway API convalida `client_id` solo se `aud` non è presente. Quando `aud` e `client_id` sono entrambi presenti, Gateway API valuta `aud`.
+ [https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.4](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.4) – deve essere successivo all'ora corrente in UTC.
+ [https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.5](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.5) – deve essere precedente all'ora corrente in UTC.
+ [https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.6](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.6) – deve essere precedente all'ora corrente in UTC.
+ [https://datatracker.ietf.org/doc/html/rfc6749#section-3.3](https://datatracker.ietf.org/doc/html/rfc6749#section-3.3) o `scp`: il token deve includere almeno uno degli ambiti negli [https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-routes-routeid.html#apis-apiid-routes-routeid-prop-updaterouteinput-authorizationscopes](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-routes-routeid.html#apis-apiid-routes-routeid-prop-updaterouteinput-authorizationscopes) della route.
Se uno di questi passaggi non riesce, API Gateway nega la richiesta API.
Dopo aver convalidato il JWT, API Gateway passa le registrazioni nel token all'integrazione della route API. Le risorse di back-end, come le funzioni Lambda, possono accedere alle attestazioni JWT. Ad esempio, se JWT include un'attestazione di identità `emailID`, è disponibile per un'integrazione Lambda in `$event.requestContext.authorizer.jwt.claims.emailID`. Per ulteriori informazioni sul payload che API Gateway invia alle integrazioni Lambda, consulta [Crea integrazioni AWS Lambda proxy per HTTP APIs in API Gateway](http-api-develop-integrations-lambda.md).
## Creazione di un'autorizzazione JWT
Prima di creare un autorizzatore JWT, è necessario registrare un'applicazione client con un provider di identità. È anche necessario aver creato un'API HTTP. Per esempi di creazione di un'API HTTP, consultare [Creazione di un'API HTTP](http-api-develop.md#http-api-examples).
### Creazione di un provider di autorizzazioni JWT tramite la console
Nei seguenti passaggi viene illustrato come creare un provider di autorizzazioni JWT utilizzando la console.
**Per creare un provider di autorizzazioni JWT tramite la console**
1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Scegliere un'API HTTP.
1. Nel pannello di navigazione principale, scegli **Autorizzazione**.
1. Seleziona la scheda **Gestisci provider di autorizzazioni**.
1. Scegli **Create** (Crea).
1. Per **Tipo di autorizzazione** scegli **JWT**.
1. Configurare il provider di autorizzazioni JWT e specificare una **Origine identità** che definisca l'origine del token.
1. Scegli **Create** (Crea).
#### Crea un autorizzatore JWT utilizzando il AWS CLI
Il comando [create-authorizer](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-authorizer.html) seguente crea un’autorizzazione JWT. Per `jwt-configuration`, specificare `Audience` e `Issuer` per il provider di identità. Se si utilizza Amazon Cognito come provider di identità, `IssuerUrl` è `https://cognito-idp.us-east-2.amazonaws.com/userPoolID`.
```
aws apigatewayv2 create-authorizer \
--name authorizer-name \
--api-id api-id \
--authorizer-type JWT \
--identity-source '$request.header.Authorization' \
--jwt-configuration Audience=audience,Issuer=IssuerUrl
```
##### Crea un autorizzatore JWT utilizzando AWS CloudFormation
Il CloudFormation modello seguente crea un'API HTTP con un autorizzatore JWT che utilizza Amazon Cognito come provider di identità.
L'output del CloudFormation modello è un URL per un'interfaccia utente ospitata da Amazon Cognito in cui i clienti possono registrarsi e accedere per ricevere un JWT. Dopo l'accesso, il client viene reindirizzato all'API HTTP con un token di accesso nell'URL. Per invocare l'API con il token di accesso, modifica `#` nell'URL in `?` per utilizzare il token come parametro della stringa di query.
##### Modello di esempio CloudFormation
```
AWSTemplateFormatVersion: '2010-09-09'
Description: |
Example HTTP API with a JWT authorizer. This template includes an Amazon Cognito user pool as the issuer for the JWT authorizer
and an Amazon Cognito app client as the audience for the authorizer. The outputs include a URL for an Amazon Cognito hosted UI where clients can
sign up and sign in to receive a JWT. After a client signs in, the client is redirected to your HTTP API with an access token
in the URL. To invoke the API with the access token, change the '#' in the URL to a '?' to use the token as a query string parameter.
Resources:
MyAPI:
Type: AWS::ApiGatewayV2::Api
Properties:
Description: Example HTTP API
Name: api-with-auth
ProtocolType: HTTP
Target: !GetAtt MyLambdaFunction.Arn
DefaultRouteOverrides:
Type: AWS::ApiGatewayV2::ApiGatewayManagedOverrides
Properties:
ApiId: !Ref MyAPI
Route:
AuthorizationType: JWT
AuthorizerId: !Ref JWTAuthorizer
JWTAuthorizer:
Type: AWS::ApiGatewayV2::Authorizer
Properties:
ApiId: !Ref MyAPI
AuthorizerType: JWT
IdentitySource:
- '$request.querystring.access_token'
JwtConfiguration:
Audience:
- !Ref AppClient
Issuer: !Sub https://cognito-idp.${AWS::Region}.amazonaws.com/${UserPool}
Name: test-jwt-authorizer
MyLambdaFunction:
Type: AWS::Lambda::Function
Properties:
Runtime: nodejs18.x
Role: !GetAtt FunctionExecutionRole.Arn
Handler: index.handler
Code:
ZipFile: |
exports.handler = async (event) => {
const response = {
statusCode: 200,
body: JSON.stringify('Hello from the ' + event.routeKey + ' route!'),
};
return response;
};
APIInvokeLambdaPermission:
Type: AWS::Lambda::Permission
Properties:
FunctionName: !Ref MyLambdaFunction
Action: lambda:InvokeFunction
Principal: apigateway.amazonaws.com
SourceArn: !Sub arn:${AWS::Partition}:execute-api:${AWS::Region}:${AWS::AccountId}:${MyAPI}/$default/$default
FunctionExecutionRole:
Type: AWS::IAM::Role
Properties:
AssumeRolePolicyDocument:
Version: '2012-10-17 '
Statement:
- Effect: Allow
Principal:
Service:
- lambda.amazonaws.com
Action:
- 'sts:AssumeRole'
ManagedPolicyArns:
- arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole
UserPool:
Type: AWS::Cognito::UserPool
Properties:
UserPoolName: http-api-user-pool
AutoVerifiedAttributes:
- email
Schema:
- Name: name
AttributeDataType: String
Mutable: true
Required: true
- Name: email
AttributeDataType: String
Mutable: false
Required: true
AppClient:
Type: AWS::Cognito::UserPoolClient
Properties:
AllowedOAuthFlows:
- implicit
AllowedOAuthScopes:
- aws.cognito.signin.user.admin
- email
- openid
- profile
AllowedOAuthFlowsUserPoolClient: true
ClientName: api-app-client
CallbackURLs:
- !Sub https://${MyAPI}.execute-api.${AWS::Region}.amazonaws.com
ExplicitAuthFlows:
- ALLOW_USER_PASSWORD_AUTH
- ALLOW_REFRESH_TOKEN_AUTH
UserPoolId: !Ref UserPool
SupportedIdentityProviders:
- COGNITO
HostedUI:
Type: AWS::Cognito::UserPoolDomain
Properties:
Domain: !Join
- '-'
- - !Ref MyAPI
- !Ref AppClient
UserPoolId: !Ref UserPool
Outputs:
SignupURL:
Value: !Sub https://${HostedUI}.auth.${AWS::Region}.amazoncognito.com/login?client_id=${AppClient}&response_type=token&scope=email+profile&redirect_uri=https://${MyAPI}.execute-api.${AWS::Region}.amazonaws.com
```
## Aggiornamento di un instradamento per utilizzare un provider di autorizzazioni JWT
Puoi utilizzare la console AWS CLI, o un AWS SDK per aggiornare un percorso in modo da utilizzare un autorizzatore JWT.
### Aggiornamento di un instradamento per utilizzare un provider di autorizzazioni JWT tramite la console
Nei seguenti passaggi viene illustrato come aggiornare un instradamento per utilizzare un provider di autorizzazioni JWT utilizzando la console.
**Per creare un provider di autorizzazioni JWT tramite la console**
1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Scegliere un'API HTTP.
1. Nel pannello di navigazione principale, scegli **Autorizzazione**.
1. Scegli un metodo, quindi seleziona il provider di autorizzazioni dal menu a discesa e scegli **Collega provider di autorizzazioni**.
#### Aggiorna un percorso per utilizzare un autorizzatore JWT utilizzando il AWS CLI
Il comando [update-route](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-route.html) seguente aggiorna un instradamento per utilizzare un provider di autorizzazioni JWT:
```
aws apigatewayv2 update-route \
--api-id api-id \
--route-id route-id \
--authorization-type JWT \
--authorizer-id authorizer-id \
--authorization-scopes user.email
```
# Controlla l'accesso a HTTP APIs con l'autorizzazione IAM in API Gateway
È possibile abilitare l'autorizzazione IAM per route di API HTTP. Quando l'autorizzazione IAM è abilitata, i client devono utilizzare [Signature Version 4 (SigV4)](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html) per firmare le loro richieste con AWS le credenziali. API Gateway richiama la route API solo se il client dispone dell'autorizzazione `execute-api` per la route.
[L'autorizzazione IAM per HTTP APIs è simile a quella per REST. APIs](api-gateway-control-access-using-iam-policies-to-invoke-api.md)
**Nota**
Le politiche relative alle risorse non sono attualmente supportate per HTTP APIs.
Per esempi di politiche IAM che concedono ai client il permesso di invocazione APIs, consulta[Controllo degli accessi per invocare un'API](api-gateway-control-access-using-iam-policies-to-invoke-api.md).
## Abilitazione dell'autorizzazione IAM per una route
Il comando [update-route](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-route.html) seguente abilita l’autorizzazione IAM per un instradamento di un’API HTTP:
```
aws apigatewayv2 update-route \
--api-id abc123 \
--route-id abcdef \
--authorization-type AWS_IAM
```
# Creazione delle integrazioni per API HTTP in Gateway API
Le *integrazioni* collegano una route alle risorse di back-end. Le API HTTP supportano proxy Lambda, il servizio AWS e le integrazioni proxy HTTP. Ad esempio, è possibile configurare una richiesta `POST` per la route `/signup` dell'API per l'integrazione con una funzione Lambda che gestisce la registrazione dei clienti.
**Topics**
+ [Crea integrazioni AWS Lambda proxy per HTTP APIs in API Gateway](http-api-develop-integrations-lambda.md)
+ [Crea integrazioni proxy HTTP per HTTP APIs](http-api-develop-integrations-http.md)
+ [Crea integrazioni AWS di servizi per HTTP APIs in API Gateway](http-api-develop-integrations-aws-services.md)
+ [Crea integrazioni private per HTTP APIs in API Gateway](http-api-develop-integrations-private.md)
# Crea integrazioni AWS Lambda proxy per HTTP APIs in API Gateway
Un'integrazione proxy Lambda consente di integrare una route API con una funzione Lambda. Quando un client chiama l'API, API Gateway invia la richiesta alla funzione Lambda e restituisce la risposta della funzione al client. Per esempi di creazione di un'API HTTP, consultare [Creazione di un'API HTTP](http-api-develop.md#http-api-examples).
## Tipo di formato payload
La versione del formato del payload specifica il formato dell'evento che Gateway API invia a un'integrazione Lambda e il modo in cui Gateway API interpreta la risposta ricevuta da Lambda. Se non specifichi una versione del formato di payload, Console di gestione AWS utilizza la versione più recente per impostazione predefinita. Se crei un'integrazione Lambda utilizzando AWS CLI CloudFormation, o un SDK, devi specificare un. `payloadFormatVersion` I valori supportati sono `1.0` e `2.0`.
Per ulteriori informazioni su come impostare `payloadFormatVersion`, consulta [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html). Per ulteriori informazioni su come determinare l'entità `payloadFormatVersion` di un'integrazione esistente, consulta [get-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/get-integration.html).
### Differenze di formato del payload
L'elenco seguente mostra le differenze tra le versioni del formato del payload `1.0` e `2.0`:
+ Il formato `2.0` non contiene i campi `multiValueHeaders` o `multiValueQueryStringParameters`. Le intestazioni duplicate sono combinate con virgole e incluse nel campo `headers`. Le stringhe di query duplicate sono combinate con virgole e incluse nel campo `queryStringParameters`.
+ Il formato `2.0` include `rawPath`. Se si utilizza una mappatura API per collegare la fase a un nome di dominio personalizzato, `rawPath` non fornirà il valore di mappatura API. Utilizza il formato `1.0` e `path` per accedere alla mappatura API per il nome di dominio personalizzato.
+ Il formato `2.0` include un nuovo campo `cookies`. Tutte le intestazioni dei cookie nella richiesta vengono combinate con virgole e aggiunte al campo `cookies`. Nella risposta al client, ogni cookie diventa un'intestazione `set-cookie`.
### Struttura del formato del payload
Gli esempi seguenti mostrano la struttura di ogni tipo di formato payload. Per tutti i nomi delle intestazioni si utilizzano le minuscole.
------
#### [ 2.0 ]
```
{
"version": "2.0",
"routeKey": "$default",
"rawPath": "/my/path",
"rawQueryString": "parameter1=value1¶meter1=value2¶meter2=value",
"cookies": [
"cookie1",
"cookie2"
],
"headers": {
"header1": "value1",
"header2": "value1,value2"
},
"queryStringParameters": {
"parameter1": "value1,value2",
"parameter2": "value"
},
"requestContext": {
"accountId": "123456789012",
"apiId": "api-id",
"authentication": {
"clientCert": {
"clientCertPem": "CERT_CONTENT",
"subjectDN": "www.example.com",
"issuerDN": "Example issuer",
"serialNumber": "a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1",
"validity": {
"notBefore": "May 28 12:30:02 2019 GMT",
"notAfter": "Aug 5 09:36:04 2021 GMT"
}
}
},
"authorizer": {
"jwt": {
"claims": {
"claim1": "value1",
"claim2": "value2"
},
"scopes": [
"scope1",
"scope2"
]
}
},
"domainName": "id.execute-api.us-east-1.amazonaws.com",
"domainPrefix": "id",
"http": {
"method": "POST",
"path": "/my/path",
"protocol": "HTTP/1.1",
"sourceIp": "192.0.2.1",
"userAgent": "agent"
},
"requestId": "id",
"routeKey": "$default",
"stage": "$default",
"time": "12/Mar/2020:19:03:58 +0000",
"timeEpoch": 1583348638390
},
"body": "Hello from Lambda",
"pathParameters": {
"parameter1": "value1"
},
"isBase64Encoded": false,
"stageVariables": {
"stageVariable1": "value1",
"stageVariable2": "value2"
}
}
```
------
#### [ 1.0 ]
```
{
"version": "1.0",
"resource": "/my/path",
"path": "/my/path",
"httpMethod": "GET",
"headers": {
"header1": "value1",
"header2": "value2"
},
"multiValueHeaders": {
"header1": [
"value1"
],
"header2": [
"value1",
"value2"
]
},
"queryStringParameters": {
"parameter1": "value1",
"parameter2": "value"
},
"multiValueQueryStringParameters": {
"parameter1": [
"value1",
"value2"
],
"parameter2": [
"value"
]
},
"requestContext": {
"accountId": "123456789012",
"apiId": "id",
"authorizer": {
"claims": null,
"scopes": null
},
"domainName": "id.execute-api.us-east-1.amazonaws.com",
"domainPrefix": "id",
"extendedRequestId": "request-id",
"httpMethod": "GET",
"identity": {
"accessKey": null,
"accountId": null,
"caller": null,
"cognitoAuthenticationProvider": null,
"cognitoAuthenticationType": null,
"cognitoIdentityId": null,
"cognitoIdentityPoolId": null,
"principalOrgId": null,
"sourceIp": "192.0.2.1",
"user": null,
"userAgent": "user-agent",
"userArn": null,
"clientCert": {
"clientCertPem": "CERT_CONTENT",
"subjectDN": "www.example.com",
"issuerDN": "Example issuer",
"serialNumber": "a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1",
"validity": {
"notBefore": "May 28 12:30:02 2019 GMT",
"notAfter": "Aug 5 09:36:04 2021 GMT"
}
}
},
"path": "/my/path",
"protocol": "HTTP/1.1",
"requestId": "id=",
"requestTime": "04/Mar/2020:19:15:17 +0000",
"requestTimeEpoch": 1583349317135,
"resourceId": null,
"resourcePath": "/my/path",
"stage": "$default"
},
"pathParameters": null,
"stageVariables": null,
"body": "Hello from Lambda!",
"isBase64Encoded": false
}
```
------
## Formato di risposta della funzione Lambda
Il tipo di formato del payload determina la struttura della risposta che deve essere restituita dalla funzione Lambda.
### Risposta della funzione Lambda per il formato 1.0
Con la versione di formato `1.0`, le integrazioni Lambda devono restituire una risposta nel formato JSON seguente:
**Example**
```
{
"isBase64Encoded": true|false,
"statusCode": httpStatusCode,
"headers": { "headername": "headervalue", ... },
"multiValueHeaders": { "headername": ["headervalue", "headervalue2", ...], ... },
"body": "..."
}
```
### Risposta della funzione Lambda per il formato 2.0
Con il tipo di formato `2.0`, API Gateway può dedurre autonomamente il formato della risposta. Se la funzione Lambda restituisce un JSON valido e non restituisce un , API Gateway fa le seguenti ipotes `statusCode`:
+ `isBase64Encoded` è `false`.
+ `statusCode` è `200`.
+ `content-type` è `application/json`.
+ `body` è la risposta della funzione.
Gli esempi seguenti mostrano l'output di una funzione Lambda e l'interpretazione da parte di API Gateway.
| Risultato della funzione Lambda | Interpretazione di API Gateway |
| --- | --- |
| "Hello from Lambda!"
| {
"isBase64Encoded": false,
"statusCode": 200,
"body": "Hello from Lambda!",
"headers": {
"content-type": "application/json"
}
} |
| { "message": "Hello from Lambda!" } | {
"isBase64Encoded": false,
"statusCode": 200,
"body": "{ \"message\": \"Hello from Lambda!\" }",
"headers": {
"content-type": "application/json"
}
} |
Per personalizzare la risposta, la funzione Lambda deve restituire una risposta con il seguente formato.
```
{
"cookies" : ["cookie1", "cookie2"],
"isBase64Encoded": true|false,
"statusCode": httpStatusCode,
"headers": { "headername": "headervalue", ... },
"body": "Hello from Lambda!"
}
```
# Crea integrazioni proxy HTTP per HTTP APIs
Un'integrazione proxy HTTP consente di collegare una route API a un endpoint HTTP instradabile pubblicamente. Con questo tipo di integrazione, API Gateway passa l'intera richiesta e risposta tra il front-end e il back-end.
Per creare un'integrazione HTTP, fornire l'URL di un endpoint HTTP instradabile pubblicamente.
## Integrazione proxy HTTP con variabili di percorso
Nelle route delle API HTTP è possibile utilizzare delle variabili di percorso.
Ad esempio, la route `/pets/{petID}` cattura le richieste a `/pets/6`. Puoi fare riferimento alle variabili di percorso nell'URI di integrazione per inviare il contenuto della variabile a un'integrazione. Un esempio è `/pets/extendedpath/{petID}`.
Puoi utilizzare variabili di percorso greedy per catturare tutte le risorse figlio di una route. Per creare una variabile di percorso greedy, aggiungere `+` al nome della variale, ad esempio `{proxy+}`.
Per impostare una route con un'integrazione proxy HTTP che cattura tutte le richieste, crea una route API con una variabile di percorso greedy (ad esempio, `/parent/{proxy+}`). Integra la route con un endpoint HTTP (ad esempio `https://petstore-demo-endpoint.execute-api.com/petstore/{proxy}`) nel metodo `ANY`. La variabile di percorso greedy deve trovarsi alla fine del percorso della risorsa.
# Crea integrazioni AWS di servizi per HTTP APIs in API Gateway
Puoi integrare la tua API HTTP con AWS i servizi utilizzando *integrazioni di prima classe*. Un'integrazione di prima classe collega una route di un'API HTTP a un'API di un servizio AWS . Quando un client richiama un percorso supportato da un'integrazione di prima classe, API Gateway richiama un' AWS API di servizio per te. Ad esempio, puoi utilizzare integrazioni di prima classe per inviare un messaggio a una coda di Amazon Simple Queue Service o per avviare una macchina a stati. AWS Step Functions Per le operazioni di servizio supportate, consulta [Riferimento al sottotipo di integrazione](http-api-develop-integrations-aws-services-reference.md).
## Mappatura dei parametri delle richieste
Le integrazioni di prima classe hanno parametri obbligatori e facoltativi. È necessario configurare tutti i parametri obbligatori per creare un'integrazione. È possibile utilizzare valori statici o mappare i parametri che vengono valutati dinamicamente in fase di runtime. Per un elenco completo delle integrazioni e dei parametri supportati, consulta [Riferimento al sottotipo di integrazione](http-api-develop-integrations-aws-services-reference.md).
Nella tabella seguente vengono descritti i parametri supportati della richiesta di mappatura.
| Tipo | Esempio | Note |
| --- | --- | --- |
| Valore intestazione | \$1request.header. name | I nomi delle intestazioni non fanno distinzione tra maiuscole e minuscole. API Gateway combina più valori di intestazione con virgole, ad esempio "header1": "value1,value2". |
| Valore della stringa di query | \$1request.querystring. name | I nomi delle stringhe di query fanno distinzione tra maiuscole e minuscole. API Gateway combina più valori con virgole, ad esempio "querystring1": "Value1,Value2". |
| Parametro del percorso | \$1richiesta.percorso. name | Il valore di un parametro del percorso nella richiesta. Ad esempio, se l'instradamento è /pets/\$1petId\$1, è possibile mappare il parametro petId della richiesta con \$1request.path.petId. |
| Passthrough corpo richiesta | \$1request.body | API Gateway passa l'intero corpo della richiesta. |
| Corpo della richiesta | \$1request.body. name | Un'[espressione di percorso JSON](https://goessner.net/articles/JsonPath/index.html#e2). Le espressioni di discesa ricorsiva (\$1request.body..name) e di filtro (?(expression)) non sono supportate. Quando si specifica un percorso JSON, API Gateway tronca il corpo della richiesta a 100 KB e quindi applica l'espressione di selezione. Per inviare payload superiori a 100 KB, specificare `$request.body`. |
| Variabile di contesto | \$1contesto. variableName | Valore di una [variabile di contesto](http-api-logging-variables.md) supportata. |
| Variabile di fase | \$1stageVariabili. variableName | Il valore di una [variabile di fase](http-api-stages.stage-variables.md). |
| Valore statico | string | Un valore costante. |
## Creazione di un'integrazione di prima classe
Prima di creare un'integrazione di prima classe, devi creare un ruolo IAM che conceda le autorizzazioni API Gateway per richiamare l'azione di AWS servizio con cui stai effettuando l'integrazione. Per ulteriori informazioni, consulta [Creazione di un ruolo per un servizio AWS](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html).
Per creare un'integrazione di prima classe, scegli un'azione di AWS servizio supportata`SQS-SendMessage`, ad esempio configura i parametri di richiesta e fornisci un ruolo che conceda le autorizzazioni API Gateway per richiamare l'API del servizio integrato. AWS A seconda del sottotipo di integrazione, sono necessari diversi parametri di richiesta. Per ulteriori informazioni, consulta [Riferimento al sottotipo di integrazione](http-api-develop-integrations-aws-services-reference.md).
Il comando [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) seguente crea un’integrazione che invia un messaggio Amazon SQS:
```
aws apigatewayv2 create-integration \
--api-id abcdef123 \
--integration-subtype SQS-SendMessage \
--integration-type AWS_PROXY \
--payload-format-version 1.0 \
--credentials-arn arn:aws:iam::123456789012:role/apigateway-sqs \
--request-parameters '{"QueueUrl": "$request.header.queueUrl", "MessageBody": "$request.body.message"}'
```
## Crea un'integrazione di prima classe utilizzando CloudFormation
L'esempio seguente mostra uno CloudFormation snippet che crea un `/{source}/{detailType}` percorso con un'integrazione di prima classe con Amazon. EventBridge
Il parametro `Source` viene mappato al parametro del percorso `{source}`, `DetailType` viene mappato al parametro del percorso `{DetailType}` e il parametro `Detail` viene mappato al corpo della richiesta.
Lo snippet non mostra il router di eventi o il ruolo IAM che concede le autorizzazioni Gateway API per richiamare l'operazione `PutEvents`.
```
Route:
Type: AWS::ApiGatewayV2::Route
Properties:
ApiId: !Ref HttpApi
AuthorizationType: None
RouteKey: 'POST /{source}/{detailType}'
Target: !Join
- /
- - integrations
- !Ref Integration
Integration:
Type: AWS::ApiGatewayV2::Integration
Properties:
ApiId: !Ref HttpApi
IntegrationType: AWS_PROXY
IntegrationSubtype: EventBridge-PutEvents
CredentialsArn: !GetAtt EventBridgeRole.Arn
RequestParameters:
Source: $request.path.source
DetailType: $request.path.detailType
Detail: $request.body
EventBusName: !GetAtt EventBus.Arn
PayloadFormatVersion: "1.0"
```
# Riferimento al sottotipo di integrazione
I seguenti [sottotipi di integrazione](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid.html#apis-apiid-integrations-integrationid-prop-integration-integrationsubtype) sono supportati per le API HTTP.
**Topics**
+ [EventBridge-PutEvents 1.0](#EventBridge-PutEvents)
+ [SQS-SendMessage 1.0](#SQS-SendMessage)
+ [SQS-ReceiveMessage 1.0](#SQS-ReceiveMessage)
+ [SQS-DeleteMessage 1.0](#SQS-DeleteMessage)
+ [SQS-PurgeQueue 1.0](#SQS-PurgeQueue)
+ [AppConfig-GetConfiguration 1.0](#AppConfig-GetConfiguration)
+ [Kinesis-PutRecord 1.0](#Kinesis-PutRecord)
+ [StepFunctions-StartExecution 1.0](#StepFunctions-StartExecution)
+ [StepFunctions-StartSyncExecution 1.0](#StepFunctions-StartSyncExecution)
+ [StepFunctions-StopExecution 1.0](#StepFunctions-StopExecution)
## EventBridge-PutEvents 1.0
Invia eventi personalizzati ad Amazon EventBridge in modo che possano essere abbinati alle regole.
| Parametro | Campo obbligatorio |
| --- | --- |
| Dettaglio | True |
| DetailType | True |
| Crea | True |
| Orario | False |
| EventBusName | False |
| Risorse | False |
| Regione | False |
| TraceHeader | False |
Per ulteriori informazioni, consulta [PutEvents](https://docs.aws.amazon.com/eventbridge/latest/APIReference/API_PutEvents.html) nella *Guida di riferimento per le API di Amazon EventBridge*.
## SQS-SendMessage 1.0
Recapita un messaggio alla coda specificata.
| Parametro | Campo obbligatorio |
| --- | --- |
| QueueUrl | True |
| MessageBody | True |
| DelaySeconds | False |
| MessageAttributes | False |
| MessageDeduplicationId | False |
| MessageGroupId | False |
| MessageSystemAttributes | False |
| Regione | False |
Per ulteriori informazioni, consulta [SendMessage](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_SendMessage.html) nella *Guida di riferimento per le API di Amazon Simple Queue Service*.
## SQS-ReceiveMessage 1.0
Recupera uno o più messaggi (fino a 10) dalla coda specificata.
| Parametro | Campo obbligatorio |
| --- | --- |
| QueueUrl | True |
| AttributeNames | False |
| MaxNumberOfMessages | False |
| MessageAttributeNames | False |
| ReceiveRequestAttemptId | False |
| VisibilityTimeout | False |
| WaitTimeSeconds | False |
| Regione | False |
Per ulteriori informazioni, consulta [ReceiveMessage](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_ReceiveMessage.html) nella *Guida di riferimento per le API di Amazon Simple Queue Service*.
## SQS-DeleteMessage 1.0
Elimina il messaggio specificato dalla coda specificata.
| Parametro | Campo obbligatorio |
| --- | --- |
| ReceiptHandle | True |
| QueueUrl | True |
| Regione | False |
Per ulteriori informazioni, consulta [DeleteMessage](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_DeleteMessage.html) nella *Guida di riferimento per le API di Amazon Simple Queue Service*.
## SQS-PurgeQueue 1.0
Elimina tutti i messaggi nella coda specificata.
| Parametro | Campo obbligatorio |
| --- | --- |
| QueueUrl | True |
| Regione | False |
Per ulteriori informazioni, consulta [PurgeQueue](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_PurgeQueue.html) nella *Guida di riferimento per le API di Amazon Simple Queue Service*.
## AppConfig-GetConfiguration 1.0
Ricezione di informazioni su una configurazione.
| Parametro | Campo obbligatorio |
| --- | --- |
| Applicazione | True |
| Ambiente | True |
| Configurazione | True |
| ClientId | True |
| ClientConfigurationVersion | False |
| Regione | False |
Per ulteriori informazioni, consulta [GetConfiguration](https://docs.aws.amazon.com/appconfig/2019-10-09/APIReference/API_GetConfiguration.html) in *Documentazione di riferimento delle API AWS AppConfig*.
## Kinesis-PutRecord 1.0
Scrive un singolo record di dati in un flusso di dati di Amazon Kinesis.
| Parametro | Campo obbligatorio |
| --- | --- |
| StreamName | True |
| Dati | True |
| PartitionKey | True |
| SequenceNumberForOrdering | False |
| ExplicitHashKey | False |
| Regione | False |
Per ulteriori informazioni, consulta [PutRecord](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_PutRecord.html) nella *Guida di riferimento per le API di Amazon Kinesis Data Streams*.
## StepFunctions-StartExecution 1.0
Avvia l'esecuzione di una macchina a stati.
| Parametro | Campo obbligatorio |
| --- | --- |
| StateMachineArn | True |
| Nome | False |
| Input | False |
| Regione | False |
Per ulteriori informazioni, consulta [StartExecution](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StartExecution.html) nella *Documentazione di riferimento delle API AWS Step Functions*.
## StepFunctions-StartSyncExecution 1.0
Avvia un'esecuzione sincrona di una macchina a stati.
| Parametro | Campo obbligatorio |
| --- | --- |
| StateMachineArn | True |
| Nome | False |
| Input | False |
| Regione | False |
| TraceHeader | False |
Per ulteriori informazioni, consulta [StartSyncExecution](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StartSyncExecution.html) nella *Documentazione di riferimento delle API AWS Step Functions*.
## StepFunctions-StopExecution 1.0
Interrompe un'esecuzione.
| Parametro | Campo obbligatorio |
| --- | --- |
| ExecutionArn | True |
| Causa | False |
| Errore | False |
| Regione | False |
Per ulteriori informazioni, consulta [StopExecution](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StopExecution.html) nella *Documentazione di riferimento delle API AWS Step Functions*.
# Crea integrazioni private per HTTP APIs in API Gateway
Le integrazioni private consentono di creare integrazioni API con risorse private in un VPC, come ad esempio Application Load Balancer o applicazioni basate su container di Amazon ECS.
Puoi esporre le risorse in un VPC per l'accesso da parte di client esterni al VPC utilizzando integrazioni private. È possibile controllare l'accesso all'API utilizzando uno qualsiasi dei [ metodi di autorizzazione](http-api-access-control.md) supportati da API Gateway.
**Nota**
Per creare un'integrazione privata, devi innanzitutto creare un collegamento VPC. I link VPC V2 sono ora supportati sia per HTTP che per REST. APIs Per ulteriori informazioni sui collegamenti VPC V2, consulta. [Configura i collegamenti VPC V2 in API Gateway](apigateway-vpc-links-v2.md)
Dopo aver creato un VPC link V2, puoi configurare integrazioni private che si connettono a un Application Load Balancer, Network Load Balancer o a risorse registrate con un servizio. AWS Cloud Map
## Considerazioni
Le seguenti considerazioni potrebbero influire sull'utilizzo delle integrazioni private:
+ Tutte le risorse devono essere di proprietà dello stesso. Account AWS Ciò include il AWS Cloud Map servizio o il servizio di bilanciamento del carico, il collegamento VPC e l'API HTTP.
+ Per impostazione predefinita, il traffico di integrazione privata utilizza il protocollo HTTP. Per utilizzare HTTPS, specifica un. [https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid.html](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid.html) A tale scopo Console di gestione AWS, quando crei l'integrazione privata, scegli **Impostazioni avanzate** e quindi inserisci un nome di server sicuro.
+ Per le integrazioni private, API Gateway include la porzione [fase](http-api-stages.md) dell'endpoint API nella richiesta alle risorse back-end. Ad esempio, una richiesta alla fase `test` di un'API include `test/route-path` nella richiesta all'integrazione privata. Per rimuovere il nome della fase dalla richiesta alle risorse di back-end, utilizzare [parameter mapping](http-api-parameter-mapping.md) (mappatura dei parametri) per sovrascrivere il percorso della richiesta a `$request.path`.
## Creare un'integrazione privata utilizzando un Application Load Balancer o un Network Load Balancer
Prima di creare un'integrazione privata, è necessario creare un collegamento VPC V2. Per ulteriori informazioni sui collegamenti VPC V2, consulta. [Configura i collegamenti VPC V2 in API Gateway](apigateway-vpc-links-v2.md)
Per creare un'integrazione privata con un Application Load Balancer o un Network Load Balancer, creare un'integrazione proxy HTTP, specificare il collegamento VPC da utilizzare e fornire l'ARN del listener del sistema di bilanciamento del carico.
Il comando [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) seguente crea un’integrazione privata che si connette a un bilanciatore del carico utilizzando un collegamento VPC:
```
aws apigatewayv2 create-integration --api-id api-id --integration-type HTTP_PROXY \
--integration-method GET --connection-type VPC_LINK \
--connection-id VPC-link-ID \
--integration-uri arn:aws:elasticloadbalancing:us-east-2:123456789012:listener/app/my-load-balancer/50dc6c495c0c9188/0467ef3c8400ae65
--payload-format-version 1.0
```
## Crea un'integrazione privata utilizzando Service Discovery AWS Cloud Map
Prima di creare un'integrazione privata, è necessario creare un collegamento VPC V2. Per ulteriori informazioni sui collegamenti VPC, consultare [Configura i collegamenti VPC V2 in API Gateway](apigateway-vpc-links-v2.md).
Per le integrazioni con AWS Cloud Map, API Gateway utilizza `DiscoverInstances` per identificare le risorse. È possibile utilizzare i parametri di query per fare riferimento a risorse specifiche. Gli attributi delle risorse registrate devono includere indirizzi IP e porte. API Gateway distribuisce le richieste tra le risorse integre restituite da `DiscoverInstances`. Per ulteriori informazioni, consulta [DiscoverInstances](https://docs.aws.amazon.com/cloud-map/latest/api/API_DiscoverInstances.html)l' AWS Cloud Map API Reference.
**Nota**
Se utilizzi Amazon ECS per compilare le voci AWS Cloud Map, devi configurare il tuo task Amazon ECS per utilizzare i record SRV con Amazon ECS Service Discovery o attivare Amazon ECS Service Connect. Per ulteriori informazioni, consulta [Interconnecting services](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/interconnecting-services.html) nella Guida per gli sviluppatori di Amazon Elastic Container Service.
Per creare un'integrazione privata con AWS Cloud Map, crea un'integrazione proxy HTTP, specifica il link VPC da utilizzare e fornisci l'ARN del servizio. AWS Cloud Map
Il seguente comando [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) crea un'integrazione privata che utilizza il rilevamento dei AWS Cloud Map servizi per identificare le risorse:
```
aws apigatewayv2 create-integration --api-id api-id --integration-type HTTP_PROXY \
--integration-method GET --connection-type VPC_LINK \
--connection-id VPC-link-ID \
--integration-uri arn:aws:servicediscovery:us-east-2:123456789012:service/srv-id?stage=prod&deployment=green_deployment
--payload-format-version 1.0
```
# Configurazione di CORS per HTTP APIs in API Gateway
[CORS (Cross-origin resource sharing)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) è una caratteristica di sicurezza del browser che limita le richieste HTTP avviate da script in esecuzione nel browser. Se non riesci ad accedere all'API e ricevi un messaggio di errore che contiene `Cross-Origin Request Blocked`, potresti dover abilitare CORS. Per ulteriori informazioni, consulta [Che cos'è CORS?](https://aws.amazon.com/what-is/cross-origin-resource-sharing/)
CORS è in genere necessario per creare applicazioni Web che accedano a APIs server ospitati su un dominio o un'origine diversi. È possibile abilitare CORS per consentire le richieste all'API da un'applicazione Web ospitata in un dominio diverso. Ad esempio, se l'API è ospitata in `https://{api_id}.execute-api.{region}.amazonaws.com/` e si desidera chiamare l'API da un'applicazione Web ospitata in `example.com`, l'API deve supportare CORS.
Se si configura CORS per un'API, API Gateway invia automaticamente una risposta alle richieste OPTIONS preliminari, anche se non esiste una route OPTIONS configurata per l'API. Per una richiesta CORS, API Gateway aggiunge le intestazioni CORS configurate alla risposta da un'integrazione.
**Nota**
Se si configura CORS per un'API, API Gateway ignora le intestazioni CORS restituite dall'integrazione back-end.
È possibile specificare i seguenti parametri in una configurazione CORS. Per aggiungere questi parametri utilizzando la console Gateway API, scegli **Aggiungi** dopo aver inserito il valore.
| Intestazioni CORS | Proprietà di configurazione CORS | Valori di esempio |
| --- | --- | --- |
| Access-Control-Allow-Origin | allowOrigins | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/http-api-cors.html) |
| Access-Control-Allow-Credentials | allowCredentials | true |
| Access-Control-Expose-Headers | exposeHeaders | data,, \$1 x-api-id |
| Access-Control-Max-Age | maxAge | 300 |
| Access-Control-Allow-Methods | allowMethods | GET, POST, DELETE, \$1 |
| Access-Control-Allow-Headers | allowHeaders | authorization, \$1 |
Per restituire le intestazioni CORS, la richiesta deve contenere un'intestazione `origin`. Per il metodo `OPTIONS`, la richiesta deve contenere un'intestazione `origin` e un'intestazione `Access-Control-Request-Method`.
La configurazione CORS potrebbe essere simile all'immagine seguente:
![\[configurazione CORS per HTTP APIs\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/http-cors-console.png)
## Configurazione di CORS per un'API HTTP con un instradamento `$default` e un provider di autorizzazioni
È possibile abilitare CORS e configurare l'autorizzazione per qualsiasi route di un'API HTTP. Quando si abilitano CORS e l'autorizzazione per la [route `$default`](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-develop-routes.html#http-api-develop-routes.default), ci sono alcune considerazioni speciali di cui tenere conto. Il percorso `$default` cattura le richieste per tutti i metodi e i percorsi che non sono stati definiti in modo esplicito, incluse le richieste `OPTIONS`. Per supportare le richieste `OPTIONS` non autorizzate, aggiungi all'API una route `OPTIONS /{proxy+}` che non richiede l'autorizzazione e collega un'integrazione alla route. Il percorso `OPTIONS /{proxy+}` ha priorità più alta rispetto al percorso `$default`. Di conseguenza, consente ai client di inviare richieste `OPTIONS` all'API senza autorizzazione. Per ulteriori informazioni sulle priorità di instradamento, consultare [Routing delle richieste API](http-api-develop-routes.md#http-api-develop-routes.evaluation).
## Configurare CORS per un'API HTTP utilizzando la CLI AWS
Il comando [update-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-api.html) seguente abilita le richieste CORS da `https://www.example.com`:
**Example**
```
aws apigatewayv2 update-api --api-id api-id --cors-configuration AllowOrigins="https://www.example.com"
```
Per maggiori informazioni, consultare [CORS](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid.html#apis-apiid-model-cors) nella Guida di riferimento delle API di Amazon API Gateway Versione 2.
# Trasformazione delle richieste e delle risposte API per API HTTP in Gateway API
È possibile modificare le richieste API dai client prima che raggiungano le integrazioni back-end. È inoltre possibile modificare la risposta dalle integrazioni prima che API Gateway restituisca la risposta ai client. È possibile utilizzare *la mappatura dei parametri* per modificare le richieste e le risposte API per le API HTTP. Per utilizzare la mappatura dei parametri, specificare i parametri di richiesta o risposta API da modificare e la modalità per modificare tali parametri.
## Trasformazione delle richieste API
È possibile utilizzare i parametri di richiesta per modificare le richieste prima che raggiungano le integrazioni back-end. È possibile modificare le intestazioni, le stringhe di query o il percorso della richiesta.
I parametri di richiesta sono una mappa chiave-valore. La chiave identificherà la posizione del parametro di richiesta da modificare e la modalità per modificarlo. Il valore specifica i nuovi dati per il parametro.
Nella tabella seguente sono illustrate le chiavi supportate.
| Tipo | Sintassi |
| --- | --- |
| Intestazione | append\$1overwrite\$1remove:header.headername |
| Stringa di query | append\$1overwrite\$1remove:querystring.querystring-name |
| Percorso | overwrite:path |
Nella tabella seguente sono illustrati i valori supportati che è possibile mappare ai parametri.
| Tipo | Sintassi | Note |
| --- | --- | --- |
| Valore intestazione | \$1request.header.name o \$1\$1request.header.name\$1 | I nomi delle intestazioni non fanno distinzione tra maiuscole e minuscole. API Gateway combina più valori di intestazione con virgole, ad esempio "header1": "value1,value2". Alcune intestazioni sono riservate. Per ulteriori informazioni, consulta [Intestazioni riservate](#http-api-mapping-reserved-headers). |
| Valore della stringa di query | \$1request.querystring.name o \$1\$1request.querystring.name\$1 | I nomi delle stringhe di query fanno distinzione tra maiuscole e minuscole. API Gateway combina più valori con virgole, ad esempio "querystring1" "Value1,Value2". |
| Corpo della richiesta | \$1request.body.name o \$1\$1request.body.name\$1 | Un'espressione di percorso JSON. Le espressioni di discesa ricorsiva (\$1request.body..name)) e di filtro (?(expression)) non sono supportate. Quando si specifica un percorso JSON, API Gateway tronca il corpo della richiesta a 100 KB e quindi applica l'espressione di selezione. Per inviare payload superiori a 100 KB, specificare `$request.body`. |
| Percorso della richiesta | \$1request.path o \$1\$1request.path\$1 | Il percorso della richiesta, senza il nome della fase. |
| Parametro del percorso | \$1request.path.name o \$1\$1request.path.name\$1 | Il valore di un parametro del percorso nella richiesta. Ad esempio, se l'instradamento è /pets/\$1petId\$1, è possibile mappare il parametro petId della richiesta con \$1request.path.petId. |
| Variabile di contesto | \$1context.variableName o \$1\$1context.variableName\$1 | Il valore di una [variabile di contesto](http-api-logging-variables.md). Sono supportati solo i caratteri speciali `.` e `_`. |
| Variabile di fase | \$1stageVariables.variableName o \$1\$1stageVariables.variableName\$1 | Il valore di una [variabile di fase](http-api-stages.stage-variables.md). |
| Valore statico | stringa | Un valore costante. |
**Nota**
Per utilizzare più variabili in un'espressione di selezione, racchiudere la variabile tra parentesi. Ad esempio, `${request.path.name} ${request.path.id}`.
## Trasformazione delle risposte API
È possibile utilizzare i parametri di risposta per trasformare la risposta HTTP da un'integrazione back-end prima di restituire la risposta ai client. È possibile modificare le intestazioni o il codice di stato di una risposta prima che Gateway API restituisca la risposta ai client.
Configurare i parametri di risposta per ogni codice di stato restituito dall'integrazione. I parametri di risposta sono una mappa chiave-valore. La chiave identificherà la posizione del parametro di richiesta da modificare e la modalità per modificarlo. Il valore specifica i nuovi dati per il parametro.
Nella tabella seguente sono illustrate le chiavi supportate.
| Tipo | Sintassi |
| --- | --- |
| Intestazione | append\$1overwrite\$1remove:header.headername |
| Codice di stato | overwrite:statuscode |
Nella tabella seguente sono illustrati i valori supportati che è possibile mappare ai parametri.
| Tipo | Sintassi | Note |
| --- | --- | --- |
| Valore intestazione | \$1response.header.name o \$1\$1response.header.name\$1 | I nomi delle intestazioni non fanno distinzione tra maiuscole e minuscole. API Gateway combina più valori di intestazione con virgole, ad esempio "header1": "value1,value2". Alcune intestazioni sono riservate. Per ulteriori informazioni, consulta [Intestazioni riservate](#http-api-mapping-reserved-headers). |
| Corpo di risposta | \$1response.body.name o \$1\$1response.body.name\$1 | Un'espressione di percorso JSON. Le espressioni di discesa ricorsiva (\$1response.body..name) e di filtro (?(expression)) non sono supportate. Quando si specifica un percorso JSON, API Gateway tronca il corpo della risposta a 100 KB e quindi applica l'espressione di selezione. Per inviare payload superiori a 100 KB, specificare `$response.body`. |
| Variabile di contesto | \$1context.variableName o \$1\$1context.variableName\$1 | Valore di una [variabile di contesto](http-api-logging-variables.md) supportata. |
| Variabile di fase | \$1stageVariables.variableName o \$1\$1stageVariables.variableName\$1 | Il valore di una [variabile di fase](http-api-stages.stage-variables.md). |
| Valore statico | stringa | Un valore costante. |
**Nota**
Per utilizzare più variabili in un'espressione di selezione, racchiudere la variabile tra parentesi. Ad esempio, `${request.path.name} ${request.path.id}`.
## Intestazioni riservate
Le intestazioni seguenti sono riservate. Per queste intestazioni, non è possibile configurare le mappature di richiesta o di risposta.
+ access-control-\$1
+ apigw-\$1
+ Autorizzazione
+ Connessione
+ Content-Encoding
+ Content-Length
+ Content-Location
+ Forwarded
+ Keep-Alive
+ Origin
+ Proxy-Authenticate
+ Proxy-Authorization
+ TE
+ Trailers
+ Transfer-Encoding
+ Upgrade
+ x-amz-\$1
+ x-amzn-\$1
+ X-Forwarded-For
+ X-Forwarded-Host
+ X-Forwarded-Proto
+ Via
## Esempi
Gli esempi della AWS CLI seguenti configurano le mappature dei parametri. Per modelli di esempio CloudFormation, vedi [GitHub](https://github.com/awsdocs/amazon-api-gateway-developer-guide/tree/main/cloudformation-templates).
### Aggiungere un'intestazione a una richiesta API
Il comando [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) seguente crea un’intestazione denominata `header1` per una richiesta API prima che raggiunga l’integrazione del backend. API Gateway popola l'intestazione con l'ID di richiesta.
```
aws apigatewayv2 create-integration \
--api-id abcdef123 \
--integration-type HTTP_PROXY \
--payload-format-version 1.0 \
--integration-uri 'https://api.example.com' \
--integration-method ANY \
--request-parameters '{ "append:header.header1": "$context.requestId" }'
```
### Rinominare un'intestazione di richiesta
Il comando [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) seguente rinomina l’intestazione di una richiesta da `header1` a `header2`:
```
aws apigatewayv2 create-integration \
--api-id abcdef123 \
--integration-type HTTP_PROXY \
--payload-format-version 1.0 \
--integration-uri 'https://api.example.com' \
--integration-method ANY \
--request-parameters '{ "append:header.header2": "$request.header.header1", "remove:header.header1": "''"}'
```
### Modificare la risposta da un'integrazione
Il comando [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) seguente configura i parametri di risposta per un’integrazione. Quando le integrazioni restituiscono un codice di stato 500, API Gateway modifica il codice di stato in 403 e aggiunge `header1`1 alla risposta. Quando l'integrazione restituisce un codice di stato 404, API Gateway aggiunge un'intestazione `error` alla risposta.
```
aws apigatewayv2 create-integration \
--api-id abcdef123 \
--integration-type HTTP_PROXY \
--payload-format-version 1.0 \
--integration-uri 'https://api.example.com' \
--integration-method ANY \
--response-parameters '{"500" : {"append:header.header1": "$context.requestId", "overwrite:statuscode" : "403"}, "404" : {"append:header.error" : "$stageVariables.environmentId"} }'
```
### Rimuovere le mappature dei parametri configurati
Il comando [update-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) seguente rimuove i parametri di richiesta configurati in precedenza per `append:header.header1`. Il comando rimuove anche i parametri di risposta configurati in precedenza per un codice di stato 200.
```
aws apigatewayv2 update-integration \
--api-id abcdef123 \
--integration-id hijk456 \
--request-parameters '{"append:header.header1" : ""}' \
--response-parameters '{"200" : {}}'
```
# Usa le definizioni OpenAPI per HTTP APIs in API Gateway
È possibile definire l'API HTTP utilizzando un file di definizione OpenAPI 3.0. Quindi è possibile importare la definizione in API Gateway per creare un'API. Per ulteriori informazioni sulle estensioni di API Gateway verso OpenAPI, consultare [Estensioni OpenAPI per Gateway API](api-gateway-swagger-extensions.md).
## Importazione di un'API HTTP
È possibile creare un'API HTTP importando un file di definizione OpenAPI 3.0.
Per eseguire la migrazione da un'API REST a un'API HTTP, è possibile esportare l'API REST come file di definizione OpenAPI 3.0. Quindi importare la definizione dell'API come un'API HTTP. Per ulteriori informazioni sull'esportazione di un'API REST, consultare [Esportazione di un'API REST da API Gateway](api-gateway-export-api.md).
**Nota**
HTTP APIs supporta le stesse AWS variabili di REST APIs. Per ulteriori informazioni, consulta [AWS variabili per l'importazione OpenAPI](import-api-aws-variables.md).
### Informazioni di convalida dell'importazione
Quando si importa un'API, API Gateway fornisce tre categorie di informazioni di convalida.
**Informazioni**
Una proprietà è valida in base alla specifica OpenAPI, ma tale proprietà non è supportata per HTTP. APIs
Ad esempio, il seguente frammento di codice OpenAPI 3.0 produce informazioni sull'importazione perché HTTP APIs non supporta la convalida delle richieste. API Gateway ignora i campi `requestBody` e `schema`.
```
"paths": {
"/": {
"get": {
"x-amazon-apigateway-integration": {
"type": "AWS_PROXY",
"httpMethod": "POST",
"uri": "arn:aws:lambda:us-east-2:123456789012:function:HelloWorld",
"payloadFormatVersion": "1.0"
},
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Body"
}
}
}
}
}
}
...
},
"components": {
"schemas": {
"Body": {
"type": "object",
"properties": {
"key": {
"type": "string"
}
}
}
...
}
...
}
```
**Attenzione**
Una proprietà o una struttura non è valida in base alla specifica OpenAPI, ma non blocca la creazione di API. È possibile specificare se l'API Gateway deve ignorare questi avvisi e continuare a creare l'API o interrompere la creazione dell'API n caso di presenza di avvisi.
Il seguente documento OpenAPI 3.0 produce avvisi sull'importazione perché HTTP supporta APIs solo le integrazioni del proxy Lambda e del proxy HTTP.
```
"x-amazon-apigateway-integration": {
"type": "AWS",
"httpMethod": "POST",
"uri": "arn:aws:lambda:us-east-2:123456789012:function:HelloWorld",
"payloadFormatVersion": "1.0"
}
```
**Errore**
La specifica OpenAPI non è valida o è malformata. API Gateway non è in grado di creare alcuna risorsa dal documento malformato. È necessario correggere gli errori e quindi riprovare.
La seguente definizione dell'API produce errori durante l'importazione perché HTTP APIs supporta solo la specifica OpenAPI 3.0.
```
{
"swagger": "2.0.0",
"info": {
"title": "My API",
"description": "An Example OpenAPI definition for Errors/Warnings/ImportInfo",
"version": "1.0"
}
...
}
```
Come altro esempio, mentre OpenAPI consente agli utenti di definire un'API con più requisiti di sicurezza associati a una particolare operazione, API Gateway non supporta questa operazione. Ogni operazione può avere solo un'autorizzazione IAM, un provider di autorizzazioni Lambda o un provider di autorizzazioni JWT. Il tentativo di modellare più requisiti di sicurezza genera un errore.
### Importa un'API utilizzando il AWS CLI
Il comando [import-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/import-api.html) seguente importa il file di definizione OpenAPI 3.0 `api-definition.json` come API HTTP:
**Example**
```
aws apigatewayv2 import-api --body file://api-definition.json
```
**Example**
È possibile importare la seguente definizione OpenAPI 3.0 di esempio per creare un'API HTTP.
```
{
"openapi": "3.0.1",
"info": {
"title": "Example Pet Store",
"description": "A Pet Store API.",
"version": "1.0"
},
"paths": {
"/pets": {
"get": {
"operationId": "GET HTTP",
"parameters": [
{
"name": "type",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "page",
"in": "query",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "200 response",
"headers": {
"Access-Control-Allow-Origin": {
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Pets"
}
}
}
}
},
"x-amazon-apigateway-integration": {
"type": "HTTP_PROXY",
"httpMethod": "GET",
"uri": "http://petstore.execute-api.us-west-1.amazonaws.com/petstore/pets",
"payloadFormatVersion": 1.0
}
},
"post": {
"operationId": "Create Pet",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NewPet"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "200 response",
"headers": {
"Access-Control-Allow-Origin": {
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NewPetResponse"
}
}
}
}
},
"x-amazon-apigateway-integration": {
"type": "HTTP_PROXY",
"httpMethod": "POST",
"uri": "http://petstore.execute-api.us-west-1.amazonaws.com/petstore/pets",
"payloadFormatVersion": 1.0
}
}
},
"/pets/{petId}": {
"get": {
"operationId": "Get Pet",
"parameters": [
{
"name": "petId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "200 response",
"headers": {
"Access-Control-Allow-Origin": {
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Pet"
}
}
}
}
},
"x-amazon-apigateway-integration": {
"type": "HTTP_PROXY",
"httpMethod": "GET",
"uri": "http://petstore.execute-api.us-west-1.amazonaws.com/petstore/pets/{petId}",
"payloadFormatVersion": 1.0
}
}
}
},
"x-amazon-apigateway-cors": {
"allowOrigins": [
"*"
],
"allowMethods": [
"GET",
"OPTIONS",
"POST"
],
"allowHeaders": [
"x-amzm-header",
"x-apigateway-header",
"x-api-key",
"authorization",
"x-amz-date",
"content-type"
]
},
"components": {
"schemas": {
"Pets": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Pet"
}
},
"Empty": {
"type": "object"
},
"NewPetResponse": {
"type": "object",
"properties": {
"pet": {
"$ref": "#/components/schemas/Pet"
},
"message": {
"type": "string"
}
}
},
"Pet": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"type": {
"type": "string"
},
"price": {
"type": "number"
}
}
},
"NewPet": {
"type": "object",
"properties": {
"type": {
"$ref": "#/components/schemas/PetType"
},
"price": {
"type": "number"
}
}
},
"PetType": {
"type": "string",
"enum": [
"dog",
"cat",
"fish",
"bird",
"gecko"
]
}
}
}
}
```
# Esporta HTTP APIs da API Gateway
Dopo aver creato un'API HTTP, è possibile esportare una definizione OpenAPI 3.0 della propria API da API Gateway. È possibile scegliere una fase da esportare o esportare l'ultima configurazione dell'API. È inoltre possibile importare una definizione API esportata in API Gateway per creare un'altra API identica. Per ulteriori informazioni sull'importazione delle definizioni API, consultare [Importazione di un'API HTTP](http-api-open-api.md#http-api-import).
## Esportazione di una definizione OpenAPI 3.0 di uno stage utilizzando la CLI AWS
Il comando [export-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/export-api.html) seguente esporta una definizione OpenAPI di una fase API denominata `prod` in un file YAML denominato `stage-definition.yaml`. Per impostazione predefinita il file di definizione esportato include le [estensioni API Gateway](api-gateway-swagger-extensions.md).
```
aws apigatewayv2 export-api \
--api-id api-id \
--output-type YAML \
--specification OAS30 \
--stage-name prod \
stage-definition.yaml
```
## Esporta una definizione OpenAPI 3.0 delle ultime modifiche della tua API utilizzando la CLI AWS
Il comando [export-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/export-api.html) seguente esporta una definizione OpenAPI di un’API HTTP in un file JSON denominato `latest-api-definition.json`. Poiché il comando non specifica una fase, API Gateway esporta la configurazione più recente dell'API, indipendentemente dal fatto che sia stata distribuita in una fase o meno. Il file di definizione esportato non include le [estensioni API Gateway](api-gateway-swagger-extensions.md).
```
aws apigatewayv2 export-api \
--api-id api-id \
--output-type JSON \
--specification OAS30 \
--no-include-extensions \
latest-api-definition.json
```
Per ulteriori informazioni, consulta [ExportAPI](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-exports-specification.html#apis-apiid-exports-specification-http-methods) nella *Guida di riferimento per le API di Amazon API Gateway Versione 2*.
## Esportazione di una definizione OpenAPI 3.0 utilizzando la console Gateway API
La seguente procedura mostra come esportare una definizione OpenAPI di un'API HTTP.
**Esportazione di una definizione OpenAPI 3.0 utilizzando la console Gateway API**
1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Scegliere un'API HTTP.
1. Nel pannello di navigazione principale, in **Sviluppa**, scegli **Esporta**.
1. Seleziona una delle seguenti opzioni per esportare la tua API:
![\[Opzioni di esportazione per HTTP. APIs\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/export-http-api.png)
1. In **Origine**, seleziona un'origine per la definizione OpenAPI 3.0. Puoi scegliere una fase da esportare o esportare l'ultima configurazione dell'API.
1. Attiva **Includi le estensioni API Gateway** per includere le [estensioni Gateway API](api-gateway-swagger-extensions.md).
1. In **Formato di output**, seleziona un formato di output.
1. Scegli **Scarica**.
# Pubblicazione di API HTTP che i clienti possono invocare
Puoi utilizzare fasi e nomi di dominio personalizzati per pubblicare l'API richiamabile dai client.
Una fase API è un riferimento logico a uno stato del ciclo di vita dell'API (ad esempio, `dev`, `prod`, `beta` o `v2`). Ogni fase è un riferimento con nome a una distribuzione dell'API e viene resa disponibile per le applicazioni client da chiamare. Puoi configurare integrazioni e impostazioni differenti per ogni fase di un'API.
Puoi utilizzare nomi di dominio personalizzati per fornire un URL più semplice e intuitivo all'API richiamabile dai client, rispetto all'URL predefini, `https://api-id.execute-api.region.amazonaws.com/stage`.
**Nota**
Per aumentare la sicurezza delle API API Gateway, il dominio `execute-api.{region}.amazonaws.com`è registrato nella [Public Suffix List (PSL)](https://publicsuffix.org/). Per una maggiore sicurezza, consigliamo di utilizzare i cookie con un prefisso `__Host-` se hai bisogno di impostare cookie sensibili nel nome di dominio predefinito per le API API Gateway. Questa pratica ti aiuterà a difendere il tuo dominio dai tentativi CSRF (cross-site request forgery). Per ulteriori informazioni, consulta la pagina [Impostazione cookie](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#cookie_prefixes) nella pagina Mozilla Developer Network.
**Topics**
+ [Fasi per HTTP APIs in API Gateway](http-api-stages.md)
+ [Politica di sicurezza per HTTP APIs in API Gateway](http-api-ciphers.md)
+ [Nomi di dominio personalizzati per API HTTP in Gateway API](http-api-custom-domain-names.md)
# Fasi per HTTP APIs in API Gateway
Una fase API è un riferimento logico a uno stato del ciclo di vita dell'API (ad esempio, `dev`, `prod`, `beta` o `v2`). Le fasi API sono identificate dal rispettivo ID API e dal nome della fase e sono incluse nell'URL utilizzato per richiamare l'API. Ogni fase è un riferimento con nome a una distribuzione dell'API e viene resa disponibile per le applicazioni client da chiamare.
È possibile creare una fase `$default` che viene servita dalla base dell'URL dell'API, ad esempio `https://{api_id}.execute-api.{region}.amazonaws.com/`. Utilizzare questo URL per richiamare una fase API.
Una distribuzione è uno snapshot della configurazione dell'API. Dopo essere stata distribuita a una fase, l'API è disponibile per i client da richiamare. È necessario distribuire un'API per attivare le modifiche apportate. Se si abilitano le distribuzioni automatiche, le modifiche apportate a un'API vengono rilasciate automaticamente.
# Usa le variabili di fase per HTTP APIs in API Gateway
Le variabili di fase sono coppie chiave-valore che è possibile definire per una fase di un'API HTTP. Fungono da variabili di ambiente e possono essere utilizzate nella configurazione dell'API.
Le variabili di fase non sono destinate ad essere utilizzate per i dati sensibili, come le credenziali. Per passare dati sensibili alle integrazioni, usa un AWS Lambda autorizzatore. È possibile passare dati sensibili alle integrazioni nell'output del provider di autorizzazioni Lambda. Per ulteriori informazioni, consulta [Formato della risposta dell'autorizzazione](http-api-lambda-authorizer.md#http-api-lambda-authorizer.payload-format-response).
## Esempio: utilizzo di una variabile di fase per personalizzare l'endpoint di integrazione HTTP
Ad esempio, puoi definire una variabile di fase e quindi impostare il suo valore come un endpoint HTTP per un'integrazione proxy HTTP. Successivamente, puoi fare riferimento all'endpoint utilizzando il nome della variabile di fase associata. In questo modo, puoi utilizzare la stessa configurazione API con un endpoint diverso in ogni fase. Allo stesso modo, puoi utilizzare le variabili di fase per specificare un'integrazione di AWS Lambda funzioni diversa per ogni fase dell'API.
Per utilizzare una variabile di fase per personalizzare l'endpoint di integrazione HTTP, è necessario innanzitutto impostare il nome e il valore della variabile di fase (ad esempio `url`) con un valore pari a `example.com`. Quindi, impostare un'integrazione proxy HTTP. Anziché inserire l'URL dell'endpoint, è possibile comunicare ad API Gateway di usare il valore della variabile di fase, ossi, **http://\$1\$1stageVariables.url\$1**. Questo valore indica ad API Gateway di sostituire la variabile di fase `${}` al runtime, a seconda della fase dell'API.
È possibile fare riferimento alle variabili di fase in modo simile per specificare il nome di una funzione Lambda o un ruolo AWS ARN.
Quando si specifica un nome di funzione Lambda come valore della variabile di fase, è necessario configurare manualmente le autorizzazioni per la funzione Lambda. Il comando [add-permission](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html) seguente configura l’autorizzazione per la funzione Lambda:
```
aws lambda add-permission --function-name arn:aws:lambda:XXXXXX:your-lambda-function-name --source-arn arn:aws:execute-api:us-east-1:YOUR_ACCOUNT_ID:api_id/*/HTTP_METHOD/resource --principal apigateway.amazonaws.com --statement-id apigateway-access --action lambda:InvokeFunction
```
# Riferimento alle variabili di fase API Gateway per HTTP APIs in API Gateway
È possibile utilizzare le variabili di fase API Gateway per HTTP APIs nei seguenti casi.
## Integrazione HTTP URIs
Puoi utilizzare una variabile di fase come parte di un URI di integrazione HTTP, come mostrato negli esempi seguenti.
+ Un URI completo senza protocoll – `http://${stageVariables.}`
+ Un dominio completo – `http://${stageVariables.}/resource/operation`
+ Un sottodominio – `http://${stageVariables.}.example.com/resource/operation`
+ Un percorso – `http://example.com/${stageVariables.}/bar`
+ Una stringa di query – `http://example.com/foo?q=${stageVariables.}`
## Funzioni Lambda
Puoi utilizzare una variabile di fase al posto di un nome di integrazione di funzione o alias Lambda, come illustrato negli esempi seguenti.
+ `arn:aws:apigateway::lambda:path/2015-03-31/functions/arn:aws:lambda:::function:${stageVariables.}/invocations`
+ `arn:aws:apigateway::lambda:path/2015-03-31/functions/arn:aws:lambda:::function::${stageVariables.}/invocations`
**Nota**
Per utilizzare una variabile di fase per una funzione Lambda, la funzione deve essere nello stesso account dell'API. Le variabili di fase non supportano le funzioni Lambda tra più account.
## AWS credenziali di integrazione
È possibile utilizzare una variabile stage come parte di un ARN di credenziali AWS utente o di ruolo, come illustrato nell'esempio seguente.
+ `arn:aws:iam:::${stageVariables.}`
# Politica di sicurezza per HTTP APIs in API Gateway
Gateway API applica la policy di sicurezza `TLS_1_2` per tutti gli endpoint delle API HTTP.
Una *policy di sicurezza* è una combinazione predefinita di una versione TLS minima e un pacchetto di crittografia offerta da Gateway Amazon API. Il protocollo TLS affronta i problemi di sicurezza della rete, ad esempio manomissioni e intercettazioni tra un client e un server. Quando i client stabiliscono un handshake TLS sull'API tramite il dominio personalizzato, la policy di sicurezza applica la versione di TLS e le opzioni del pacchetto di crittografia che i client possono scegliere di utilizzare. Questa policy di sicurezza accetta il traffico TLS 1.2 e TLS 1.3 e rifiuta il traffico TLS 1.0.
## Protocolli e cifrari TLS supportati per HTTP APIs
La tabella seguente descrive i protocolli TLS supportati per HTTP. APIs
| **Protocolli TLS** | **Policy di sicurezza TLS\$11\$12** |
| --- | --- |
| TLSv13. | ![\[alt text not found\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/success_icon.svg) Sì |
| TLSv12. | ![\[alt text not found\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/success_icon.svg) Sì |
La tabella seguente descrive i codici TLS disponibili per la politica di sicurezza TLS 1\$12 per HTTP. APIs
| **Crittografie TLS** | **Policy di sicurezza TLS\$11\$12** |
| --- | --- |
| TLS-AES-128-GCM- SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/success_icon.svg) Sì |
| TLS-AES-256-GCM- SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/success_icon.svg) Sì |
| TLS- - - CHACHA20 POLY1305 SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/success_icon.svg) Sì |
| ECDHE-ECDSA- -GCM- AES128 SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/success_icon.svg) Sì |
| ECDH-RSA- AES128 -GCM- SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/success_icon.svg) Sì |
| ECDHE-ECSA AES128 - - SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/success_icon.svg) Sì |
| ECDHE-RSA- - AES128 SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/success_icon.svg) Sì |
| ECDHE-ECDSA- -GCM AES256 - SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/success_icon.svg) Sì |
| ECDH-RSA- AES256 -GCM- SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/success_icon.svg) Sì |
| ECDHE-ECSA AES256 - - SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/success_icon.svg) Sì |
| ECDHE-RSA- - AES256 SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/success_icon.svg) Sì |
| AES128-GCM- SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/success_icon.svg) Sì |
| AES128-SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/success_icon.svg) Sì |
| AES256-GCM- SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/success_icon.svg) Sì |
| AES256-SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/success_icon.svg) Sì |
## OpenSSL e nomi crittografia RFC
OpenSSL e IETF RFC 5246 utilizzano nomi diversi per le stesse crittografie. Per l'elenco dei nomi delle crittografie, consulta [OpenSSL e nomi crittografia RFC](apigateway-security-policies-list.md#apigateway-secure-connections-openssl-rfc-cipher-names).
## Informazioni su REST e APIs WebSocket APIs
Per ulteriori informazioni su REST APIs e WebSocket APIs, vedere [Scegli una politica di sicurezza per il tuo dominio personalizzato in API Gateway](apigateway-custom-domain-tls-version.md) e[Politica di sicurezza per WebSocket APIs API Gateway](websocket-api-ciphers.md).
# Nomi di dominio personalizzati per API HTTP in Gateway API
I *nomi di dominio personalizzati* sono URL più semplici e più intuitivi che è possibile fornire agli utenti delle API.
Dopo aver distribuito un'API, tu e i tuoi clienti potete richiamarla usando l'URL di base predefinito nel formato seguente:
```
https://api-id.execute-api.region.amazonaws.com/stage
```
dove *api-id* è generato da Gateway API, *region* è la Regione AWS e *stage* è il valore che è stato specificato al momento dell'implementazione dell'API.
La parte del nome host dell'URL, `api-id.execute-api.region.amazonaws.com`, fa riferimento a un endpoint API. Il nome dell'endpoint API predefinito viene generato casualmente, è complesso da richiamare e non è intuitivo.
Con i nomi di dominio personalizzati, è possibile impostare il nome host dell'API e scegliere un percorso base (ad esempio `myservice`) per mappare l'URL alternativo all'API. Ad esempio, un URL di base dell'API più intuitivo può diventare:
```
https://api.example.com/myservice
```
## Considerazioni
Le seguenti considerazioni potrebbero influire sull'utilizzo di un nome di dominio personalizzato.
+ Un nome di dominio personalizzato regionale può essere associato alle REST API e alle API HTTP. È possibile utilizzare le API di Gateway API Versione 2 per creare e gestire nomi di dominio personalizzati regionali per le REST API.
+ L'unica versione minima di TLS supportata è TLS 1.2.
+ È necessario creare o aggiornare il record di risorse del provider DNS per eseguire la mappatura all'endpoint API. In assenza di questa mappatura, le richieste API destinate al nome di dominio personalizzato non possono raggiungere API Gateway.
+ È possibile supportare un numero pressoché infinito di nomi di dominio senza superare la quota predefinita con un certificato jolly. Per ulteriori informazioni, consulta [Nomi di dominio personalizzati con caratteri jolly](#http-wildcard-custom-domain-names).
## Prerequisiti
Di seguito sono riportati i prerequisiti per la creazione di un nome di dominio personalizzato.
### Registrare un nome di dominio
Per configurare nomi di dominio personalizzati per le API, devi avere un nome di dominio Internet registrato. Puoi registrare un nome di dominio Internet utilizzando [Amazon Route 53](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/) oppure un registrar di dominio di terze parti a tua scelta. Il nome di dominio personalizzato può essere il nome di un sottodominio o del dominio root (detto anche "apex di zona") di un dominio Internet registrato.
Il nome di dominio deve seguire la specifica [RFC 1035](https://tools.ietf.org/html/rfc1035#section-2.3.4) e può avere un massimo di 63 ottetti per etichetta e 255 ottetti in totale.
### Certificati per nomi di dominio personalizzati
Prima di configurare un nome di dominio personalizzato per un'API, è necessario che sia già presente un certificato SSL/TLS in ACM. Se ACM non è disponibile nella Regione AWS in cui si sta creando il nome di dominio personalizzato, è necessario importare nella Regione un certificato in Gateway API.
Per importare un certificato SSL/TLS, devi fornire il corpo del certificato SSL/TLS in formato PEM, la sua chiave privata e la catena di certificati per il nome di dominio personalizzato.
Ogni certificato archiviato in ACM è identificato dal relativo ARN. Con i certificati emessi da ACM, non devi preoccuparti di esporre dettagli sensibili del certificato, come la chiave privata. Per usare un certificato gestito da AWS per un nome di dominio, devi semplicemente fare riferimento al relativo ARN.
Se l’applicazione utilizza il blocco dei certificati, talvolta denominato associazione SSL, per associare un certificato ACM, è possibile che l'applicazione non riesca a connettersi al tuo dominio dopo che AWS ha rinnovato il certificato. Per ulteriori informazioni, consulta [Probemi nel blocco dei certificati](https://docs.aws.amazon.com/acm/latest/userguide/troubleshooting-pinning.html) nella *Guida per l'utente di AWS Certificate Manager*.
## Nomi di dominio personalizzati con caratteri jolly
Con i nomi di dominio personalizzati con caratteri jolly, è possibile supportare un numero quasi infinito di nomi di dominio senza superare la [quota predefinita](limits.md). Ad esempio, è possibile dare a ciascuno dei clienti il proprio nome di dominio, `customername.api.example.com`.
Per creare un nome di dominio personalizzato con caratteri jolly, specificare un carattere jolly (`*`) come primo sottodominio di un dominio personalizzato che rappresenta tutti i possibili sottodomini di un dominio radice.
Ad esempio, il nome di dominio personalizzato con caratteri jolly `*.example.com` genera sottodomini quali `a.example.com`, `b.example.com` e `c.example.com`, indirizzati tutti allo stesso dominio.
I nomi di dominio personalizzati con caratteri jolly supportano configurazioni distinte dai nomi di dominio personalizzati standard di API Gateway. Ad esempio, in un singolo account AWS, è possibile configurare `*.example.com` e `a.example.com` affinché si comportino in modo diverso.
Per creare un nome di dominio personalizzato con caratteri jolly, è necessario fornire un certificato emesso da ACM che sia stato convalidato utilizzando il DNS o il metodo di convalida della posta elettronica.
**Nota**
Non è possibile creare un nome di dominio personalizzato con caratteri jolly se un account AWS diverso ha creato un nome di dominio personalizzato in conflitto con il nome di dominio personalizzato con caratteri jolly. Ad esempio, se l'account A ha creato `a.example.com`, l'account B non può creare il nome di dominio personalizzato con caratteri jolly `*.example.com`.
Se l'account A e l'account B condividono un proprietario, è possibile contattare il [Centro assistenza AWS](https://console.aws.amazon.com/support/home#/) per richiedere un'eccezione.
## Passaggi successivi per nomi di dominio personalizzati
Per configurare un nome di dominio personalizzato per un'API HTTP, consulta la documentazione disponibile nella sezione REST API della Guida per gli sviluppatori di Gateway API.
Per prima cosa, si specifica un certificato per il nome di dominio personalizzato. Per ulteriori informazioni, consulta [Prepara i certificati in AWS Certificate Manager](how-to-specify-certificate-for-custom-domain-name.md). Successivamente, si crea un nome di dominio personalizzato regionale. Per ulteriori informazioni, consulta [Configurazione di un nome di dominio personalizzato regionale in Gateway API](apigateway-regional-api-custom-domain-create.md).
# Mappatura delle fasi API a un nome di dominio personalizzato per le API HTTP
È possibile utilizzare le mappature API per connettere le fasi API a un nome di dominio personalizzato. Dopo aver creato un nome di dominio e aver configurato i record DNS, è possibile utilizzare le mappature API per inviare il traffico alle API tramite il nome di dominio personalizzato.
Una mappatura API specifica un'API, una fase e, facoltativamente, un percorso da utilizzare per la mappatura. Ad esempio, è possibile mappare la fase `production` di un'API su `https://api.example.com/orders`.
È possibile mappare le fasi HTTP e API REST allo stesso nome di dominio personalizzato.
Prima di creare una mappatura API, è necessario disporre di un'API, di una fase e di un nome di dominio personalizzato. Per ulteriori informazioni sulla creazione di un nome di dominio personalizzato, consulta [Configurazione di un nome di dominio personalizzato regionale in Gateway API](apigateway-regional-api-custom-domain-create.md).
## Routing delle richieste API
È possibile configurare le mappature API con più livelli, ad esempio `orders/v1/items` e `orders/v2/items`.
Per mappature API con più livelli, API Gateway instrada le richieste alla mappatura API che ha il percorso corrispondente più lungo. API Gateway considera solo i percorsi configurati per le mappature API, e non i percorsi API, per selezionare l'API da richiamare. Se nessun percorso corrisponde alla richiesta, API Gateway invia la richiesta all'API mappata al percorso vuoto `(none)`.
Per i nomi di dominio personalizzati che usano mappature API con più livelli, API Gateway instrada le richieste alla mappatura API che ha il percorso corrispondente più lungo.
Ad esempio, se si considera un nome di dominio personalizzato `https://api.example.com` con le seguenti mappature API:
1. `(none)` mappato all'API 1.
1. `orders` mappato all'API 2.
1. `orders/v1/items` mappato all'API 3.
1. `orders/v2/items` mappato all'API 4.
1. `orders/v2/items/categories` mappato all'API 5.
| Richiesta | API selezionata | Spiegazione |
| --- | --- | --- |
| `https://api.example.com/orders` | `API 2` | La richiesta corrisponde esattamente a questa mappatura API. |
| `https://api.example.com/orders/v1/items` | `API 3` | La richiesta corrisponde esattamente a questa mappatura API. |
| `https://api.example.com/orders/v2/items` | `API 4` | La richiesta corrisponde esattamente a questa mappatura API. |
| `https://api.example.com/orders/v1/items/123` | `API 3` | API Gateway sceglie la mappatura con il percorso corrispondente più lungo. `123` alla fine della richiesta non influisce sulla selezione. |
| `https://api.example.com/orders/v2/items/categories/5` | `API 5` | API Gateway sceglie la mappatura con il percorso corrispondente più lungo. |
| `https://api.example.com/customers` | `API 1` | API Gateway utilizza la mappatura vuota come catch-all. |
| `https://api.example.com/ordersandmore` | `API 2` | API Gateway sceglie la mappatura con il prefisso corrispondente più lungo. Per un nome di dominio personalizzato configurato con mappature a livello singolo, ad esempio solo `https://api.example.com/orders` e `https://api.example.com/`, API Gateway sceglie `API 1`, poiché non esiste un percorso corrispondente con `ordersandmore`. |
## Restrizioni
+ In una mappatura API, il nome di dominio personalizzato e le API mappate devono trovarsi nello stesso account AWS.
+ Le mappature API devono contenere solo lettere, numeri e i seguenti caratteri: `$-_.+!*'()/`.
+ La lunghezza massima per il percorso in una mappatura API è di 300 caratteri.
+ È possibile disporre di 200 mappature API con più livelli per ogni nome di dominio. Questo limite non include le mappature API con livelli singoli, ad esempio `/prod`.
+ È possibile mappare le API HTTP a un nome di dominio personalizzato regionale solo con la policy di sicurezza TLS 1.2.
+ Non è possibile mappare le API WebSocket allo stesso nome di dominio personalizzato di un'API HTTP o un'API REST.
+ Se si crea una mappatura API con più livelli, Gateway API converte tutti i nomi di intestazione in lettere minuscole.
## Creare una mappatura API
Per creare una mappatura API, innanzitutto è necessario creare un nome di dominio personalizzato, un'API e una fase. Per informazioni sulla creazione di un nome di dominio personalizzato, consulta [Configurazione di un nome di dominio personalizzato regionale in Gateway API](apigateway-regional-api-custom-domain-create.md).
Per modelli di esempio di AWS Serverless Application Model che creano tutte le risorse, consulta [Sessioni con SAM](https://github.com/aws-samples/sessions-with-aws-sam/tree/master/custom-domains) su GitHub.
------
#### [ Console di gestione AWS ]
**Per creare una mappatura API**
1. Accedere alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Scegliere **Nomi di dominio personalizzati**.
1. Selezionare un nome di dominio personalizzato già creato.
1. Scegliere **API mappings (mappature API)**.
1. Scegliere **Configure API mappings (Configura mappature API)**.
1. Scegliere **Add new mapping (Aggiungi nuova mappatura)**.
1. Immettere un'**API**, uno **Stage (Fase)**e, facoltativamente, un **Path (Percorso)**.
1. Selezionare **Salva**.
------
#### [ AWS CLI ]
Il comando [create-api-mapping](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-api.html) seguente crea una mappatura API. In questo esempio, API Gateway invia le richieste `api.example.com/v1/orders` all'API e alla fase specificate.
```
aws apigatewayv2 create-api-mapping \
--domain-name api.example.com \
--api-mapping-key v1/orders \
--api-id a1b2c3d4 \
--stage test
```
------
#### [ CloudFormation ]
Il seguente esempio di CloudFormation consente di creare una mappatura API.
```
MyApiMapping:
Type: 'AWS::ApiGatewayV2::ApiMapping'
Properties:
DomainName: api.example.com
ApiMappingKey: 'orders/v2/items'
ApiId: !Ref MyApi
Stage: !Ref MyStage
```
------
# Disabilitazione dell'endpoint predefinito per API HTTP
Per impostazione predefinita, i client possono richiamare l'API utilizzando l'endpoint `execute-api` generato da API Gateway per l'API. Per garantire che i client possano accedere all'API solo utilizzando un nome di dominio personalizzato con l'autenticazione TLS reciproca, disattivare l'endpoint `execute-api` predefinito. Quando si disattiva l'endpoint predefinito, questa operazione influisce su tutte le fasi di un'API.
La seguente procedura mostra come disabilitare l'endpoint predefinito per un'API HTTP.
------
#### [ Console di gestione AWS ]
1. Accedere alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Scegliere un'API HTTP.
1. Scegli l'ID dell'API per aprire la pagina **Dettagli API**.
1. In **Dettagli API** seleziona **Modifica**.
1. Per **Endpoint predefinito** seleziona **Disabilita**.
1. Selezionare **Salva**.
Se si attivano le implementazioni automatiche per la fase, non è necessario implementare nuovamente l'API per rendere effettiva la modifica. In caso contrario, è necessario implementare nuovamente l'API.
1. (Facoltativo) Scegli **Distribuzione**, quindi implementa nuovamente l'API o crea una nuova fase per rendere effettiva la modifica.
------
#### [ AWS CLI ]
Il comando [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-domain-name.html) seguente disabilita l’endpoint predefinito per un’API HTTP:
```
aws apigatewayv2 update-api \
--api-id abcdef123 \
--disable-execute-api-endpoint
```
Dopo aver disattivato l'endpoint predefinito, è necessario distribuire l'API per rendere effettiva la modifica, a meno che non siano abilitate le distribuzioni automatiche.
Il seguente comando [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-deployment.html) crea l'implementazione:
```
aws apigatewayv2 create-deployment \
--api-id abcdef123 \
--stage-name dev
```
------
# Tipi di indirizzo IP per nomi di dominio personalizzati per API HTTP
Quando si crea un’API, è possibile specificare il tipo di indirizzo IP che può invocare il dominio. È possibile scegliere IPv4 per risolvere gli indirizzi IPv4 per invocare il dominio oppure dualstack per consentire a entrambi gli indirizzi IPv4 e IPv6 di invocare il dominio. È consigliabile impostare il tipo di indirizzo IP su dualstack per ridurre l’esaurimento dello spazio IP o per il livello di sicurezza. Per ulteriori informazioni sui vantaggi del tipo di indirizzo IP dualstack, consultare [IPv6 on AWS](https://docs.aws.amazon.com/whitepapers/latest/ipv6-on-aws/internet-protocol-version-6.html).
## Considerazioni sui tipi di indirizzo IP
Le seguenti considerazioni potrebbero influire sull’utilizzo dei tipi di indirizzo IP.
+ Il tipo di indirizzo IP predefinito per i nomi di dominio personalizzati di Gateway API è IPv4.
+ Per il nome di dominio personalizzato, non è necessario che tutte le API mappate ad esso abbiano lo stesso tipo di indirizzo IP. Se si disabilita l’endpoint API predefinito, si potrebbe influire sul modo in cui i chiamanti possono invocare l’API.
## Modifica del tipo di indirizzo IP di un nome di dominio personalizzato
È possibile modificare il tipo di indirizzo IP aggiornando la configurazione dell’endpoint del dominio. È possibile aggiornare la configurazione dell’endpoint del dominio utilizzando la Console di gestione AWS, AWS CLI, CloudFormation o un AWS SDK.
------
#### [ Console di gestione AWS ]
**Per modificare il tipo di indirizzo IP di un nome di dominio personalizzato**
1. Accedere alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Scegliere un nome di dominio personalizzato pubblico.
1. Scegliere **Configurazione endpoint**.
1. Per Tipo di indirizzo IP, selezionare **IPv4** o **Dualstack**.
1. Selezionare **Salva**.
------
#### [ AWS CLI ]
Il comando [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-domain-name.html) seguente aggiorna un’API in modo che abbia un tipo di indirizzo IP dualstack:
```
aws apigatewayv2 update-domain-name \
--domain-name dualstack.example.com \
--domain-name-configurations CertificateArn=arn:aws:acm:us-east-1:111122223333:certificate/abcd1234-5678-abc,IpAddressType=dualstack
```
L'output sarà simile al seguente:
```
{
"ApiMappingSelectionExpression": "$request.basepath",
"DomainName": "dualstack.example.com",
"DomainNameConfigurations": [
{
"ApiGatewayDomainName": "d-abcd1234.execute-api.us-east-1.amazonaws.com",
"CertificateArn": "arn:aws:acm:us-east-1:111122223333:certificate/abcd1234-5678-abc",
"DomainNameStatus": "AVAILABLE",
"EndpointType": "REGIONAL",
"HostedZoneId": "Z3LQWSYCGH4ADY",
"SecurityPolicy": "TLS_1_2",
"IpAddressType": "dualstack"
}
],
"Tags": {}
}
```
------
# Protezione delle API HTTP in Gateway API
API Gateway fornisce diversi modi per proteggere l'API da determinate minacce, ad esempio utenti malintenzionati o picchi di traffico. È possibile proteggere l'API usando strategie come l'impostazione delle destinazioni di limitazione e l'abilitazione dell'autenticazione TLS reciproca. In questa sezione viene descritto come abilitare queste funzionalità utilizzando API Gateway.
**Topics**
+ [Limita le richieste al tuo HTTP APIs per una migliore velocità di trasmissione in API Gateway](http-api-throttling.md)
+ [Come attivare l'autenticazione TLS reciproca per il tuo HTTP APIs in API Gateway](http-api-mutual-tls.md)
# Limita le richieste al tuo HTTP APIs per una migliore velocità di trasmissione in API Gateway
Puoi configurare il throttling per APIs evitare che vengano sopraffatti da troppe richieste. Le limitazioni della larghezza di banda della rete sono applicate sulla base del massimo sforzo e dovrebbero essere considerate come obiettivi e non limiti massimi garantiti delle richieste.
API Gateway limita la larghezza di banda della rete delle richieste nell'API mediante l'algoritmo di token bucket, dove un token rappresenta una richiesta. In particolare, API Gateway esamina la frequenza e il numero di richieste inviate rispetto APIs a tutti gli utenti del tuo account, per regione. Nell'algoritmo di bucket token, un picco può consentire il superamento predefinito di tali limiti, ma anche altri fattori possono causare il superamento dei limiti in alcuni casi.
Quando le richieste inviate superano i limiti impostati per il tasso a regime e per i limiti di picco, API Gateway inizia a limitare le richieste. I clienti potrebbero ricevere risposte agli errori `429 Too Many Requests` a questo punto. Quando rileva queste eccezioni, il client può reinviare le richieste non riuscite in modo da limitare la velocità.
In qualità di sviluppatore di API, puoi impostare i limiti target per le singole fasi o percorsi dell'API per migliorare le prestazioni complessive di tutto APIs il tuo account.
## Limitazione a livello di account per regione
Per impostazione predefinita, API Gateway limita le richieste allo stato stazionario (RPS) APIs all'interno di un AWS account, per regione. Inoltre, limita il burst (ovvero la dimensione massima del bucket) per tutti gli elementi APIs all'interno di un account, per regione. AWS In API Gateway, il limite dei picchi rappresenta il numero massimo di invii di richieste che API Gateway può gestire prima di restituire risposte di errore `429 Too Many Requests`. Per ulteriori informazioni sulla limitazione delle quote, vedere [Quote Gateway Amazon API](limits.md).
I limiti per account vengono applicati a tutti i membri di un account APIs in una regione specificata. Il limite di tariffa a livello di account può essere aumentato su richiesta: sono possibili limiti più elevati con APIs timeout più brevi e carichi utili inferiori. Per richiedere un aumento dei limiti di limitazione a livello di account per Regione, contatta il [Centro assistenza AWS](https://console.aws.amazon.com/support/home#/). Per ulteriori informazioni, consulta [Quote Gateway Amazon API](limits.md). Tieni presente che questi limiti non possono essere superiori ai limiti di limitazione. AWS
## Throttling a livello di instradamento
Puoi impostare il throttling a livello di route per sostituire i limiti di throttling delle richieste a livello di account per una fase specifica o per singoli route nell'API. I limiti della limitazione (della larghezza di banda della rete) della route di default non possono superare i limiti di velocità a livello di account.
È possibile configurare la limitazione a livello di percorso utilizzando AWS CLI. Il comando [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-stage.html) seguente configura la limitazione (della larghezza di banda della rete) personalizzata per la fase e l’instradamento specificati di un’API:
```
aws apigatewayv2 update-stage \
--api-id a1b2c3d4 \
--stage-name dev \
--route-settings '{"GET /pets":{"ThrottlingBurstLimit":100,"ThrottlingRateLimit":2000}}'
```
# Come attivare l'autenticazione TLS reciproca per il tuo HTTP APIs in API Gateway
L'autenticazione TLS reciproca richiede l'autenticazione bidirezionale tra il client e il server. Con l'autenticazione TLS reciproca, i client devono presentare certificati X.509 per verificare la propria identità per accedere all'API. Il TLS reciproco è un requisito comune per l'Internet of Things (IoT) e business-to-business le applicazioni.
È possibile utilizzare l'autenticazione TLS reciproca insieme ad altre [operazioni di autorizzazione e autenticazione](apigateway-control-access-to-api.md) supportate da API Gateway. API Gateway inoltra i certificati forniti dai client alle autorizzazioni Lambda e alle integrazioni di back-end.
**Importante**
Per impostazione predefinita, i client possono richiamare l'API utilizzando l'endpoint `execute-api` generato da API Gateway per l'API. Per garantire che i client possano accedere all'API solo utilizzando un nome di dominio personalizzato con l'autenticazione TLS reciproca, disattivare l'endpoint `execute-api` predefinito. Per ulteriori informazioni, consulta [Disabilitazione dell'endpoint predefinito per API HTTP](http-api-disable-default-endpoint.md).
## Prerequisiti per l'autenticazione TLS reciproca
Per configurare l'autenticazione TLS reciproca hai bisogno di:
+ Un nome di dominio personalizzato
+ Almeno un certificato configurato AWS Certificate Manager per il tuo nome di dominio personalizzato
+ Un truststore configurato e caricato in Amazon S3
### Nomi di dominio personalizzati
Per abilitare l'autenticazione TLS reciproca per un'API HTTP, è necessario configurare un nome di dominio personalizzato per l'API. È possibile abilitare l'autenticazione TLS reciproca per un nome di dominio personalizzato e quindi fornire il nome di dominio personalizzato ai client. Per accedere a un'API utilizzando un nome di dominio personalizzato con l'autenticazione TLS reciproca attivata, i client devono presentare certificati attendibili nelle richieste API. Puoi trovare ulteriori informazioni all'indirizzo [Nomi di dominio personalizzati per API HTTP in Gateway API](http-api-custom-domain-names.md).
### Utilizzo di certificati AWS Certificate Manager emessi
Puoi richiedere un certificato pubblicamente attendibile direttamente da ACM o importare certificati pubblici o autofirmati. Per configurare un certificato in ACM, accedi ad [ACM](https://console.aws.amazon.com/acm/). Se desideri importare un certificato, continua a leggere la sezione seguente.
### Utilizzo di un AWS Autorità di certificazione privata certificato o importato
Per utilizzare un certificato importato in ACM o un certificato AWS Autorità di certificazione privata con TLS reciproco, API Gateway necessita di un certificato `ownershipVerificationCertificate` rilasciato da ACM. Questo certificato di proprietà viene utilizzato solo per verificare che disponi delle autorizzazioni per l'utilizzo del nome di dominio. Non viene utilizzato per l'handshake TLS. Se non ne hai già uno`ownershipVerificationCertificate`, vai a [https://console.aws.amazon.com/acm/](https://console.aws.amazon.com/acm/)configurarne uno.
Dovrai mantenere la validità di questo certificato per tutta la durata del nome di dominio. Se un certificato scade e il rinnovo automatico non riesce, tutti gli aggiornamenti al nome di dominio verranno bloccati. Dovrai aggiornare il `ownershipVerificationCertificateArn` con un `ownershipVerificationCertificate` valido prima di poter apportare altre modifiche. Il `ownershipVerificationCertificate` non può essere utilizzato come certificato del server per un altro dominio TLS reciproco in API Gateway. Se un certificato viene reimportato direttamente in ACM, l'emittente deve rimanere invariato.
### Configurazione del truststore
I truststore sono file di testo con un'estensione `.pem`. Sono elenchi attendibili di certificati provenienti da autorità di certificazione. Per utilizzare l'autenticazione TLS reciproca, crea un truststore di certificati X.509 attendibili per accedere all'API.
Devi includere nel truststore l'intera catena di attendibilità, a partire dal certificato della CA emittente, fino al certificato emesso da una CA radice. API Gateway accetta certificati del client emessi da qualsiasi CA presente nella catena di attendibilità. I certificati possono provenire da autorità di certificazione pubbliche o private. I certificati possono avere una lunghezza massima della catena di quattro. È inoltre possibile fornire certificati autofirmati. Nel truststore sono supportati i seguenti algoritmi di hashing:
+ SHA-256 o superiore
+ RSA-2048 o superiore
+ ECDSA-256 o superiore
API Gateway convalida un certo numero di proprietà del certificato. È possibile utilizzare le autorizzazioni Lambda per eseguire ulteriori controlli quando un client richiama un'API, incluso il controllo della revoca di un certificato. API Gateway convalida le seguenti proprietà:
| Validation | Descrizione |
| --- | --- |
| Sintassi X.509 | Il certificato deve soddisfare i requisiti di sintassi X.509. |
| Integrità | Il contenuto del certificato non deve essere stato modificato rispetto a quello firmato dall'autorità di certificazione del truststore. |
| Validity | Il periodo di validità del certificato deve essere attuale. |
| Concatenamento di nomi/concatenamento di chiavi | I nomi e gli oggetti dei certificati devono formare una catena ininterrotta. I certificati possono avere una lunghezza massima della catena di quattro. |
### Carica il truststore in un bucket Amazon S3 in un singolo file
**Example certificates.pem**
```
-----BEGIN CERTIFICATE-----
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
-----END CERTIFICATE-----
...
```
Il seguente AWS CLI comando [cp](https://docs.aws.amazon.com/cli/latest/reference/s3/cp.html) viene caricato nel tuo `certificates.pem` bucket Amazon S3:
```
aws s3 cp certificates.pem s3://bucket-name
```
## Configurazione dell'autenticazione TLS reciproca per un nome di dominio personalizzato
Per configurare l'autenticazione TLS reciproca per un'API HTTP, devi utilizzare un nome di dominio personalizzato regionale per l'API, con la versione 1.2 di TLS o successiva. Per ulteriori informazioni sulla creazione e la configurazione di un nome di dominio personalizzato, consulta [Configurazione di un nome di dominio personalizzato regionale in Gateway API](apigateway-regional-api-custom-domain-create.md).
**Nota**
Il TLS reciproco non è supportato per uso privato. APIs
Dopo aver caricato il truststore su Amazon S3, puoi configurare il tuo nome di dominio personalizzato per utilizzare l'autenticazione TLS reciproca. Quanto segue [create-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-domain-name.html)crea un nome di dominio personalizzato con TLS reciproco:
```
aws apigatewayv2 create-domain-name \
--domain-name api.example.com \
--domain-name-configurations CertificateArn=arn:aws:acm:us-west-2:123456789012:certificate/123456789012-1234-1234-1234-12345678 \
--mutual-tls-authentication TruststoreUri=s3://bucket-name/key-name
```
Dopo aver creato il nome di dominio, devi configurare i record DNS e le mappature del percorso di base per le operazioni API. Per ulteriori informazioni, consulta [Configurazione di un nome di dominio personalizzato regionale in Gateway API](apigateway-regional-api-custom-domain-create.md).
## Richiamo di un'API utilizzando un nome di dominio personalizzato che richiede l'autenticazione TLS reciproca.
Per richiamare un'API con l'autenticazione TLS reciproca abilitata, i client devono presentare un certificato attendibile nella richiesta API. Quando un client tenta di richiamare la tua API, API Gateway cerca l'emittente del certificato del client nel tuo truststore. Per permettere ad API Gateway di procedere con la richiesta, l'emittente del certificato e l'intera catena di attendibilità fino al certificato emesso da una CA root devono trovarsi nel truststore.
Il seguente comando `curl` di esempio seguente invia una richiesta `api.example.com,` che include `my-cert.pem` nella richiesta. `my-key.key` è la chiave privata del certificato.
```
curl -v --key ./my-key.key --cert ./my-cert.pem api.example.com
```
L'API viene richiamata solo se il truststore considera attendibile il certificato. Le seguenti condizioni impediranno ad API Gateway di eseguire l'handshake TLS e lo porteranno a negare la richiesta con il codice di stato `403`. Se il tuo certificato:
+ non è attendibile
+ è scaduto
+ non utilizza un algoritmo supportato
**Nota**
API Gateway non verifica se un certificato è stato revocato.
## Aggiornamento del truststore
Per aggiornare i certificati nel truststore, carica un nuovo bundle di certificati in Amazon S3. Potrai quindi aggiornare il nome di dominio personalizzato per utilizzare il certificato aggiornato.
Usa il [Controllo delle versioni di Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Versioning.html) per mantenere più versioni del truststore. Quando si aggiorna il nome di dominio personalizzato per utilizzare una nuova versione del truststore, API Gateway restituisce avvisi se i certificati non sono validi.
API Gateway produce avvisi di certificati solo quando si aggiorna il nome di dominio. API Gateway non invia notifiche se un certificato caricato in precedenza scade.
Il [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-domain-name.html)comando seguente aggiorna un nome di dominio personalizzato per utilizzare una nuova versione di truststore:
```
aws apigatewayv2 update-domain-name \
--domain-name api.example.com \
--domain-name-configurations CertificateArn=arn:aws:acm:us-west-2:123456789012:certificate/123456789012-1234-1234-1234-12345678 \
--mutual-tls-authentication TruststoreVersion='abcdef123'
```
## Disabilitazione dell'autenticazione TLS reciproca
Per disabilitare l'autenticazione TLS reciproca per un nome di dominio personalizzato, rimuovere il truststore dal nome di dominio personalizzato, come mostrato nel comando seguente.
Il [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-domain-name.html)comando seguente aggiorna un nome di dominio personalizzato per rimuovere il truststore dal nome di dominio personalizzato:
```
aws apigatewayv2 update-domain-name \
--domain-name api.example.com \
--domain-name-configurations CertificateArn=arn:aws:acm:us-west-2:123456789012:certificate/123456789012-1234-1234-1234-12345678 \
--mutual-tls-authentication TruststoreUri=''
```
## Risoluzione dei problemi relativi all'autenticazione TLS reciproca per l'API HTTP
Di seguito vengono forniti i consigli per la risoluzione dei problemi e la correzione degli errori che possono verificarsi durante l'attivazione dell'autenticazione TLS reciproca.
### Risoluzione dei problemi relativi agli avvisi dei certificati
Quando crei un nome di dominio personalizzato con l'autenticazione TLS reciproca, API Gateway genera avvisi se i certificati nel truststore non sono validi. Questo può verificarsi anche quando aggiorni un nome di dominio personalizzato all'utilizzo di un nuovo truststore. Gli avvisi indicano il problema con il certificato e l'oggetto del certificato che ha generato l'avviso. L'autenticazione TLS reciproca è ancora abilitata per l'API, ma alcuni client potrebbero non essere in grado di accedere all'API.
Per identificare il certificato che ha generato l'avviso, devi decodificare i certificati nel truststore. Puoi utilizzare strumenti come `openssl` per decodificare i certificati e identificarne gli oggetti.
Il comando seguente visualizza il contenuto di un certificato, incluso l'oggetto:
```
openssl x509 -in certificate.crt -text -noout
```
Aggiorna o rimuovi i certificati che hanno prodotto gli avvisi, quindi carica un nuovo truststore su Amazon S3. Dopo aver caricato il nuovo truststore, aggiorna il nome di dominio personalizzato per utilizzarlo.
### Risoluzione dei problemi relativi ai conflitti dei nomi di dominio
L'errore `"The certificate subject conflicts with an existing certificate from a different issuer."` indica che più autorità di certificazione hanno emesso un certificato per questo dominio. Per ogni oggetto del certificato, può esistere un solo emittente in API Gateway per domini TLS reciproci. Dovrai ottenere tutti i certificati per tale oggetto tramite un unico emittente. Se il problema riguarda un certificato di cui non hai il controllo ma puoi provare la proprietà del nome di dominio, [contatta Supporto](https://console.aws.amazon.com/support/cases#/create) per aprire un ticket.
### Risoluzione dei problemi relativi ai messaggi di stato dei nomi di dominio
`PENDING_CERTIFICATE_REIMPORT`: Ciò significa che hai reimportato un certificato in ACM e la convalida non è riuscita perché il nuovo certificato ha un SAN (nome alternativo del soggetto) che non è coperto dal `ownershipVerificationCertificate` o l'oggetto o SANs nel certificato non copre il nome di dominio. Potrebbe esserci una configurazione errata o è stato importato un certificato non valido. Devi reimportare un certificato valido in ACM. Per ulteriori informazioni sulla convalida, consulta [Convalida della proprietà del dominio](https://docs.aws.amazon.com/acm/latest/userguide/domain-ownership-validation.html).
`PENDING_OWNERSHIP_VERIFICATION`: significa che il certificato verificato in precedenza è scaduto e che ACM non è stato in grado di rinnovarlo in automatico. Dovrai rinnovare il certificato o richiederne uno nuovo. Ulteriori informazioni sul rinnovo del certificato si trovano nella guida alla [Risoluzione dei problemi relativi al rinnovo dei certificati gestiti di ACM](https://docs.aws.amazon.com/acm/latest/userguide/troubleshooting-renewal.html).
# Monitora HTTP APIs nell'API Gateway
Puoi utilizzare CloudWatch metriche e CloudWatch registri per monitorare HTTP. APIs Combinando log e parametri, puoi registrare gli errori e monitorare le prestazioni dell'API.
**Nota**
L'API Gateway potrebbe non generare log e parametri nei seguenti casi:
Errori 413 per richiesta troppo grande
Errori 429 per troppe richieste
Errori serie 400 per richieste inviate a un dominio personalizzato che non dispone del mapping API
Errori serie 500 per malfunzionamenti interni
**Topics**
+ [Monitoraggio delle metriche CloudWatch per API HTTP in Gateway API](http-api-metrics.md)
+ [Configurare la registrazione per HTTP APIs in API Gateway](http-api-logging.md)
# Monitoraggio delle metriche CloudWatch per API HTTP in Gateway API
È possibile monitorare l'esecuzione dell'API usando CloudWatch, che raccoglie i dati grezzi dall'API Gateway e li elabora trasformandoli in parametri leggibili quasi in tempo reale. Queste statistiche vengono registrate per un periodo di 15 mesi, per permettere l'accesso alle informazioni storiche e offrire una prospettiva migliore sulle prestazioni del servizio o dell'applicazione Web. Per impostazione predefinita, i dati dei parametri dell'API Gateway vengono inviati automaticamente a CloudWatch in periodi di un minuto. Per monitorare le metriche, creare un dashboard CloudWatch per l'API. Per ulteriori informazioni su come creare un dashboard CloudWatch, consultare l'argomento relativo alla [creazione di un dashboard CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/create_dashboard.html) nella *Guida per l'utente di Amazon CloudWatch*. Per ulteriori informazioni, consulta [Che cos'è Amazon CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/WhatIsCloudWatch.html) nella *Guida per l'utente di Amazon CloudWatch*.
I parametri seguenti sono supportati per API HTTP. Inoltre, puoi abilitare parametri dettagliati per scrivere parametri a livello di route in Amazon CloudWatch.
| Parametro | Descrizione |
| --- | --- |
| 4xx | Il numero di errori lato client catturati in un dato periodo. |
| 5xx | Il numero di errori lato server catturati in un dato periodo. |
| Conteggio | Il numero totale di richieste API in un dato periodo. |
| IntegrationLatency | Il tempo che intercorre tra il momento in cui API Gateway ritrasmette una richiesta al back-end e quando riceve da questo una risposta. |
| Latenza | Il tempo che intercorre tra il momento in cui API Gateway riceve una richiesta dal client e quando restituisce ad esso una risposta. La latenza include la latenza di integrazione e altri sovraccarichi dell'API Gateway. |
| DataProcessed | La quantità di dati elaborati in byte. |
Per filtrare i parametri di API Gateway, puoi utilizzare le dimensioni nella seguente tabella.
| Dimensione | Descrizione |
| --- | --- |
| ApiId | Filtra i parametri API Gateway per un'API con l'ID API specificato. |
| ApiId, Fase | Filtra i parametri API Gateway per una fase API con l'ID API e l'ID fase specificati. |
| ApiId, Metodo, Risorsa, Fase | Filtra le metriche di Gateway API per un metodo API con l'ID API, l'ID fase, il percorso della risorsa e l'ID instradamento specificati. API Gateway non invia questi parametri a meno che non siano stati abilitati esplicitamente parametri CloudWatch dettagliati. A questo scopo, richiama l'operazione [UpdateStage](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-stages-stagename.html) dell'API REST API Gateway V2 per aggiornare la proprietà `detailedMetricsEnabled` su `true`. In alternativa, puoi chiamare il comando [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-stage.html) della AWS CLI per aggiornare la proprietà `DetailedMetricsEnabled` a `true`. L'abilitazione di tali parametri comporta addebiti aggiuntivi sul tuo account. Per informazioni sui prezzi, consulta la pagina [Prezzi di Amazon CloudWatch](https://aws.amazon.com/cloudwatch/pricing/). |
# Configurare la registrazione per HTTP APIs in API Gateway
È possibile attivare la registrazione per scrivere i log nei registri. CloudWatch È possibile utilizzare [variabili di registrazione](http-api-logging-variables.md) per personalizzare il contenuto dei log.
Per migliorare il tuo livello di sicurezza, ti consigliamo di scrivere i log in CloudWatch Logs per tutte le fasi della tua API HTTP. Potrebbe essere necessario eseguire questa operazione per rispettare vari framework di conformità. Per ulteriori informazioni, consultare [Amazon API Gateway controls](https://docs.aws.amazon.com/securityhub/latest/userguide/apigateway-controls.html) nella *Guida per l’utente di AWS Security Hub *.
Per attivare la registrazione per un'API HTTP, è necessario effettuare le seguenti operazioni.
1. Assicurarsi che l'utente disponga delle autorizzazioni necessarie per attivare la registrazione.
1. Crea un gruppo di CloudWatch log Logs.
1. Fornisci l'ARN del gruppo di log CloudWatch Logs per una fase della tua API.
## Autorizzazioni per attivare la registrazione
Per attivare la registrazione per un'API, l'utente deve disporre delle seguenti autorizzazioni.
**Example**
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"logs:DescribeLogGroups",
"logs:DescribeLogStreams",
"logs:GetLogEvents",
"logs:FilterLogEvents"
],
"Resource": "arn:aws:logs:us-east-2:123456789012:log-group:*"
},
{
"Effect": "Allow",
"Action": [
"logs:CreateLogDelivery",
"logs:PutResourcePolicy",
"logs:UpdateLogDelivery",
"logs:DeleteLogDelivery",
"logs:CreateLogGroup",
"logs:DescribeResourcePolicies",
"logs:GetLogDelivery",
"logs:ListLogDeliveries"
],
"Resource": "*"
}
]
}
```
## Crea un gruppo di log e attiva la registrazione per HTTP APIs
È possibile creare un gruppo di log e attivare la registrazione degli accessi utilizzando Console di gestione AWS o il. AWS CLI
------
#### [ Console di gestione AWS ]
1. Creazione di un gruppo di log.
Per informazioni su come creare un gruppo di log utilizzando la console, consulta [Create a Log Group in Amazon CloudWatch Logs User Guide](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/Working-with-log-groups-and-streams.html).
1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Scegliere un'API HTTP.
1. Nella scheda **Monitor** (Monitoraggio) nel riquadro di navigazione principale, scegliere **Logging** (Registrazione).
1. Seleziona una fase per attivare la registrazione e scegliere **Select** (Seleziona).
1. Scegliere **Edit** (Modifica) per attivare la registrazione degli accessi.
1. Attiva la **registrazione degli accessi**, inserisci un CloudWatch registro e seleziona un formato di registro.
1. Scegli **Save** (Salva).
------
#### [ AWS CLI ]
Il [create-log-group](https://docs.aws.amazon.com/cli/latest/reference/logs/create-log-group.html)comando seguente crea un gruppo di log:
```
aws logs create-log-group --log-group-name my-log-group
```
Per attivare la registrazione, è necessario il nome della risorsa Amazon (ARN) del gruppo di log. Il formato ARN è arn:aws:logs: :log-group:. *region* *account-id* *log-group-name*
Il comando [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-stage.html) seguente attiva la registrazione dei log per la fase `$default` di un’API HTTP:
```
aws apigatewayv2 update-stage --api-id abcdef \
--stage-name '$default' \
--access-log-settings '{"DestinationArn": "arn:aws:logs:region:account-id:log-group:log-group-name", "Format": "$context.identity.sourceIp - - [$context.requestTime] \"$context.httpMethod $context.routeKey $context.protocol\" $context.status $context.responseLength $context.requestId"}'
```
------
## Formati di log di esempio
Esempi di formati di log di accesso comuni utilizzati con maggiore frequenza sono disponibili nella console API Gateway ed elencati come segue.
+ `CLF` ([Common Log Format](https://httpd.apache.org/docs/current/logs.html#common)):
```
$context.identity.sourceIp - - [$context.requestTime] "$context.httpMethod $context.routeKey $context.protocol" $context.status $context.responseLength $context.requestId $context.extendedRequestId
```
+ `JSON`:
```
{ "requestId":"$context.requestId", "ip": "$context.identity.sourceIp", "requestTime":"$context.requestTime", "httpMethod":"$context.httpMethod","routeKey":"$context.routeKey", "status":"$context.status","protocol":"$context.protocol", "responseLength":"$context.responseLength", "extendedRequestId": "$context.extendedRequestId" }
```
+ `XML`:
```
$context.identity.sourceIp $context.requestTime $context.httpMethod $context.routeKey $context.status $context.protocol $context.responseLength $context.extendedRequestId
```
+ `CSV` (valori separati da virgola):
```
$context.identity.sourceIp,$context.requestTime,$context.httpMethod,$context.routeKey,$context.protocol,$context.status,$context.responseLength,$context.requestId,$context.extendedRequestId
```
# Personalizzazione dei log degli accessi delle API HTTP
Puoi utilizzare le seguenti variabili per personalizzare i log di accesso per API HTTP. Per ulteriori informazioni sui log di accesso per HTTP APIs, consulta[Configurare la registrazione per HTTP APIs in API Gateway](http-api-logging.md).
| Parametro | Description |
| --- | --- |
| \$1context.accountId | L'ID dell' AWS account del proprietario dell'API. |
| \$1context.apiId | Identificatore assegnato da API Gateway all'API. |
| \$1context.authorizer.claims.property | Proprietà delle richieste restituite da JSON Web Token (JWT) dopo che il chiamante del metodo è stato autenticato correttamente, ad esempio `$context.authorizer.claims.username`. Per ulteriori informazioni, consulta [Controlla l'accesso a HTTP APIs con gli autorizzatori JWT in API Gateway](http-api-jwt-authorizer.md). La chiamata di `$context.authorizer.claims` restituisce null. |
| \$1context.authorizer.error | Il messaggio di errore restituito da un'autorizzazione. |
| \$1context.authorizer.property | Valore della coppia chiave/valore specificata della mappa `context` restituita da una funzione delle autorizzazioni Lambda di API Gateway. Ad esempio, se le autorizzazioni restituiscono la mappa `context` seguente: "context" : {
"key": "value",
"numKey": 1,
"boolKey": true
} chiamando `$context.authorizer.key` viene restituita la stringa `"value"`, chiamando `$context.authorizer.numKey` viene restituito `1` e chiamando `$context.authorizer.boolKey` viene restituito `true`. |
| \$1context.awsEndpointRequestId | L'ID della richiesta dell' AWS endpoint dall'`x-amzn-requestId`intestazione `x-amz-request-id` o. |
| \$1context.awsEndpointRequestId2 | L'ID della richiesta dell' AWS endpoint dall'intestazione. `x-amz-id-2` |
| \$1context.customDomain.basePathMatched | Il percorso per una mappatura API a cui corrisponde una richiesta in ingresso. Applicabile quando un client utilizza un nome di dominio personalizzato per accedere a un'API. Ad esempio, se un client invia una richiesta a `https://api.example.com/v1/orders/1234` e la richiesta corrisponde alla mappatura API con il percorso `v1/orders`, il valore è `v1/orders`. Per ulteriori informazioni, consulta [Mappatura delle fasi API a un nome di dominio personalizzato per le API HTTP](http-api-mappings.md). |
| \$1context.dataProcessed | La quantità di dati elaborati in byte. |
| \$1context.domainName | Nome di dominio completo usato per richiamare l'API. Deve essere lo stesso dell'intestazione `Host` in ingresso. |
| \$1context.domainPrefix | Prima etichetta di `$context.domainName`. |
| \$1context.error.message | Una stringa contenente un messaggio di errore API Gateway. |
| \$1context.error.messageString | Valore \$1context.error.message tra virgolette, ovvero "\$1context.error.message". |
| \$1context.error.responseType | Un tipo di `GatewayResponse`. Per ulteriori informazioni, consultare [Monitora l'esecuzione delle WebSocket API con CloudWatch metriche](apigateway-websocket-api-logging.md) e [Configurazione delle risposte del gateway per la personalizzazione delle risposte agli errori](api-gateway-gatewayResponse-definition.md#customize-gateway-responses). |
| \$1context.extendedRequestId | Equivalente a \$1context.requestId. |
| \$1context.httpMethod | Metodo HTTP usato. I valori validi sono: `DELETE`, `GET`, `HEAD`, `OPTIONS`, `PATCH`, `POST` e `PUT`. |
| \$1context.identity.accountId | L'ID AWS dell'account associato alla richiesta. Supportato per route che utilizzano l'autorizzazione IAM. |
| \$1context.identity.caller | Identificatore dell'entità principale dell'intermediario che ha firmato la richiesta. Supportato per route che utilizzano l'autorizzazione IAM. |
| \$1context.identity.cognitoAuthenticationProvider | Un elenco separato da virgole con tutti i provider di autenticazione Amazon Cognito utilizzati dal chiamante che effettua la richiesta. Disponibile solo se la richiesta è stata firmata con credenziali Amazon Cognito. Ad esempio, per un'identità di un pool di utenti Amazon Cognito, `cognito-idp. region.amazonaws.com/user_pool_id,cognito-idp.region.amazonaws.com/user_pool_id:CognitoSignIn:token subject claim` Per informazioni sui provider di autenticazione Amazon Cognito disponibili, consulta [Using Federated Identities](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-identity.html) nella *Guida per gli sviluppatori di Amazon Cognito*. |
| \$1context.identity.cognitoAuthenticationType | Tipo di autenticazione Amazon Cognito dell'intermediario da cui proviene la richiesta. Disponibile solo se la richiesta è stata firmata con credenziali Amazon Cognito. I valori possibili includono `authenticated` per le identità autenticate e `unauthenticated` per le identità non autenticate. |
| \$1context.identity.cognitoIdentityId | ID identità di Amazon Cognito dell'intermediario da cui proviene la richiesta. Disponibile solo se la richiesta è stata firmata con credenziali Amazon Cognito. |
| \$1context.identity.cognitoIdentityPoolId | ID pool di identità di Amazon Cognito dell'intermediario da cui proviene la richiesta. Disponibile solo se la richiesta è stata firmata con credenziali Amazon Cognito. |
| \$1context.identity.principalOrgId | L'[ID organizzazione AWS](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_org_details.html). Supportato per route che utilizzano l'autorizzazione IAM. |
| \$1context.identity.clientCert.clientCertPem | Certificato client codificato PEM che il client ha presentato durante l'autenticazione TLS reciproca. Presente quando un client accede a un'API utilizzando un nome di dominio personalizzato che ha attivato l'autenticazione TLS reciproca. |
| \$1context.identity.clientCert.subjectDN | Nome distinto dell'oggetto del certificato presentato da un client. Presente quando un client accede a un'API utilizzando un nome di dominio personalizzato che ha attivato l'autenticazione TLS reciproca. |
| \$1context.identity.clientCert.issuerDN | Nome distinto dell'approvatore del certificato presentato da un cliente. Presente quando un client accede a un'API utilizzando un nome di dominio personalizzato che ha attivato l'autenticazione TLS reciproca. |
| \$1context.identity.clientCert.serialNumber | Il numero di serie del certificato. Presente quando un client accede a un'API utilizzando un nome di dominio personalizzato che ha attivato l'autenticazione TLS reciproca. |
| \$1context.identity.clientCert.validity.notBefore | La data prima della quale il certificato non è valido. Presente quando un client accede a un'API utilizzando un nome di dominio personalizzato che ha attivato l'autenticazione TLS reciproca. |
| \$1context.identity.clientCert.validity.notAfter | La data dopo la quale il certificato non è valido. Presente quando un client accede a un'API utilizzando un nome di dominio personalizzato che ha attivato l'autenticazione TLS reciproca. |
| \$1context.identity.sourceIp | L'indirizzo IP di origine della connessione TCP immediata da cui proviene la richiesta all'endpoint di API Gateway. |
| \$1context.identity.user | Identificatore dell'entità principale dell'utente che sarà autorizzato per l'accesso alle risorse. Supportato per route che utilizzano l'autorizzazione IAM. |
| \$1context.identity.userAgent | Intestazione [https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent) del chiamante API. |
| \$1context.identity.userArn | Amazon Resource Name (ARN) dell'utente valido identificato dopo l'autenticazione. Supportato per route che utilizzano l'autorizzazione IAM. Per ulteriori informazioni, consulta [https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html). |
| \$1context.integration.error | Il messaggio di errore restituito da un'integrazione. Equivalente a \$1context.integrationErrorMessage. |
| \$1context.integration.integrationStatus | Per l'integrazione del proxy Lambda, il codice di stato restituito dal codice della funzione Lambda di backend AWS Lambda, non dal codice della funzione Lambda. |
| \$1context.integration.latency | Latenza di integrazione in ms. Equivalente a \$1context.integrationLatency. |
| \$1context.integration.requestId | L'ID della AWS richiesta dell'endpoint. Equivalente a \$1context.awsEndpointRequestId. |
| \$1context.integration.status | Il codice di stato restituito da un'integrazione. Per le integrazioni proxy Lambda, questo è il codice di stato restituito dal codice della funzione Lambda. |
| \$1context.integrationErrorMessage | Una stringa contenente un messaggio di errore di integrazione. |
| \$1context.integrationLatency | Latenza di integrazione in ms. |
| \$1context.integrationStatus | Per l'integrazione del proxy Lambda, questo parametro rappresenta il codice di stato restituito dalla funzione Lambda di backend AWS Lambda, non dalla funzione Lambda di backend. |
| \$1context.path | Percorso della richiesta. Ad esempio, /\$1stage\$1/root/child. |
| \$1context.protocol | Protocollo della richiesta, ad esempi, HTTP/1.1. API Gateway APIs può accettare richieste HTTP/2, ma API Gateway invia richieste alle integrazioni di backend utilizzando HTTP/1.1. Di conseguenza, il protocollo di richiesta viene registrato come HTTP/1.1 anche se un client invia una richiesta che utilizza HTTP/2. |
| \$1context.requestId | ID assegnato da API Gateway alla richiesta API. |
| \$1context.requestTime | Ora della richiesta in formato [CLF](https://httpd.apache.org/docs/current/logs.html#common) (dd/MMM/yyyy:HH:mm:ss \$1-hhmm). |
| \$1context.requestTimeEpoch | Ora della richiesta in formato [Unix epoch](https://en.wikipedia.org/wiki/Unix_time). |
| \$1context.responseLatency | Latenza della risposta in ms. |
| \$1context.responseLength | Lunghezza del payload della risposta in byte. |
| \$1context.routeKey | La chiave di route della richiesta API, ad esempio `/pets`. |
| \$1context.stage | La fase di distribuzione della richiesta API (ad esempio `beta` o `prod`). |
| \$1context.status | Stato della risposta del metodo. |
# Risoluzione dei problemi con le API HTTP in Gateway API
Negli argomenti seguenti vengono forniti suggerimenti per la risoluzione dei problemi relativi a errori e problemi che potrebbero verificarsi durante l'utilizzo di API HTTP.
**Topics**
+ [Risoluzione dei problemi relativi alle integrazione Lambda di API HTTP](http-api-troubleshooting-lambda.md)
+ [Risoluzione dei problemi relativi ai provider di autorizzazioni JWT per API HTTP](http-api-troubleshooting-jwt.md)
# Risoluzione dei problemi relativi alle integrazione Lambda di API HTTP
Di seguito vengono forniti consigli per la risoluzione di errori e problemi che potrebbero verificarsi durante l'utilizzo [AWS Lambda integrazioni](http-api-develop-integrations-lambda.md) con HTTP APIs.
## Problema: la mia API con un'integrazione Lambda restituisce `{"message":"Internal Server Error"}`
Per risolvere l'errore interno del server, aggiungere la `$context.integrationErrorMessage` [variabile di registrazione](http-api-logging-variables.md) al formato di registro e visualizzare i registri dell'API HTTP. Per raggiungere questo obiettivo, effettuare le seguenti operazioni:
**Per creare un gruppo di log utilizzando Console di gestione AWS**
1. Aprire la CloudWatch console all'indirizzo [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).
1. Scegliere **Gruppi di log**.
1. Scegliere **Crea gruppo di log**.
1. Immettere un nome di gruppo di log, quindi scegliere **Crea**.
1. Prendere nota del nome risorsa Amazon (ARN) per il tuo gruppo di log. Il formato ARN è arn:aws:logs: :log-group:. *region* *account-id* *log-group-name* È necessario il gruppo di log ARN per abilitare la registrazione degli accessi per la propria API HTTP.
**Per aggiungere la variabile di registrazione `$context.integrationErrorMessage`**
1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Scegliere l'API HTTP.
1. In **Monitor (Monitora)**, scegliere **Logging (Registrazione)**.
1. Selezionare una fase della tua API.
1. Scegliere **Modifica**, quindi abilitare la registrazione degli accessi.
1. Per **Log destination (Destinazione dei log)**, immettere l'ARN per il gruppo di log creato nel passaggio precedente.
1. Per **Formato registro**, scegliere **CLF**. Gateway API crea un formato di log di esempio.
1. Aggiungere `$context.integrationErrorMessage` alla fine del formato di registro.
1. Selezionare **Salva**.
**Per visualizzare i log delle API**
1. Generare i log Utilizzare un browser o `curl` per richiamare la tua API.
```
$curl https://api-id.execute-api.us-west-2.amazonaws.com/route
```
1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Scegliere l'API HTTP.
1. In **Monitor (Monitora)**, scegliere **Logging (Registrazione)**.
1. Selezionare la fase dell'API per la quale è stata abilitata la registrazione.
1. **Scegli Visualizza i log in. CloudWatch**
1. Scegliere il flusso di log più recente per visualizzare i log dell'API HTTP.
1. La voce di registro dovrebbe essere simile alla seguente:
![\[CloudWatch Registra la voce del registro che mostra il messaggio di errore di integrazione di Lambda.\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/troubleshoot-http-api-logs.png)
Poiché è stato aggiunto `$context.integrationErrorMessage` al formato di registro, viene visualizzato un messaggio di errore nei nostri registri che riassume il problema.
I registri potrebbero includere un messaggio di errore diverso che indica che si è verificato un problema con il codice della funzione Lambda. In tal caso, controllare il codice della funzione Lambda e verificare che la funzione Lambda restituisca una risposta nel [formato richiesto](http-api-develop-integrations-lambda.md#http-api-develop-integrations-lambda.response). Se i log non includono messaggi di errore, aggiungere `$context.error.message` e `$context.error.responseType` al formato del log per ottenere ulteriori informazioni per la risoluzione dei problemi.
In questo caso, i registri mostrano che API Gateway non disponeva delle autorizzazioni necessarie per richiamare la funzione Lambda.
Quando si crea un'integrazione Lambda nella console API Gateway, le autorizzazioni vengono configurate automaticamente per richiamare la funzione Lambda. Quando crei un'integrazione Lambda utilizzando, o un SDK AWS CLI CloudFormation, devi concedere le autorizzazioni ad API Gateway per richiamare la funzione. I comandi [add-permission](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html) seguenti forniscono l’autorizzazione a diversi instradamenti di API HTTP per invocare una funzione Lambda.
**Example Esempio: per la fase `$default` e l'instradamento `$default` di un'API HTTP**
```
aws lambda add-permission \
--function-name my-function \
--statement-id apigateway-invoke-permissions \
--action lambda:InvokeFunction \
--principal apigateway.amazonaws.com \
--source-arn "arn:aws:execute-api:us-west-2:123456789012:api-id/\$default/\$default"
```
**Example Esempio: per la fase `prod` e l'instradamento `test` di un'API HTTP**
```
aws lambda add-permission \
--function-name my-function \
--statement-id apigateway-invoke-permissions \
--action lambda:InvokeFunction \
--principal apigateway.amazonaws.com \
--source-arn "arn:aws:execute-api:us-west-2:123456789012:api-id/prod/*/test"
```
[Conferma la policy della funzione](https://docs.aws.amazon.com/lambda/latest/dg/access-control-resource-based.html) nella scheda **Permissions (Autorizzazioni)** della console Lambda.
Prova a richiamare nuovamente la tua API. Deve essere visualizzata la risposta della funzione Lambda.
# Risoluzione dei problemi relativi ai provider di autorizzazioni JWT per API HTTP
Di seguito vengono forniti consigli per la risoluzione di errori e problemi che potrebbero verificarsi durante l'utilizzo di autorizzatori JSON Web Token (JWT) con HTTP. APIs
## Problema: la mia API restituisce `401 {"message":"Unauthorized"}`
Controlla l'intestazione `www-authenticate` nella risposta dell'API.
Il comando seguente utilizza `curl` per inviare una richiesta a un'API con un autorizzatore JWT che utilizza `$request.header.Authorization` come origine identità.
```
$curl -v -H "Authorization: token" https://api-id.execute-api.us-west-2.amazonaws.com/route
```
La risposta dell'API include un'intestazione `www-authenticate`.
```
...
< HTTP/1.1 401 Unauthorized
< Date: Wed, 13 May 2020 04:07:30 GMT
< Content-Length: 26
< Connection: keep-alive
< www-authenticate: Bearer scope="" error="invalid_token" error_description="the token does not have a valid audience"
< apigw-requestid: Mc7UVioPPHcEKPA=
<
* Connection #0 to host api-id.execute-api.us-west-2.amazonaws.com left intact
{"message":"Unauthorized"}}
```
In questo caso, l'intestazione `www-authenticate` mostra che il token non è stato emesso per un pubblico valido. Per consentire ad API Gateway di autorizzare una richiesta, la richiesta `aud` o `client_id` di JWT deve corrispondere a una delle voci destinatario configurate per il provider di autorizzazioni. Gateway API convalida `client_id` solo se `aud` non è presente. Quando `aud` e `client_id` sono entrambi presenti, Gateway API valuta `aud`.
Puoi anche decodificare un JWT e verificare che corrisponda all'emittente, al pubblico e agli ambiti richiesti dall'API. Il sito web [jwt.io](https://jwt.io/) può eseguire il debug nel browser. JWTs La OpenID Foundation mantiene un [elenco di librerie con cui lavorare](https://openid.net/developers/jwt-jws-jwe-jwk-and-jwa-implementations/). JWTs
Per ulteriori informazioni sui provider di autorizzazioni JWT, consulta [Controlla l'accesso a HTTP APIs con gli autorizzatori JWT in API Gateway](http-api-jwt-authorizer.md).