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à.
# Nome di dominio personalizzato per REST pubblico APIs in API Gateway
*I nomi di dominio personalizzati* sono più semplici e intuitivi URLs che puoi fornire agli utenti delle tue 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* viene generato da API Gateway, *region* è la AWS regione e *stage* viene specificato dall'utente al momento della distribuzione 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
```
**Nota**
Per informazioni sui nomi di dominio personalizzati per uso privato APIs, consulta[Nomi di dominio personalizzati per uso privato APIs in API Gateway](apigateway-private-custom-domains.md).
## Considerazioni
Le seguenti considerazioni potrebbero influire sull’utilizzo di un nome di dominio personalizzato:
+ È possibile disabilitare l'endpoint predefinito per un'API. I client possono comunque connettersi all'endpoint predefinito, ma riceveranno un codice di stato `403 Forbidden`.
+ Un nome di dominio personalizzato regionale può essere associato a REST APIs e HTTP APIs. Puoi utilizzare [API Gateway versione 2 APIs](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/api-reference.html) per creare e gestire nomi di dominio personalizzati regionali per REST APIs.
+ Un nome di dominio personalizzato deve essere univoco all'interno di una regione per tutti gli AWS account.
+ È possibile eseguire la migrazione di un nome di dominio personalizzato tra endpoint ottimizzati per l'edge e regionali, ma non la migrazione di un dominio personalizzato pubblico a un nome di dominio personalizzato privato.
+ È 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](#wildcard-custom-domain-names).
+ Puoi scegliere una policy di sicurezza per il dominio personalizzato. Per ulteriori informazioni, consulta [Scegli una politica di sicurezza per il tuo dominio personalizzato in API Gateway](apigateway-custom-domain-tls-version.md).
+ Per configurare le mappature API con più livelli, è necessario utilizzare un nome di dominio personalizzato regionale e la policy di sicurezza TLS 1.2.
## Prerequisiti per i nomi di dominio personalizzati
Di seguito sono riportati i prerequisiti per la creazione di un nome di dominio personalizzato pubblico o privato. Per informazioni sui nomi di dominio personalizzati per uso privato APIs, consulta[Nomi di dominio personalizzati per uso privato APIs in API Gateway](apigateway-private-custom-domains.md).
### Registrare un nome di dominio
È necessario disporre di un nome di dominio Internet registrato per configurare nomi di dominio personalizzati per il tuo APIs. 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.
### Impostazione del certificato per il nome di dominio personalizzato
Prima di configurare un nome di dominio personalizzato per un'API, devi disporre di un SSL/TLS certificato pronto in ACM. Se ACM non è disponibile nella AWS regione in cui stai creando il tuo nome di dominio personalizzato, devi importare un certificato in API Gateway in quella regione.
Per importare un SSL/TLS certificato, devi fornire l'ente del SSL/TLS certificato in formato PEM, la relativa 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 utilizzare un certificato AWS gestito per un nome di dominio, è sufficiente fare riferimento al relativo ARN.
Se l'applicazione utilizza il blocco dei certificati, a volte noto come pinning SSL, per bloccare un certificato ACM, l'applicazione potrebbe non essere in grado di connettersi al dominio dopo il rinnovo del certificato. AWS 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.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` restituisce sottodomini quali `a.example.com`, `b.example.com` e `c.example.com`. Quando si crea il nome di dominio personalizzato con caratteri jolly, tutti i relativi sottodomini vengono instradati dalla modalità di routing del nome di dominio con caratteri jolly. Per indirizzare sottodomini verso diversi APIs, puoi effettuare una delle seguenti operazioni:
+ Utilizza le regole di routing per indirizzare le richieste in entrata verso destinazioni REST APIs diverse utilizzando `*.example.com` l'intestazione. `Host` Per ulteriori informazioni, consulta [Esempio 4: regole di routing per i nomi di dominio con caratteri jolly](rest-api-routing-rules-examples.md#rest-api-routing-rules-examples-rule-for-wildcard-domains).
+ Creare un nome di dominio per i sottodomini da instradare a un endpoint diverso. In un unico AWS account, puoi avere entrambi e. `*.example.com` `a.example.com`
È possibile utilizzare le variabili di contesto `$context.domainName` e `$context.domainPrefix` per determinare il nome di dominio utilizzato da un client per chiamare l'API. Per ulteriori informazioni sulle variabili di contesto, consulta [Variabili per le trasformazioni dei dati per Gateway API](api-gateway-mapping-template-reference.md).
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 puoi creare un nome di dominio personalizzato con caratteri jolly se un altro AWS account ha creato un nome di dominio personalizzato che è 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
Di seguito sono riportati i passaggi successivi per i nomi di dominio personalizzati.
**Fasi successive**
+ Per informazioni su come impostare il SSL/TLS certificato, consulta. [Prepara i certificati in AWS Certificate Manager](how-to-specify-certificate-for-custom-domain-name.md)
+ Per informazioni su come creare un dominio personalizzato regionale, consulta [Configurazione di un nome di dominio personalizzato regionale in Gateway API](apigateway-regional-api-custom-domain-create.md).
+ Per informazioni su come creare un dominio personalizzato ottimizzato per l'edge, consulta [Configurazione di un nome di dominio personalizzato ottimizzato per l'edge in Gateway API](how-to-edge-optimized-custom-domain-name.md).
+ Per informazioni su come eseguire la migrazione tra nomi di dominio personalizzati regionali e ottimizzati per l'edge, consulta [Migrazione di un nome di dominio personalizzato a un tipo di endpoint API diverso in Gateway API](apigateway-regional-api-custom-domain-migrate.md).
+ Per informazioni su come connettere le fasi API a un nome di dominio personalizzato, consulta [Invia traffico al tuo APIs tramite il tuo nome di dominio personalizzato in API Gateway](rest-api-routing-mode.md).
+ Per informazioni su come scegliere una policy di sicurezza per il dominio personalizzato, consulta [Scegli una politica di sicurezza per il tuo dominio personalizzato in API Gateway](apigateway-custom-domain-tls-version.md).
+ Per informazioni su come disattivare l'endpoint predefinito per il nome di dominio personalizzato, consulta [Disabilita l'endpoint predefinito per REST APIs](rest-api-disable-default-endpoint.md).
+ Per informazioni su come utilizzare i controlli dell'integrità di Route 53 per controllare il failover DNS da un'API di Gateway API, consulta [Configurazione dei controlli dell'integrità personalizzati per failover DNS per un'API di Gateway API](dns-failover.md).
Se è la prima volta che crei un nome di dominio personalizzato, ti consigliamo di iniziare con [Prepara i certificati in AWS Certificate Manager](how-to-specify-certificate-for-custom-domain-name.md), per specificare il certificato, quindi [Configurazione di un nome di dominio personalizzato regionale in Gateway API](apigateway-regional-api-custom-domain-create.md) per creare un nome di dominio personalizzato regionale.
# Prepara i certificati in AWS Certificate Manager
Prima di configurare un nome di dominio personalizzato per un'API, è necessario che sia già presente un certificato SSL/TLS in AWS Certificate Manager. Per ulteriori informazioni, consulta la [Guida per l'utente AWS Certificate Manager](https://docs.aws.amazon.com/acm/latest/userguide/).
## Considerazioni
Di seguito sono riportate le considerazioni relative al tuo SSL/TLS certificato.
+ Se crei un nome di dominio personalizzato ottimizzato per i dispositivi edge, API Gateway lo sfrutta per supportare i certificati per i nomi CloudFront di dominio personalizzati. Pertanto, i requisiti e i vincoli di un certificato di nome di dominio personalizzato sono dettati da. SSL/TLS [CloudFront](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/distribution-web-values-specify.html) La dimensione massima della chiave pubblica è ad esempio di 2048, mentre la dimensione della chiave privata può essere di 1024, 2048 e 4096. La dimensione della chiave pubblica è determinata dall'autorità di certificazione usata. Chiedi all'autorità di certificazione di restituire chiavi di dimensioni diverse dalla lunghezza predefinita. Per ulteriori informazioni, consulta [Accesso sicuro agli oggetti e Creazione di cookie](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/using-https.html) [firmati URLs e firmati](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/private-content-trusted-signers.html).
+ Se crei un nome di dominio personalizzato regionale, la dimensione massima della chiave pubblica è 2048.
+ Per usare un certificato ACM con un nome di dominio personalizzato regionale, devi richiedere o importare il certificato nella stessa Regione dell'API. Il certificato deve coprire il nome di dominio personalizzato.
+ Per usare un certificato ACM con un nome di dominio personalizzato ottimizzato per l'edge, devi richiedere o importare il certificato nella Regione Stati Uniti orientali (Virginia settentrionale) – `us-east-1`.
+ È necessario disporre di un nome di dominio registrato, ad esempio `example.com`. È possibile usare [Amazon Route 53](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/) o un registrar di dominio di terze parti accreditato. Per un elenco dei registrar, consulta la pagina [Accredited Registrar Directory](https://www.icann.org/en/accredited-registrars) nel sito Web ICANN.
## Per creare o importare un SSL/TLS certificato in ACM
Le seguenti procedure mostrano come creare o importare un SSL/TLS certificato per un nome di dominio.
------
#### [ To request a certificate provided by ACM for a domain name ]
1. Accedere alla [console AWS Certificate Manager](https://console.aws.amazon.com/acm).
1. Scegliere **Request a certificate (Richiedi un certificato)**.
1. Per **Tipo di certificato**, scegli **Richiedi un certificato pubblico**.
1. Scegli **Next (Successivo)**.
1. In **Nome di dominio completo**, immetti un nome di dominio personalizzato per la tua API, ad esempio `api.example.com`.
1. Facoltativamente, scegliere **Add another name to this certificate (Aggiungi un altro nome a questo certificato)**.
1. Per **Metodo di convalida**, scegli un metodo per convalidare la proprietà del dominio.
1. Per **Algoritmo chiave**, scegli un algoritmo di crittografia.
1. Scegli **Richiedi**.
1. Per una richiesta valida, un proprietario registrato del dominio Internet deve accettare la richiesta prima che ACM emetta il certificato. Se utilizzi Route 53 per gestire i record DNS pubblici, puoi aggiornarli direttamente tramite la console ACM.
------
#### [ To import into ACM a certificate for a domain name ]
1. Richiedi un SSL/TLS certificato con codifica PEM per il tuo nome di dominio personalizzato da un'autorità di certificazione. Per un elenco parziale di questi CAs, consulta [Mozilla](https://ccadb.my.salesforce-sites.com/mozilla/IncludedCACertificateReport) Included CA List.
1. Generare una chiave privata per il certificato e salvare l'output in un file usando il kit di strumenti [OpenSSL](https://www.openssl.org) disponibile nel sito Web OpenSSL:
```
openssl genrsa -out private-key-file 2048
```
1. Genera una richiesta di firma del certificato con la chiave privata generata in precedenza, usando OpenSSL:
```
openssl req -new -sha256 -key private-key-file -out CSR-file
```
1. Invia la richiesta di firma del certificato all'autorità di certificazione e salva il certificato risultante.
1. Scarica la catena di certificati dall'autorità di certificazione.
**Nota**
Se ottieni la chiave privata in un altro modo e la chiave è crittografata, puoi usare il comando seguente per decrittarla prima di inviarla ad API Gateway per la configurazione di un nome di dominio personalizzato.
```
openssl pkcs8 -topk8 -inform pem -in MyEncryptedKey.pem -outform pem -nocrypt -out MyDecryptedKey.pem
```
1. Carica il certificato su AWS Certificate Manager:
1. Accedere alla [console AWS Certificate Manager](https://console.aws.amazon.com/acm).
1. Seleziona **Import a certificate** (Importa un certificato).
1. Per **Corpo certificato**, inserisci il corpo del certificato server in formato PEM fornito dall'autorità di certificazione. Di seguito è illustrato un esempio abbreviato di tale certificato.
```
-----BEGIN CERTIFICATE-----
EXAMPLECA+KgAwIBAgIQJ1XxJ8Pl++gOfQtj0IBoqDANBgkqhkiG9w0BAQUFADBB
...
az8Cg1aicxLBQ7EaWIhhgEXAMPLE
-----END CERTIFICATE-----
```
1. Per **Chiave privata del certificato**, inserisci la chiave privata del certificato in formato PEM. Di seguito è illustrato un esempio abbreviato di tale chiave.
```
-----BEGIN RSA PRIVATE KEY-----
EXAMPLEBAAKCAQEA2Qb3LDHD7StY7Wj6U2/opV6Xu37qUCCkeDWhwpZMYJ9/nETO
...
1qGvJ3u04vdnzaYN5WoyN5LFckrlA71+CszD1CGSqbVDWEXAMPLE
-----END RSA PRIVATE KEY-----
```
1. Per **Catena di certificati**, inserisci i certificati intermedi in formato PEM e, facoltativamente, il certificato root, uno dopo l'altro senza righe vuote. Se includi il certificato root, la catena di certificati deve iniziare con i certificati intermedi e terminare con il certificato root. Usa i certificati intermedi forniti dall'autorità di certificazione. Non includere intermediari non presenti nella catena del percorso di trust. Di seguito è illustrato un esempio abbreviato.
```
-----BEGIN CERTIFICATE-----
EXAMPLECA4ugAwIBAgIQWrYdrB5NogYUx1U9Pamy3DANBgkqhkiG9w0BAQUFADCB
...
8/ifBlIK3se2e4/hEfcEejX/arxbx1BJCHBvlEPNnsdw8EXAMPLE
-----END CERTIFICATE-----
```
Ecco un altro esempio.
```
-----BEGIN CERTIFICATE-----
Intermediate certificate 2
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
Intermediate certificate 1
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
Optional: Root certificate
-----END CERTIFICATE-----
```
1. Scegli **Successivo** e di nuovo **Successivo**.
------
Dopo la creazione o l'importazione del certificato, prendi nota del relativo ARN. Sarà necessario in seguito per la configurazione del nome di dominio personalizzato.
# Configurazione di un nome di dominio personalizzato regionale in Gateway API
Usa un nome di dominio personalizzato regionale per creare un URL di base dell'API intuitivo. Con un nome di dominio personalizzato regionale, puoi mappare le fasi HTTP e REST API allo stesso nome di dominio personalizzato e utilizzare l'autenticazione TLS reciproca.
## Considerazioni
Di seguito sono riportate alcune considerazioni relative al nome di dominio personalizzato regionale:
+ Devi fornire un certificato ACM specifico della Regione. Il certificato deve trovarsi nella stessa Regione dell'API. Per ulteriori informazioni sulla creazione o il caricamento di un certificato di un nome di dominio personalizzato consulta [Prepara i certificati in AWS Certificate Manager](how-to-specify-certificate-for-custom-domain-name.md).
+ Quando si crea un nome di dominio personalizzato regionale (o si esegue la migrazione di uno di essi) con un certificato ACM, Gateway API crea un ruolo collegato ai servizi nel tuo account. Il ruolo collegato ai servizi è necessario per collegare il certificato ACM all'endpoint regionale. Il ruolo è denominato **AWSServiceRoleForAPIGateway** e sarà collegato alla policy gestita **APIGatewayServiceRolePolicy**. Per ulteriori informazioni sull'uso del ruolo collegato ai servizi, consulta [Utilizzo dei ruoli collegati ai servizi](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html).
+ Dopo aver creato il nome di dominio personalizzato regionale, è necessario creare un record DNS per far sì che il nome di dominio personalizzato punti al dominio regionale. Questo consente al traffico destinato al nome di dominio personalizzato di essere reindirizzato al nome host regionale dell'API.
Il record DNS può essere un record CNAME o un record alias A. Se si utilizza Route 53 come provider DNS, occorre creare un record di alias di tipo A. Se si utilizza un provider DNS di terze parti, occorre usare un record CNAME. Se si utilizza un record CNAME e si crea un endpoint VPC dell’interfaccia Gateway API con DNS privato abilitato per un’API privata, non è possibile risolvere il nome di dominio personalizzato all’interno del VPC che ospita l’API privata.
## Creazione di un nome di dominio personalizzato regionale
La procedura seguente mostra come creare un nome di dominio personalizzato regionale. Una volta completata questa procedura, si crea una regola di routing per instradare le fasi dell’API al nome di dominio personalizzato.
------
#### [ Console di gestione AWS ]
1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Scegliere **Custom Domain Names (Nomi di dominio personalizzati)** nel riquadro di navigazione principale.
1. Seleziona **Crea**.
1. In **Domain name (Nome di dominio)**, immettere un nome di dominio.
1. Per **Modalità di routing**, scegliere **Solo regole di routing**.
In questa modalità di routing, puoi inviare traffico dal tuo nome di dominio personalizzato al tuo solo utilizzando le regole di routing. APIs Per ulteriori informazioni, consulta [Invia traffico al tuo APIs tramite il tuo nome di dominio personalizzato in API Gateway](rest-api-routing-mode.md).
1. Per **Versione TLS minima**, seleziona una versione.
1. Sotto **Configurazione endpoint**, per **Tipo di endpoint API** scegli **Regionale**.
1. Scegliere un certificato ACM. Il certificato deve trovarsi nella stessa regione dell'API.
1. Scegli **Create** (Crea).
------
#### [ AWS CLI ]
Il [create-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-domain-name.html)comando seguente crea un nome di dominio personalizzato:
```
aws apigatewayv2 create-domain-name \
--domain-name 'regional.example.com' \
--domain-name-configurations CertificateArn=arn:aws:acm:us-west-2:123456789012:certificate/123456789012-1234-1234-1234-12345678 \
--routing-mode ROUTING_RULE_ONLY
```
L'output sarà simile al seguente:
```
{
"ApiMappingSelectionExpression": "$request.basepath",
"DomainName": "regional.example.com",
"DomainNameConfigurations": [
{
"ApiGatewayDomainName": "d-numh1z56v6.execute-api.us-west-2.amazonaws.com",
"CertificateArn": "arn:aws:acm:us-west-2:123456789012:certificate/123456789012-1234-1234-1234-12345678",
"DomainNameStatus": "AVAILABLE",
"EndpointType": "REGIONAL",
"HostedZoneId": "Z2OJLYMUO9EFXC",
"SecurityPolicy": "TLS_1_2"
}
"RoutingMode": "ROUTING_RULE_ONLY"
]
}
```
Il valore della proprietà `DomainNameConfigurations` restituisce il nome host dell'API regionale. Devi creare un record DNS per puntare il tuo nome di dominio personalizzato al nome del dominio regionale. Questo consente al traffico destinato al nome di dominio personalizzato di essere reindirizzato al nome host dell'API regionale.
------
## Creazione di una regola di routing per il nome di dominio personalizzato regionale
Dopo aver creato il tuo nome di dominio personalizzato, configuri il modo in cui il traffico viene instradato dal tuo nome di dominio personalizzato al tuo APIs. Poiché hai impostato la modalità di routing su`ROUTING_RULE_ONLY`, utilizzi le regole di routing per indirizzare le richieste in entrata dal tuo nome di dominio personalizzato al tuo. APIs
In questo esempio, si crea una regola catch-all che instrada a una fase dell’API tutte le richieste in entrata per il nome di dominio personalizzato. È anche possibile configurare le regole di routing in base a diverse condizioni di intestazione e percorso. Per ulteriori informazioni, consulta [Regole di routing per connettere le fasi dell'API a un nome di dominio personalizzato per REST APIs](rest-api-routing-rules.md).
------
#### [ Console di gestione AWS ]
1. Accedi 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.
1. Nella scheda **Dettagli di routing**, scegliere **Aggiungi una regola di routing**.
1. Scegliere **Aggiungi una nuova condizione** per aggiungere una nuova condizione.
1. Mantenere questa regola senza condizioni. In tal modo si instradano all’API di destinazione e alla fase di destinazione tutte le richieste per il nome di dominio personalizzato.
1. Per **Azione**, selezionare nel menu a discesa l’API e la fase di destinazione.
1. Scegli **Next (Successivo)**.
1. Nel campo Priorità, immettere **100**.
Gateway API valuta le regole in ordine di priorità, dal valore più basso a quello più alto. Poiché si tratta di una regola catch-all, si utilizza una priorità elevata in modo che Gateway API possa soddisfare qualsiasi regola aggiuntiva creata.
1. Scegliere **Crea una regola di routing**.
------
#### [ AWS CLI ]
Il comando `create-routing-rule` seguente crea una regola di routing catch-all:
```
aws apigatewayv2 create-routing-rule \
--domain-name 'regional.example.com' \
--priority 100 \
--conditions \
--actions '[{
"InvokeApi": {
"ApiId": "a1b2c3",
"Stage": "prod"
}
}]'
```
------
È possibile modificare la modalità di routing e creare nuove regole in qualsiasi momento. Per ulteriori informazioni, consulta [Invia traffico al tuo APIs tramite il tuo nome di dominio personalizzato in API Gateway](rest-api-routing-mode.md).
## Creazione di un record DNS per il nome di dominio personalizzato regionale
Dopo aver creato il nome di dominio personalizzato e le mappature dei percorsi di base, puoi creare un record DNS in modo che il nome di dominio personalizzato punti al nome di dominio regionale appena creato.
------
#### [ Console di gestione AWS ]
Per utilizzare il Console di gestione AWS, segui la documentazione di Route 53 sulla [configurazione di Route 53 per instradare il traffico verso API Gateway](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-api-gateway.html).
------
#### [ AWS CLI ]
Per configurare i record DNS in modo da mappare il nome di dominio personalizzato regionale al relativo nome host dell'ID della zona ospitata, crea innanzitutto un file JSON contenente la configurazione per configurare un record DNS per il nome di dominio regionale.
Il seguente `setup-dns-record.json` mostra come creare un record DNS `A` per mappare un nome di dominio personalizzato regionale (`regional.example.com`) al relativo nome host regionale (`d-numh1z56v6.execute-api.us-west-2.amazonaws.com`) fornito durante la creazione del nome di dominio personalizzato. Le proprietà `DNSName` e `HostedZoneId` di `AliasTarget` possono prendere rispettivamente i valori `regionalDomainName` e `regionalHostedZoneId` del nome di dominio personalizzato. Puoi anche ottenere la Regional Route 53 Hosted Zone IDs in [Amazon API Gateway Endpoints and Quotas](https://docs.aws.amazon.com/general/latest/gr/apigateway.html).
```
{
"Changes": [
{
"Action": "CREATE",
"ResourceRecordSet": {
"Name": "regional.example.com",
"Type": "A",
"AliasTarget": {
"DNSName": "d-numh1z56v6.execute-api.us-west-2.amazonaws.com",
"HostedZoneId": "Z2OJLYMUO9EFXC",
"EvaluateTargetHealth": false
}
}
}
]
}
```
Quanto segue [change-resource-record-sets](https://docs.aws.amazon.com/cli/latest/reference/route53/change-resource-record-sets.html)crea un record DNS per il tuo nome di dominio personalizzato regionale:
```
aws route53 change-resource-record-sets \
--hosted-zone-id Z2OJLYMUO9EFXC \
--change-batch file://path/to/your/setup-dns-record.json
```
Sostituisci `hosted-zone-id` con l'ID della zona ospitata di Route 53 del record DNS impostato nel tuo account. Il valore del parametro `change-batch` punta a un file JSON (*setup-dns-record.json*) in una cartella (*path/to/your*).
------
# Configurazione di un nome di dominio personalizzato ottimizzato per l'edge in Gateway API
Quando crei un nome di dominio personalizzato per un'API ottimizzata per l'edge, API Gateway configura una CloudFront distribuzione e un record DNS per mappare il nome di dominio API al CloudFront nome di dominio di distribuzione. Le richieste per l'API vengono quindi indirizzate ad API Gateway tramite la distribuzione mappata CloudFront . Questa mappatura è per le richieste API associate al nome di dominio personalizzato da indirizzare ad API Gateway tramite la distribuzione CloudFront mappata.
## Considerazioni
Di seguito sono riportate alcune considerazioni relative al nome di dominio personalizzato ottimizzato per l’edge:
+ Per configurare un nome di dominio personalizzato ottimizzato per i dispositivi periferici o per aggiornarne il certificato, è necessario disporre dell'autorizzazione per aggiornare le distribuzioni. CloudFront
Per aggiornare le distribuzioni sono necessarie le seguenti autorizzazioni: CloudFront
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AllowCloudFrontUpdateDistribution",
"Effect": "Allow",
"Action": [
"cloudfront:updateDistribution"
],
"Resource": [
"*"
]
}
]
}
```
------
+ È necessario richiedere o importare un certificato per il nome di dominio personalizzato ottimizzato per l'edge nella Regione Stati Uniti orientali (Virginia settentrionale) – `us-east-1`.
+ La CloudFront distribuzione creata da API Gateway è di proprietà di un account specifico della regione affiliato ad API Gateway. Quando si tracciano le operazioni per creare e aggiornare tale CloudFront distribuzione CloudTrail, è necessario utilizzare questo ID account API Gateway. Per ulteriori informazioni, consulta [Registra la creazione di un nome di dominio personalizzato CloudTrail](#how-to-custom-domain-log-cloudfront-distribution-update-in-cloudtrail).
+ API Gateway supporta nomi di dominio personalizzati ottimizzati per i dispositivi perimetrali sfruttando la Server Name Indication (SNI) sulla distribuzione. CloudFront Per ulteriori informazioni sull'utilizzo di nomi di dominio personalizzati su una CloudFront distribuzione, incluso il formato di certificato richiesto e la dimensione massima della lunghezza della chiave del certificato, consulta [Using Alternate Domain Names and HTTPS](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/using-https-alternate-domain-names.html) nella *Amazon CloudFront Developer Guide*
+ Affinché un nome di dominio personalizzato ottimizzato per l'edge sia pronto sono necessari circa 40 minuti.
+ Dopo aver creato il nome di dominio personalizzato ottimizzato per i dispositivi periferici, devi creare un record DNS per mappare il nome di dominio personalizzato al nome di distribuzione. CloudFront
## Creazione di un nome di dominio personalizzato ottimizzato per l'edge
La procedura seguente descrive come creare un nome di dominio personalizzato ottimizzato per l'edge per un'API.
------
#### [ Console di gestione AWS ]
1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Scegliere **Custom Domain Names (Nomi di dominio personalizzati)** nel riquadro di navigazione principale.
1. Scegli **Aggiungi nome di dominio**.
1. In **Domain name (Nome di dominio)**, immettere un nome di dominio.
1. **Per la modalità **Routing**, scegli \$1ONLY. API\$1MAPPING**
1. Per **Tipo di endpoint API**, scegli **Ottimizzato per l'edge**.
1. Scegliere una versione di TLS minima.
1. Scegliere un certificato ACM.
1. Scegli **Aggiungi nome di dominio**.
------
#### [ REST API ]
1. Chiamare [domainname:create](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateDomainName.html), specificando il nome di dominio personalizzato e l'ARN di un certificato archiviato in AWS Certificate Manager.
La chiamata API riuscita restituisce una `201 Created` risposta contenente l'ARN del certificato e il nome di CloudFront distribuzione associato nel relativo payload.
1. Annota il nome del dominio di CloudFront distribuzione mostrato nell'output. Ti servirà nel passaggio successivo per impostare il target dell'alias del record A del dominio personalizzato nel DNS.
Per esempi di codice di questa chiamata all'API REST, consulta [domainname:create](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateDomainName.html).
------
Un nome di dominio personalizzato ottimizzato per l'edge impiega circa 40 minuti per essere pronto, ma la console visualizza immediatamente il nome di dominio di CloudFront distribuzione associato, sotto forma di`distribution-id.cloudfront.net`, insieme all'ARN del certificato. Nel frattempo, puoi creare una mappatura del percorso di base o una regola di routing e quindi configurare l'alias del record DNS per mappare il nome di dominio personalizzato al nome di dominio di distribuzione associato. CloudFront
## Configurazione della mappatura del percorso di base di un'API con un nome di dominio personalizzato come nome host
Poiché la modalità di routing è impostata su`API_MAPPING_ONLY`, è possibile utilizzare la mappatura del percorso di base per utilizzare un singolo nome di dominio personalizzato come nome host di più nomi. APIs In questo modo, un'API è accessibile tramite la combinazione di nome di dominio personalizzato e percorso di base associato.
Ad esempio, se in Gateway API hai creato un'API denominata `PetStore` e un'altra denominata `Dogs` e hai configurato un nome di dominio personalizzato `api.example.com`, puoi impostare l'URL dell'API `PetStore` come `https://api.example.com`.
In questo modo, l'API `PetStore` viene associata al percorso di base di una stringa vuota. Se imposti l'URL dell'API `PetStore` come `https://api.example.com/PetStore`, l'API `PetStore` viene associata al percorso di base di `PetStore`. Puoi assegnare un percorso di base `MyDogList` per l'API `Dogs`. L'URL `https://api.example.com/MyDogList` è quindi l'URL root dell'API `Dogs`.
Per configurare le mappature delle API su più livelli, è possibile utilizzare solo un nome di dominio personalizzato regionale. I nomi di dominio personalizzati ottimizzati per l'edge non sono supportati. Per ulteriori informazioni, consulta [Usa le mappature delle API per connettere le fasi dell'API a un nome di dominio personalizzato per REST APIs](rest-api-mappings.md).
La procedura seguente consente di impostare le mappature dell'API per mappare percorsi dal nome di dominio personalizzato alle fasi API.
------
#### [ Console di gestione AWS ]
1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Seleziona **Custom Domain Names (Nomi di dominio personalizzati)** nel riquadro di navigazione principale della console API Gateway.
1. Scegliere un nome di dominio personalizzato.
1. Scegliere **Configure API mappings (Configura mappature API)**.
1. Scegliere **Add new mapping (Aggiungi nuova mappatura)**.
1. Specificare **API**, **Stage (Fase)** e **Path (Percorso)** (facoltativo) per la mappatura.
1. Scegli **Save** (Salva).
------
#### [ REST API ]
Richiamare [basepathmapping:create](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateBasePathMapping.html) su un nome di dominio personalizzato specifico, indicando le proprietà `basePath`, `restApiId` e `stage` della distribuzione nel payload della richiesta.
In caso di esito positivo, la chiamata API restituisce una risposta `201 Created`.
Per esempi di codice della chiamata all'API REST, consulta [basepathmapping:create](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateBasePathMapping.html).
------
Per una maggiore flessibilità su come indirizzare il traffico verso il proprio APIs, è possibile modificare la modalità di routing in `ROUTING_RULE_ONLY` o `ROUTING_RULE_THEN_API_MAPPING` e creare una regola di routing. Per ulteriori informazioni, consulta [Invia traffico al tuo APIs tramite il tuo nome di dominio personalizzato in API Gateway](rest-api-routing-mode.md).
## Creazione di un record DNS per il nome di dominio personalizzato ottimizzato per l'edge
Dopo aver avviato la creazione del nome di dominio personalizzato ottimizzato per l'edge, configura l'alias del record DNS.
Ti consigliamo di utilizzare Route 53 per creare un alias di record A per il tuo nome di dominio personalizzato e specificare il nome di dominio di CloudFront distribuzione come destinazione dell'alias. Ciò significa che Route 53 è in grado di instradare il nome di dominio personalizzato anche se si tratta di un apex di zona. Per ulteriori informazioni, consulta la pagina relativa alla [scelta tra set di record della risorsa alias e non alias](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/resource-record-sets-choosing-alias-non-alias.html) nella *Guida per gli sviluppatori di Amazon Route 53*.
Per istruzioni su Amazon Route 53, consulta [Instradamento del traffico a un'API Amazon API Gateway utilizzando il nome di dominio](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-api-gateway.html) nella *Guida per gli sviluppatori di Amazon Route 53*.
## Registra la creazione di un nome di dominio personalizzato CloudTrail
Quando CloudTrail è abilitato per la registrazione delle chiamate API Gateway effettuate dal tuo account, API Gateway registra gli aggiornamenti di CloudFront distribuzione associati quando viene creato o aggiornato un nome di dominio personalizzato per un'API. Questi log sono disponibili in `us-east-1`. Poiché queste CloudFront distribuzioni sono di proprietà di API Gateway, ognuna di queste CloudFront distribuzioni segnalate è identificata da uno dei seguenti account API Gateway specifici della regione, anziché dall'ID dell' IDsaccount del proprietario dell'API.
| **Region** | **ID account** |
| --- | --- |
| us-east-1 | 392220576650 |
| us-east-2 | 718770453195 |
| us-west-1 | 968246515281 |
| us-west-2 | 109351309407 |
| ca-central-1 | 796887884028 |
| eu-west-1 | 631144002099 |
| eu-west-2 | 544388816663 |
| eu-west-3 | 061510835048 |
| eu-central-1 | 474240146802 |
| eu-central-2 | 166639821150 |
| eu-north-1 | 394634713161 |
| eu-south-1 | 753362059629 |
| eu-south-2 | 359345898052 |
| ap-northeast-1 | 969236854626 |
| ap-northeast-2 | 020402002396 |
| ap-northeast-3 | 360671645888 |
| ap-southeast-1 | 195145609632 |
| ap-southeast-2 | 798376113853 |
| ap-southeast-3 | 652364314486 |
| ap-southeast-4 | 849137399833 |
| ap-south-1 | 507069717855 |
| ap-south-2 | 644042651268 |
| ap-east-1 | 174803364771 |
| sa-east-1 | 287228555773 |
| me-south-1 | 855739686837 |
| me-central-1 | 614065512851 |
## Rotazione di un certificato importato in ACM
ACM gestisce automaticamente il rinnovo dei certificati emessi. Non è necessario ruotare alcun certificato emesso da ACM per i nomi di dominio personalizzati. CloudFront lo gestisce per tuo conto.
Se tuttavia importi un certificato in ACM e lo usi per un nome di dominio personalizzato, devi ruotarlo prima della scadenza. A tale scopo, è necessario importare un nuovo certificato di terze parti per il nome di dominio e ruotare il certificato esistente in quello nuovo. Il processo deve essere ripetuto quando il nuovo certificato importato scade. In alternativa, puoi richiedere a ACM di emettere un nuovo certificato per il nome di dominio e ruotare il certificato esistente in quello nuovo emesso da ACM. Dopodiché, puoi lasciare ACM e CloudFront gestire automaticamente la rotazione dei certificati. Per creare o importare un nuovo certificato ACM, segui la procedura riportata in [Per creare o importare un SSL/TLS certificato in ACM](how-to-specify-certificate-for-custom-domain-name.md#how-to-specify-certificate-for-custom-domain-name-setup).
La procedura seguente descrive come ruotare un certificato per un nome di dominio.
**Nota**
Per ruotare un certificato importato in ACM sono necessari circa 40 minuti.
------
#### [ Console di gestione AWS ]
1. Richiedi o importa un certificato in ACM.
1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Seleziona **Custom Domain Names (Nomi di dominio personalizzati)** nel riquadro di navigazione principale della console API Gateway.
1. Scegli un nome di dominio personalizzato ottimizzato per l'edge.
1. Per **Configurazione endpoint** scegli **Modifica**.
1. Seleziona un certificato nell'elenco a discesa **Certificato ACM**.
1. Scegli **Salva** per iniziare la rotazione del certificato per il nome di dominio personalizzato.
------
#### [ REST API ]
Richiama l'operazione [domainname:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateDomainName.html) indicando l'ARN del nuovo certificato ACM per il nome di dominio specificato.
------
#### [ AWS CLI ]
Quanto segue [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-domain-name.html)aggiorna il certificato ACM per un nome di dominio ottimizzato per l'edge.
```
aws apigateway update-domain-name \
--domain-name edge.example.com \
--patch-operations "op='replace',path='/certificateArn',value='arn:aws:acm:us-east-2:111122223333:certificate/CERTEXAMPLE123EXAMPLE'"
```
Quanto segue [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-domain-name.html)aggiorna il certificato ACM per un nome di dominio regionale.
```
aws apigateway update-domain-name \
--domain-name regional.example.com \
--patch-operations "op='replace',path='/regionalCertificateArn',value='arn:aws:acm:us-east-2:111122223333:certificate/CERTEXAMPLE123EXAMPLE'"
```
------
## Chiamata dell’API con nomi di dominio personalizzati quando si utilizza una mappatura percorso di base
Chiamare un'API con un nome di dominio personalizzato equivale a chiamare l'API con il nome di dominio predefinito, a condizione che venga usato l'URL corretto.
Gli esempi seguenti confrontano e contrappongono un insieme di impostazioni personalizzate predefinite URLs e corrispondenti URLs di due APIs (`udxjef`e`qf3duz`) in una regione specificata (`us-east-1`) e di un determinato nome di dominio personalizzato (`api.example.com`).
| ID API | Fase | URL predefinito | Percorso di base | URL personalizzato |
| --- | --- | --- | --- | --- |
| udxjef | prod | https://udxjef.execute-api.us-east-1.amazonaws.com/prod | /petstore | https://api.example.com/negozio di animali |
| udxjef | tst | https://udxjef.execute-api.us-east-1.amazonaws.com/tst | /petdepot | https://api.example.com/petdepot |
| qf3duz | dev | https://qf3duz.execute-api.us-east-1.amazonaws.com/dev | /bookstore | https://api.example.com/libreria |
| qf3duz | tst | https://qf3duz.execute-api.us-east-1.amazonaws.com/tst | /bookstand | https://api.example.com/leggio |
Per una maggiore flessibilità su come indirizzare il traffico verso il tuo APIs, puoi creare una regola di routing. Per ulteriori informazioni, consulta [Invia traffico al tuo APIs tramite il tuo nome di dominio personalizzato in API Gateway](rest-api-routing-mode.md).
API Gateway supporta i nomi di dominio personalizzati per un'API usando [SNI (Server Name Indication, Indicazione nome server)](https://en.wikipedia.org/wiki/Server_Name_Indication). Puoi richiamare l'API con un nome di dominio personalizzato usando un browser o una libreria client che supporta SNI.
API Gateway applica SNI sulla CloudFront distribuzione. Per informazioni su come vengono CloudFront utilizzati i nomi di dominio personalizzati, consulta [Amazon CloudFront Custom SSL.](https://aws.amazon.com/cloudfront/custom-ssl-domains/)
# Migrazione di un nome di dominio personalizzato a un tipo di endpoint API diverso in Gateway API
Puoi eseguire la migrazione di un nome di dominio personalizzato tra endpoint ottimizzati per edge ed endpoint regionali. Non è possibile eseguire la migrazione di un nome di dominio personalizzato pubblico a un nome di dominio personalizzato privato. Aggiungi prima di tutto il nuovo tipo di configurazione dell'endpoint all'elenco `endpointConfiguration.types` esistente per il nome di dominio personalizzato. Configura quindi un record DNS in modo che il nome di dominio personalizzato punti all'endpoint di cui è appena stato effettuato il provisioning. Infine, si rimuove l’endpoint del nome di dominio personalizzato obsoleto.
## Considerazioni
Di seguito sono riportate alcune considerazioni relative alla migrazione del dominio personalizzato tra un endpoint API regionale e un endpoint API ottimizzato per l’edge:
+ Un nome di dominio personalizzato ottimizzato per l'edge richiede un certificato fornito da ACM della Regione Stati Uniti orientali (Virginia settentrionale), `us-east-1`. Questo certificato è distribuito un tutte le posizioni geografiche.
+ Un nome di dominio personalizzato regionale richiede un certificato fornito da ACM nella stessa Regione che ospita l'API. È possibile eseguire la migrazione di un nome di dominio personalizzato ottimizzato per l'edge che non si trova nella Regione `us-east-1` a un nome di dominio personalizzato regionale richiedendo un nuovo certificato ACM della Regione locale dell'API.
+ Per completare la migrazione tra un nome di dominio personalizzato ottimizzato per l'edge e un nome di dominio personalizzato regionale possono essere necessari fino a 60 secondi. Il tempo necessario per la migrazione dipende anche da quando si aggiornano i record DNS.
+ È possibile aggiungere una configurazione aggiuntiva dell'endpoint solo se la modalità di accesso all'endpoint è impostata su. `BASIC` Una volta che sono disponibili due configurazioni degli endpoint, non è possibile modificare la modalità di accesso agli endpoint. Per ulteriori informazioni, consulta [Modalità di accesso agli endpoint](apigateway-security-policies.md#apigateway-security-policies-endpoint-access-mode).
+ Se il nome di dominio personalizzato utilizza una politica di sicurezza che inizia con`SecurityPolicy_`, quando aggiungi un nuovo tipo di configurazione dell'endpoint, la modalità di accesso all'endpoint è la stessa per entrambi i tipi di endpoint e devi scegliere una policy di sicurezza che inizi con `SecurityPolicy_` per il nuovo tipo di configurazione dell'endpoint.
## Migrazione di nomi di dominio personalizzati
**Nota**
Per completare la migrazione, è necessario rimuovere l’endpoint obsoleto dal nome di dominio personalizzato.
La seguente procedura illustra come eseguire la migrazione di un nome di dominio personalizzato ottimizzato per l'edge a un nome di dominio personalizzato regionale.
------
#### [ Console di gestione AWS ]
1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Scegliere **Custom Domain Names (Nomi di dominio personalizzati)** nel riquadro di navigazione principale.
1. Scegli un nome di dominio personalizzato ottimizzato per l'edge.
1. Per **Configurazione endpoint** scegli **Modifica**.
1. Scegli **Aggiungi endpoint regionale**.
1. Per **Certificato ACM** scegli un certificato.
Il certificato regionale deve trovarsi nella stessa Regione dell'API regionale.
1. Scegli **Save changes** (Salva modifiche).
1. Configura un record DNS in modo che il nome di dominio personalizzato regionale punti al nome host regionale. Per ulteriori informazioni, consulta la [configurazione di Route 53 per instradare il traffico in Gateway API](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-api-gateway.html).
1. Dopo aver verificato che la configurazione DNS utilizza l'endpoint corretto, elimina la configurazione dell'endpoint ottimizzato per l'edge. Scegli il nome di dominio personalizzato, quindi per **Configurazione dell'endpoint (ottimizzato per edge)** seleziona **Elimina**.
1. Conferma la scelta ed elimina l'endpoint.
------
#### [ AWS CLI ]
Il [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-domain-name.html)comando seguente migra un nome di dominio personalizzato ottimizzato da edge a un nome di dominio personalizzato regionale:
```
aws apigateway update-domain-name \
--domain-name 'api.example.com' \
--patch-operations '[
{ "op":"add", "path": "/endpointConfiguration/types","value": "REGIONAL" },
{ "op":"add", "path": "/regionalCertificateArn", "value": "arn:aws:acm:us-west-2:123456789012:certificate/cd833b28-58d2-407e-83e9-dce3fd852149" }
]'
```
Il certificato regionale deve trovarsi nella stessa regione dell'API regionale.
L'output sarà simile al seguente:
```
{
"certificateArn": "arn:aws:acm:us-east-1:123456789012:certificate/34a95aa1-77fa-427c-aa07-3a88bd9f3c0a",
"certificateName": "edge-cert",
"certificateUploadDate": "2017-10-16T23:22:57Z",
"distributionDomainName": "d1frvgze7vy1bf.cloudfront.net",
"domainName": "api.example.com",
"endpointConfiguration": {
"types": [
"EDGE",
"REGIONAL"
]
},
"regionalCertificateArn": "arn:aws:acm:us-west-2:123456789012:certificate/cd833b28-58d2-407e-83e9-dce3fd852149",
"regionalDomainName": "d-fdisjghyn6.execute-api.us-west-2.amazonaws.com"
}
```
Per il nome di dominio personalizzato regionale migrato, la proprietà `regionalDomainName` risultante restituisce il nome host dell'API regionale. Devi configurare un record DNS in modo che il nome di dominio personalizzato regionale punti a questo nome host regionale. Questo consente al traffico destinato al nome di dominio personalizzato di essere instradato all'host regionale.
Dopo avere impostato il record DNS, è possibile rimuovere il nome di dominio personalizzato ottimizzato per l'edge. Il [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-domain-name.html)comando seguente rimuove il nome di dominio personalizzato ottimizzato per i bordi:
```
aws apigateway update-domain-name \
--domain-name api.example.com \
--patch-operations '[
{"op":"remove", "path":"/endpointConfiguration/types", "value":"EDGE"},
{"op":"remove", "path":"certificateName"},
{"op":"remove", "path":"certificateArn"}
]'
```
------
La procedura seguente mostra come migrare un nome di dominio personalizzato ottimizzato per i dispositivi periferici che utilizza una politica di sicurezza avanzata verso un nome di dominio personalizzato regionale che utilizza anche una politica di sicurezza avanzata.
------
#### [ Console di gestione AWS ]
1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Scegliere **Custom Domain Names (Nomi di dominio personalizzati)** nel riquadro di navigazione principale.
1. Scegli un nome di dominio personalizzato ottimizzato per l'edge.
1. Per **Configurazione endpoint** scegli **Modifica**.
1. Scegli **Aggiungi endpoint regionale**.
1. Per **Certificato ACM** scegli un certificato.
Il certificato regionale deve trovarsi nella stessa Regione dell'API regionale.
1. Per **Politica di sicurezza, scegli una politica** di sicurezza che inizi con. `SecurityPolicy_`
1. Per la **modalità di accesso Endpoint**, scegli **Basic**.
1. Scegli **Save changes** (Salva modifiche).
1. Configura un record DNS in modo che il nome di dominio personalizzato regionale punti al nome host regionale. Per ulteriori informazioni, consulta la [configurazione di Route 53 per instradare il traffico in Gateway API](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-api-gateway.html).
1. Dopo aver verificato che la configurazione DNS utilizza l'endpoint corretto, elimina la configurazione dell'endpoint ottimizzato per l'edge. Scegli il nome di dominio personalizzato, quindi per **Configurazione dell'endpoint (ottimizzato per edge)** seleziona **Elimina**.
1. Conferma la scelta ed elimina l'endpoint.
------
#### [ AWS CLI ]
Il [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-domain-name.html)comando seguente migra un nome di dominio personalizzato ottimizzato dai bordi in un nome di dominio personalizzato regionale:
```
aws apigateway update-domain-name \
--domain-name 'api.example.com' \
--patch-operations '[
{ "op":"add", "path": "/endpointConfiguration/types","value": "REGIONAL" },
{ "op":"replace", "path": "/securityPolicy", "value":"SecurityPolicy_TLS13_1_3_2025_09"},
{ "op":"add", "path": "/regionalCertificateArn", "value": "arn:aws:acm:us-west-2:123456789012:certificate/cd833b28-58d2-407e-83e9-dce3fd852149" }
]'
```
Il certificato regionale deve trovarsi nella stessa regione dell'API regionale.
L'output sarà simile al seguente:
```
{
"certificateArn": "arn:aws:acm:us-east-1:123456789012:certificate/34a95aa1-77fa-427c-aa07-3a88bd9f3c0a",
"certificateName": "edge-cert",
"certificateUploadDate": "2017-10-16T23:22:57Z",
"distributionDomainName": "d1frvgze7vy1bf.cloudfront.net",
"domainName": "api.example.com",
"endpointConfiguration": {
"types": [
"EDGE",
"REGIONAL"
]
},
"securityPolicy": "SecurityPolicy_TLS13_1_3_2025_09",
"endpointAccessMode": "BASIC",
"regionalCertificateArn": "arn:aws:acm:us-west-2:123456789012:certificate/cd833b28-58d2-407e-83e9-dce3fd852149",
"regionalDomainName": "d-fdisjghyn6.execute-api.us-west-2.amazonaws.com"
}
```
Per il nome di dominio personalizzato regionale migrato, la proprietà `regionalDomainName` risultante restituisce il nome host dell'API regionale. Devi configurare un record DNS in modo che il nome di dominio personalizzato regionale punti a questo nome host regionale. Questo consente al traffico destinato al nome di dominio personalizzato di essere instradato all'host regionale.
Dopo avere impostato il record DNS, è possibile rimuovere il nome di dominio personalizzato ottimizzato per l'edge. Il [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-domain-name.html)comando seguente rimuove il nome di dominio personalizzato ottimizzato per i bordi:
```
aws apigateway update-domain-name \
--domain-name api.example.com \
--patch-operations '[
{"op":"remove", "path":"/endpointConfiguration/types", "value":"EDGE"},
{"op":"remove", "path":"certificateName"},
{"op":"remove", "path":"certificateArn"}
]'
```
------
La seguente procedura mostra come eseguire la migrazione di un nome di dominio personalizzato regionale a un nome di dominio personalizzato ottimizzato per l'edge.
------
#### [ Console di gestione AWS ]
1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Nel pannello di navigazione principale, scegli **Nomi di dominio personalizzati**.
1. Scegli un nome di dominio personalizzato regionale.
1. Per **Configurazione endpoint** scegli **Modifica**.
1. Scegli **Aggiungi endpoint ottimizzato per edge**.
1. Per **Certificato ACM** scegli un certificato.
Il certificato di dominio ottimizzato per edge deve essere creato nella regione `us-east-1`.
1. Scegli **Save** (Salva).
1. Configura un record DNS in modo che il nome di dominio personalizzato ottimizzato per l'edge punti al nome host ottimizzato per l'edge. Per ulteriori informazioni, consulta la [configurazione di Route 53 per instradare il traffico in Gateway API](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-api-gateway.html).
1. Dopo aver verificato che la configurazione DNS utilizza l'endpoint corretto, elimina la configurazione dell'endpoint regionale. Scegli il nome di dominio personalizzato, quindi per **Configurazione dell'endpoint (regionale)** seleziona **Elimina**.
1. Conferma la scelta ed elimina l'endpoint.
------
#### [ AWS CLI ]
Il [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-domain-name.html)comando seguente migra il nome di dominio personalizzato regionale in un nome di dominio personalizzato ottimizzato per Edge:
```
aws apigateway update-domain-name \
--domain-name 'api.example.com' \
--patch-operations '[
{ "op":"add", "path": "/endpointConfiguration/types","value": "EDGE" },
{ "op":"add", "path": "/certificateName", "value": "edge-cert" },
{"op":"add", "path": "/certificateArn", "value": "arn:aws:acm:us-east-1:738575810317:certificate/34a95aa1-77fa-427c-aa07-3a88bd9f3c0a"}
]'
```
Il certificato di dominio ottimizzato per edge deve essere creato nella regione `us-east-1`.
L'output sarà simile al seguente:
```
{
"certificateArn": "arn:aws:acm:us-east-1:738575810317:certificate/34a95aa1-77fa-427c-aa07-3a88bd9f3c0a",
"certificateName": "edge-cert",
"certificateUploadDate": "2017-10-16T23:22:57Z",
"distributionDomainName": "d1frvgze7vy1bf.cloudfront.net",
"domainName": "api.example.com",
"endpointConfiguration": {
"types": [
"EDGE",
"REGIONAL"
]
},
"regionalCertificateArn": "arn:aws:acm:us-east-1:123456789012:certificate/3d881b54-851a-478a-a887-f6502760461d",
"regionalDomainName": "d-cgkq2qwgzf.execute-api.us-east-1.amazonaws.com"
}
```
Per il nome di dominio personalizzato specificato, API Gateway restituisce il nome host dell'API ottimizzata per l'edge come valore della proprietà `distributionDomainName`. Devi impostare un record DNS in modo che il nome di dominio personalizzato ottimizzato per i confini punti al nome di dominio di questa distribuzione. Questo consente al traffico destinato al nome di dominio personalizzato ottimizzato per gli edge di essere instradato al nome host dell'API ottimizzata per edge.
Dopo avere impostato il record DNS, è possibile rimuovere il tipo di endpoint `REGION` del nome di dominio personalizzato. Il [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-domain-name.html)comando seguente rimuove il tipo di endpoint regionale:
```
aws apigateway update-domain-name \
--domain-name api.example.com \
--patch-operations '[
{"op":"remove", "path":"/endpointConfiguration/types", value:"REGIONAL"},
{"op":"remove", "path":"regionalCertificateArn"}
]'
```
L'output sarà simile al seguente:
```
{
"certificateArn": "arn:aws:acm:us-east-1:738575810317:certificate/34a95aa1-77fa-427c-aa07-3a88bd9f3c0a",
"certificateName": "edge-cert",
"certificateUploadDate": "2017-10-16T23:22:57Z",
"distributionDomainName": "d1frvgze7vy1bf.cloudfront.net",
"domainName": "api.example.com",
"endpointConfiguration": {
"types": "EDGE"
}
}
```
------
# Invia traffico al tuo APIs tramite il tuo nome di dominio personalizzato in API Gateway
Quando configuri la modalità di routing per il tuo nome di dominio personalizzato, imposti il modo in cui il traffico in entrata viene indirizzato al tuo. APIs Invii traffico al tuo indirizzo APIs utilizzando regole di routing, mappature API o regole di routing e mappature API. La sezione seguente illustra quando utilizzare le regole di routing e le mappature API, nonché come impostare la modalità di routing per il nome di dominio personalizzato.
## Quando utilizzare le regole di routing
Quando si utilizzano le regole di routing, si indirizzano le richieste in entrata che soddisfano determinate condizioni verso fasi REST specifiche. APIs Ad esempio, una regola può instradare una richiesta alla fase `production` della REST API `users` se contiene l’intestazione `version:v1` e il percorso di base `/users`. Utilizza le regole di routing per creare topologie di routing dinamiche avanzate che supportino casi d'uso come i A/B test o l'aumento dell'utilizzo di nuove versioni del tuo. APIs
Quando si indirizza il traffico a una REST API, è consigliabile utilizzare le regole di routing per il nome di dominio personalizzato. È possibile creare nuovamente qualsiasi mappatura API utilizzando le regole di routing. Per ulteriori informazioni, consulta [Nuova creazione di una mappatura API utilizzando le regole di routing](rest-api-routing-rules-recreate-api-mapping.md).
Per REST APIs, puoi anche utilizzare insieme le regole di routing e le mappature delle API. Quando si usano insieme le regole di routing e le mappature API, Gateway API valuta sempre le regole di routing prima di qualsiasi mappatura API. Le regole di routing e le mappature API si utilizzano insieme per migrare gli attuali nomi di dominio personalizzati o per esplorare le regole di routing.
### Considerazioni sulle regole di routing
Le seguenti considerazioni potrebbero influire sull’utilizzo delle regole di routing:
+ WebSocket oppure HTTP APIs non sono supportati come destinazione APIs per le regole di routing.
+ Se il nome di dominio personalizzato presenta mappature API sia su REST che su HTTP APIs, le regole di routing non sono supportate.
+ È possibile creare una regola di routing di un dominio personalizzato privato per una REST API privata. È possibile creare una regola di routing di un dominio personalizzato pubblico per un’API regionale oppure ottimizzata per l’edge.
+ Non è possibile creare una regola di routing di un dominio personalizzato pubblico per un’API privata. Non è possibile creare una regola di routing di un nome di dominio personalizzato privato per un’API pubblica.
## Scelta tra regole di routing e mappature API
Quando possibile, è consigliabile utilizzare le regole di routing. Utilizza le mappature API solo per inviare traffico a un HTTP o a un'API. WebSocket
# Impostazione della modalità di routing per il nome di dominio personalizzato
Puoi scegliere la modalità di routing utilizzata da API Gateway per indirizzare il traffico verso il tuo APIs. Per ulteriori informazioni, consulta [Invia traffico al tuo APIs tramite il tuo nome di dominio personalizzato in API Gateway](rest-api-routing-mode.md). In questa sezione vengono illustrate le modalità di routing per i nomi di dominio personalizzati. Devi impostare una modalità di routing per il tuo nome di dominio personalizzato per indirizzare il traffico verso il tuo. APIs Sono supportate le seguenti modalità di routing:
+ **ROUTING\$1RULE\$1THEN\$1 API\$1MAPPING**: utilizza questa modalità per inviare traffico al tuo APIs con regole di routing e mappature API. In questa modalità, tutte le regole di routing hanno la priorità su qualsiasi mappatura API. Per un esempio di questa modalità, consultare [Esempio 2: regole di routing e mappature API](rest-api-routing-rules-examples.md#rest-api-routing-rules-examples-rule-and-mappings).
+ **ROUTING\$1RULE\$1ONLY: utilizza questa modalità per consentire solo alle regole** di routing di inviare traffico al tuo. APIs Quando il nome di dominio personalizzato utilizza questa modalità, non è possibile creare una mappatura delle API, ma è possibile utilizzare il comando per visualizzarla. [get-api-mappings](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/get-api-mappings.html) I chiamanti delle API non possono utilizzare le mappature API per accedere a questo nome di dominio.
+ **API\$1MAPPING\$1ONLY**: utilizza questa modalità per consentire solo alle mappature delle API di inviare traffico al tuo. APIs Quando il nome di dominio personalizzato usa questa modalità, non è possibile creare una regola di routing, ma è possibile utilizzare il comando `list-routing-rules` per visualizzarla. I chiamanti delle API non possono utilizzare le regole di routing per accedere a questo nome di dominio.
Questa è la modalità di routing predefinita per tutti i nomi di dominio esistenti e per tutti i nuovi nomi di dominio che vengono creati.
Quando si crea un nome di dominio personalizzato utilizzando `apigateway`, `API_MAPPING_ONLY` è chiamato `BASE_PATH_MAPPING_ONLY` e `ROUTING_RULE_THEN_API_MAPPING` è chiamato `ROUTING_RULE_THEN_BASE_PATH_MAPPING`. Questo comportamento è presente solo per AWS CLI, o qualsiasi CloudFormation SDKs, non in. Console di gestione AWS
La procedura seguente illustra come modificare la modalità di routing per un nome di dominio personalizzato esistente. Quando si modifica la modalità di routing del nome di dominio personalizzato, i chiamanti delle API non possono accedere al nome di dominio utilizzando una modalità di routing non supportata.
------
#### [ Console di gestione AWS ]
1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Scegliere **Custom Domain Names (Nomi di dominio personalizzati)** nel riquadro di navigazione principale.
1. Scegliere un nome di dominio personalizzato.
1. Per **Dettagli del dominio**, scegliere **Modifica**.
1. **Per la modalità **Routing, scegliete ROUTING\$1RULE\$1THEN\$1**. API\$1MAPPING**
1. Scegli **Save** (Salva).
Se si modifica la modalità di routing in `ROUTING_RULE_ONLY` o `API_MAPPING_ONLY`, tutte le mappature API o le regole di routing create vengono rimosse dalla pagina dei dettagli del nome di dominio della console. Se si modifica la modalità di routing per supportare regole di routing o mappature API, queste risorse torneranno a essere presenti nella pagina.
------
#### [ AWS CLI - apigatewayv2 ]
Il [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-domain-name.html)comando seguente aggiorna un nome di dominio per utilizzare la modalità di routing: `ROUTING_RULE_THEN_API_MAPPING`
```
aws apigatewayv2 update-domain-name \
--domain-name 'api.example.com' \
--routing-mode "ROUTING_RULE_THEN_API_MAPPING"
```
L'output sarà simile al seguente:
```
{
"ApiMappingSelectionExpression": "$request.basepath",
"DomainName": "api.example.com",
"DomainNameArn": "arn:aws:apigateway:us-west-2::/domainnames/api.example.com",
"DomainNameConfigurations": [
{
"ApiGatewayDomainName": "d-abcdefg.execute-api.us-west-2.amazonaws.com",
"CertificateArn": "arn:aws:acm:us-west-2:111122223333:certificate/abcdefg-123456-abcdefg",
"DomainNameStatus": "AVAILABLE",
"EndpointType": "REGIONAL",
"HostedZoneId": "Z2OJLYMUO9EFXC",
"SecurityPolicy": "TLS_1_2"
}
],
"RoutingMode": "ROUTING_RULE_THEN_API_MAPPING",
"Tags": {}
}
```
------
#### [ AWS CLI - apigateway ]
Il [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-domain-name.html)comando seguente aggiorna un nome di dominio personalizzato privato per utilizzare la modalità di routing: `ROUTING_RULE_THEN_BASE_PATH_MAPPING`
```
aws apigateway update-domain-name \
--domain-name 'private.example.com' \
--patch-operations "op='replace',path='/routingMode',value='ROUTING_RULE_THEN_BASE_PATH_MAPPING'"
```
L'output sarà simile al seguente:
```
{
"domainName": "private.example.com",
"domainNameId": "abcd1234",
"domainNameArn": "arn:aws:apigateway:us-west-2:111122223333:/domainnames/private.example.com+abcd1234",
"certificateArn": "arn:aws:acm:us-west-2:111122223333:certificate/a1b2c3d4-5678-90ab-cdef",
"certificateUploadDate": "2024-09-10T10:31:20-07:00",
"endpointConfiguration": {
"types": [
"PRIVATE"
],
"ipAddressType": "dualstack"
},
"domainNameStatus": "AVAILABLE",
"securityPolicy": "TLS_1_2",
"policy": "...",
"routingMode" : "ROUTING_RULE_THEN_BASE_PATH_MAPPING"
}
```
------
# Regole di routing per connettere le fasi dell'API a un nome di dominio personalizzato per REST APIs
Una regola di routing è un insieme di condizioni che, se soddisfatte, invocano un’azione. Ad esempio, una regola può instradare qualsiasi richiesta in entrata per un nome di dominio personalizzato che contiene l’intestazione `Hello:World` e il percorso di base `users` alla fase `production` di una REST API.
Le regole vengono valutate in ordine di priorità; impostando la modalità di routing su `ROUTING_RULE_THEN_API_MAPPING`, Gateway API valuta sempre tutte le regole di routing prima di valutare qualsiasi mappatura API. Di seguito viene illustrato come una regola di routing utilizza condizioni, azioni e priorità.
**Condizioni**
Quando le condizioni di una regola vengono soddisfatte, l'operazione viene eseguita. Gateway API supporta fino a due condizioni di intestazione e una condizione di percorso. Gateway API valuta insieme le condizioni di intestazione e le condizioni di percorso di base.
È possibile creare una regola senza condizioni. Quando Gateway API valuta questa regola, l’azione viene sempre eseguita. È possibile creare una regola senza condizioni come regola catch-all.
Per ulteriori informazioni sulle condizioni di intestazione, consultare [Corrispondenza delle condizioni di intestazione](#rest-api-routing-rules-condition-headers). Per ulteriori informazioni sulle condizioni di percorso, consultare [Corrispondenza delle condizioni di percorso di base](#rest-api-routing-rules-condition-path).
**Azioni**
Le azioni sono il risultato della corrispondenza delle condizioni a una regola di routing. Attualmente, l’unica azione supportata consiste nell’invocare una fase di una REST API.
Ogni regola può avere una sola azione.
**Priorità**
La priorità determina l’ordine in cui vengono valutate le regole, dal valore più basso a quello più alto. Le regole non possono avere la stessa priorità.
È possibile impostare la priorità su un valore compreso tra 1 e 1.000.000. Se una regola ha la priorità pari a uno, Gateway API la valuta per prima. Quando si crea una regola, è consigliabile aggiungere degli spazi vuoti nelle priorità. Questo approccio consente di cambiare la priorità delle regole e aggiungere nuove regole. Per ulteriori informazioni, consulta [Modifica della priorità di una regola di routing](apigateway-routing-rules-use.md#rest-api-routing-rules-change-priority).
Per esempi di come Gateway API valuta le regole di routing, consulta [Esempi di come Gateway API valuta le regole di routing](rest-api-routing-rules-examples.md).
## Tipi di condizione delle regole di routing di Gateway API
La sezione seguente illustra i tipi di condizione delle regole di routing. Gateway API soddisfa una regola solo se tutte le condizioni sono vere.
### Corrispondenza delle condizioni di intestazione
Quando si crea una condizione di intestazione, è possibile eseguire la corrispondenza al nome dell’intestazione e al valore glob dell’intestazione, ad esempio `Hello:World`. Gateway API utilizza una corrispondenza letterale per convalidare la corrispondenza delle condizioni di intestazione. La condizione può utilizzare fino a due intestazioni specificando `AND` tra loro. Ad esempio, la condizione può essere soddisfatta se una richiesta in entrata contiene `Hello:World` e `x-version:beta`.
La corrispondenza del nome dell’intestazione non fa distinzione tra maiuscole e minuscole, ma il valore glob dell’intestazione rispetta la distinzione tra maiuscole e minuscole. `Hello:World` corrisponde a `hello:World`, ma non a `Hello:world`.
Per l’elenco dei valori di intestazione con limitazioni, consultare [Restrizioni](#rest-api-routing-rules-restrictions).
#### Utilizzo di caratteri jolly con le condizioni di intestazione
È possibile utilizzare i caratteri jolly solo nel valore glob dell’intestazione e il carattere jolly deve essere `*prefix-match`, `suffix-match*` o `*contains*`. La tabella seguente mostra degli esempi su come utilizzare i caratteri jolly per la corrispondenza delle condizioni di intestazione.
| Condizioni di intestazione | Richieste che soddisfano la regola di routing | Richieste che non soddisfano la regola di routing |
| --- | --- | --- |
| `x-version: a*` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/rest-api-routing-rules.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/rest-api-routing-rules.html) |
| `x-version: *a` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/rest-api-routing-rules.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/rest-api-routing-rules.html) |
| `x-version: *a*` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/rest-api-routing-rules.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/rest-api-routing-rules.html) |
| `x-version: *a*` e `x-version: *b*` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/rest-api-routing-rules.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/rest-api-routing-rules.html) |
| `x-version: b*` e `x-version: *a` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/rest-api-routing-rules.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/rest-api-routing-rules.html) |
| `x-version: *` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/rest-api-routing-rules.html) | Nessuno |
Se si creano condizioni per più valori di intestazione, ad esempio `Accept:application/json,text/xml`, è consigliabile utilizzare `*contains*` per le condizioni di intestazione ed evitare di creare condizioni usando la virgola (`,`).
Poiché Gateway API utilizza una corrispondenza letterale per le condizioni di intestazione, le corrispondenze semantiche potrebbero essere instradate in modo diverso. La tabella riportata di seguito mostra la differenza dei risultati delle regole di routing.
| Condizioni di intestazione | Richieste che soddisfano la regola di routing | Richieste che non soddisfano la regola di routing |
| --- | --- | --- |
| `Accept: *json` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/rest-api-routing-rules.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/rest-api-routing-rules.html) |
| `Accept: *json*` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/rest-api-routing-rules.html) | Nessuno |
### Corrispondenza delle condizioni di percorso di base
Quando si crea una condizione di percorso di base, se la richiesta in entrata contiene il percorso specificato, la regola viene soddisfatta. La corrispondenza rispetta la distinzione tra maiuscole e minuscole, quindi il percorso `New/Users` non corrisponde a `new/users`.
È possibile creare una condizione di percorso di base per un solo percorso di base.
Per l’elenco delle condizioni di percorso di base con limitazioni, consultare [Restrizioni](#rest-api-routing-rules-restrictions).
#### Eliminazione del percorso di base con le condizioni di percorso base
Quando si crea una condizione del percorso base, è possibile scegliere di rimuovere il percorso base. Quando si elimina il percorso di base, Gateway API rimuove il percorso di base corrispondente in entrata quando invoca l’API di destinazione. Questo è lo stesso comportamento di quando si utilizza una mappatura API. Se non si elimina il percorso di base, Gateway API inoltra l’intero percorso di base all’API di destinazione. È consigliabile eliminare il percorso di base solo quando si crea nuovamente una mappatura API.
La tabella seguente mostra esempi di come Gateway API valuta la condizione di eliminazione del percorso di base.
| Condizione | Eliminazione del percorso di base | Richiesta in entrata | Risultato |
| --- | --- | --- | --- |
| Se il percorso di base contiene `PetStoreShopper/dogs` | True | `GET https://example.com/PetStoreShopper/dogs` | Gateway API chiama il metodo `GET` della risorsa `/`. |
| Se il percorso di base contiene `PetStoreShopper/dogs`. | False | `GET https://example.com/PetStoreShopper/dogs` | Gateway API chiama il metodo `GET` della risorsa `PetStoreShopper/dogs`. |
| Se il percorso di base contiene `PetStoreShopper` | True | `GET https://example.com/PetStoreShopper/dogs` | Gateway API chiama il metodo `GET` della risorsa `dogs`. |
| Se il percorso di base contiene `PetStoreShopper` | False | `GET https://example.com/PetStoreShopper/dogs` | Gateway API chiama il metodo `GET` della risorsa `PetStoreShopper/dogs`. |
| Se il percorso di base contiene `PetStoreShopper` | True | `GET https://example.com/PetStoreShopper?birds=available` | Gateway API chiama il metodo `GET` della risorsa `/` con il parametro della stringa di query `birds=available`. |
| Se il percorso di base contiene `PetStoreShopper` | False | `GET https://example.com/PetStoreShopper?birds=available` | Gateway API chiama il metodo `GET` della risorsa `/PetStoreShopper` con il parametro della stringa di query `birds=available`. |
## Restrizioni
+ L'API di destinazione e il nome di dominio personalizzato devono trovarsi nello stesso AWS account.
+ Ogni regola può avere una sola API di destinazione.
+ È possibile creare una regola di routing di un nome di dominio personalizzato privato per un’API privata e di un nome di dominio personalizzato pubblico per un’API pubblica. Non è possibile combinare insieme risorse pubbliche e private.
+ Se il nome di dominio personalizzato presenta mappature API sia su REST che su HTTP APIs, le regole di routing non sono supportate.
+ Il numero massimo per la priorità è 1.000.000.
+ Limitazioni di intestazione:
+ Ogni condizione `anyOf` può contenere un solo valore di intestazione.
+ Gli unici caratteri consentiti per i nomi delle intestazioni e i valori globali delle intestazioni sono specificati da [RFC 7230](https://datatracker.ietf.org/doc/html/rfc7230), ossia `a-z`, `A-Z`, `0-9` e i seguenti caratteri speciali: `*?-!#$%&'.^_`|~`.
+ È possibile utilizzare un carattere jolly nel valore glob dell’intestazione, ma deve essere `*prefix-match`, `suffix-match*` o `*contains*`. Non è possibile utilizzare `*` all’interno di un valore glob dell’intestazione.
+ I nomi delle intestazioni con caratteri jolly non sono supportati.
+ Il nome dell’intestazione non può contenere più di 40 caratteri.
+ Il valore glob dell’intestazione non può contenere più di 128 caratteri.
+ Il valore glob dell’intestazione per una corrispondenza infissa non può contenere più di 40 caratteri.
+ Le seguenti intestazioni non sono supportate come condizioni:
+ `access-control-*`
+ `apigw-*`
+ `Authorization`
+ `Connection`
+ `Content-Encoding`
+ `Content-Length`
+ `Content-Location`
+ `Forwarded`
+ `Keep-Alive`
+ `Origin`
+ `Proxy-Authenticate`
+ `Proxy-Authorization`
+ `TE`
+ `Trailers`
+ `Transfer-Encoding`
+ `Upgrade`
+ `x-amz-*`
+ `x-amzn-*`
+ `x-apigw-api-id`
+ `X-Forwarded-For`
+ `X-Forwarded-Host`
+ `X-Forwarded-Proto`
+ `x-restAPI`
+ `Via`
+ Limitazioni di percorso di base:
+ Il percorso di base non può contenere più di 128 caratteri.
+ Il percorso di base deve contenere solo lettere, numeri e i seguenti caratteri: `$-_.+!*'()/`.
Questi caratteri non sono supportati per le espressioni regolari (regex).
+ Il percorso di base non può iniziare né terminare con una barra rovesciata (`\`).
# Esempi di come Gateway API valuta le regole di routing
La sezione seguente illustra quattro esempi di come Gateway API valuta le regole di routing e le mappature API.
## Esempio 1: solo regole di routing
In questo esempio, il nome di dominio personalizzato `https://petstore.example.com` ha la modalità di routing impostata su `ROUTING_RULE_ONLY` con le regole di routing e le priorità riportate di seguito.
| ID della regola | Priorità | Condizioni | Azione |
| --- | --- | --- | --- |
| `abc123` | 10 | Se la richiesta contiene l’intestazione `Hello:World` | API di destinazione 1 |
| `zzz000` | 50 | Se la richiesta contiene le intestazioni `Accept:image/webp` e `Pet:Dog-*` e se il percorso di base contiene `PetStoreShopper` | API di destinazione 2 |
| `efg456` | 100 | Nessuno | API di destinazione 3 |
La tabella seguente mostra come Gateway API applica le regole di routing precedenti alle richieste di esempio.
| Richiesta | API selezionata | Spiegazione |
| --- | --- | --- |
| `https://petstore.example.com -h "Hello:World"` | API di destinazione 1 | La richiesta soddisfa la regola di routing `abc123`. |
| `https://petstore.example.com/PetStoreShopper -h "Hello:World", "Pet:Dog-Bella", "Accept:image/webp"` | API di destinazione 1 | Gateway API valuta tutte le regole di routing in ordine di priorità. La regola di routing `abc123` ha la priorità assoluta e le condizioni sono soddisfatte, quindi Gateway API invoca API di destinazione 1. Sebbene le condizioni della richiesta corrispondano anche alla regola di routing `zzz000`, Gateway API non valuta nessun’altra regola di routing dopo aver effettuato una corrispondenza. |
| `https://petstore.example.com/PetStoreShopper -h "Pet:Dog-Bella", "Accept:image/webp"` | API di destinazione 2 | La richiesta soddisfa la regola di routing `zzz000`. Questa è una corrispondenza perché la stringa `Pet:Dog-Bella` corrisponde a `Pet:Dog-*` |
| `https://petstore.example.com/PetStoreShopper -h "Pet:Dog-Bella"` | API di destinazione 3 | La richiesta non soddisfa la regola di routing `abc123`. La richiesta non soddisfa la regola di routing `zzz000` perché non sono presenti tutte le intestazioni necessarie. La regola di priorità successiva corrisponde a tutte le richieste in entrata, quindi Gateway API invoca API di destinazione 3. |
## Esempio 2: regole di routing e mappature API
In questo esempio, il nome di dominio personalizzato `https://petstore.diagram.example.com` ha la modalità di routing impostata su `ROUTING_RULE_THEN_API_MAPPING` e le seguenti regole di routing e mappature API.
| ID della regola | Priorità | Condizioni | Azione |
| --- | --- | --- | --- |
| `abc123` | 1 | Se la richiesta contiene `pets` | Invoca la fase `Prod` dell’API `PetStore`. |
| `000zzz` | 5 | Se la richiesta contiene l’intestazione `Cookie`:`*ux=beta*` e se il percorso di base contiene `/refunds` | Invoca la fase `Beta` dell’API `Refunds`. |
La tabella riportata di seguito mostra le mappature API per `https://petstore.backup.example.com`.
| Mappatura API | API selezionata |
| --- | --- |
| `/refunds` | Invoca la fase `Prod` dell’API `Refunds`. |
| `(none)` | Invoca la fase `Prod` dell’API `Search`. |
Il diagramma seguente mostra come Gateway API applica le regole di routing e le mappature API precedenti alle richieste di esempio. Le richieste di esempio sono riepilogate nella tabella che segue il diagramma.
![\[Diagramma di come Gateway API applica le regole di routing e le mappature API precedenti.\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/rr-diagram.png)
La tabella seguente mostra come Gateway API applica le regole di routing e le mappature API precedenti alle richieste di esempio.
| Richiesta | API selezionata | Spiegazione |
| --- | --- | --- |
| `https://petstore.diagram.com/pets` | La fase `Prod` dell’API `PetStore`. | La richiesta soddisfa la regola di routing `abc123`. |
| `https://petstore.diagram.example.com/refunds -h "Cookie:lang=en-us;ux=beta"` | La fase `Beta` dell’API `Refunds`. | La richiesta soddisfa la regola di routing `000zzz`. L’intestazione `Cookie` contiene la corrispondenza `*contains*` e la corrispondenza del percorso di base corrette per questa condizione. |
| `https://petstore.diagram.example.com/refunds` | La fase `Prod` dell’API `Refunds`. | La richiesta non ha le intestazioni necessarie per soddisfare la regola di routing `zzz000`. Se Gateway API non riesce a soddisfare correttamente una regola di routing, utilizza le mappature API. Gateway API può mappare il percorso di base alla fase `Prod` dell’API `Refunds`. |
| `https://petstore.diagram.example.com/` | La fase `Prod` dell’API `Search`. | La richiesta esegue la corrispondenza della mappatura API al percorso vuoto `(none)`. |
## Esempio 3: regole di routing e mappature API con più livelli
In questo esempio, il nome di dominio personalizzato `https://petstore.backup.example.com` ha la modalità di routing impostata su `ROUTING_RULE_THEN_API_MAPPING` e le seguenti regole di routing e mappature API.
La tabella seguente mostra le regole di routing per `https://petstore.backup.example.com`.
| ID della regola | Priorità | Condizioni | Azione |
| --- | --- | --- | --- |
| `abc123` | 10 | Se la richiesta contiene l’intestazione `Hello:World` | API di destinazione 1 |
| `000zzz` | 50 | Se la richiesta contiene le intestazioni `Accept`:`image/webp` e `Pet:Dog-*` e se il percorso di base contiene `PetStoreShopper` | API di destinazione 2 |
La tabella riportata di seguito mostra le mappature API per `https://petstore.backup.example.com`.
| Mappatura API | API selezionata |
| --- | --- |
| `PetStoreShopper` | API di destinazione 3 |
| `PetStoreShopper/cats` | API di destinazione 4 |
La tabella seguente mostra come Gateway API applica le regole di routing e le mappature API precedenti alle richieste di esempio.
| Richiesta | API selezionata | Spiegazione |
| --- | --- | --- |
| `https://petstore.example.com/PetStoreShopper -h "Accept:image/webp", "Pet:Cats" ` | API di destinazione 3 | La richiesta non ha le intestazioni necessarie per soddisfare la regola di routing `zzz000`. Se Gateway API non riesce a soddisfare correttamente una regola di routing, utilizza le mappature API. Gateway API può mappare il percorso di base all’API di destinazione 3. |
| `https://petstore.example.com/PetStoreShopper/cats -h "Hello:World"` | API di destinazione 1 | La richiesta soddisfa la regola di routing `abc123`. Se la modalità di routing è impostata su `ROUTING_RULE_THEN_API_MAPPING`, le regole di routing hanno sempre la priorità sulle mappature API. |
| `https://petstore.example.com/Admin -h "Pet:Dog-Bella"` | Nessuno | La richiesta non soddisfa nessuna regola di routing o mappatura API. Poiché non esiste una regola di routing predefinita, Gateway API rifiuta la chiamata e invia al chiamante un codice di stato `403 Forbidden`. |
## Esempio 4: regole di routing per i nomi di dominio con caratteri jolly
In questo esempio, il nome di dominio personalizzato `https://*.example.com` è un nome di dominio con caratteri jolly. Il carattere jolly supporta tutti i sottodomini che vengono instradati nuovamente allo stesso dominio. L'esempio seguente di regole di routing modifica questo comportamento per consentire ai sottodomini di indirizzarsi verso destinazioni diverse APIs utilizzando l'intestazione. `Host`
La tabella seguente mostra le regole di routing per `https://*.example.com`.
| ID della regola | Priorità | Condizioni | Azione |
| --- | --- | --- | --- |
| `abc123` | 10 | Se la richiesta contiene l’intestazione `Host:a.example.com` | API di destinazione 1 |
| `000zzz` | 50 | Se la richiesta contiene l’intestazione `Host:b.example.com` | API di destinazione 2 |
| `efg456` | 500 | Nessuno | API di destinazione 3 |
La tabella seguente mostra come Gateway API applica le regole di routing precedenti alle richieste di esempio.
| Richiesta | API selezionata | Spiegazione |
| --- | --- | --- |
| `https://a.example.com` | API di destinazione 1 | L’intestazione `Host` è `a.example.com`. Questa richiesta soddisfa la regola di routing `abc123`. |
| `https://b.example.com` | API di destinazione 2 | L’intestazione `Host` è `b.example.com`. Questa richiesta soddisfa la regola di routing `000zzz`. |
| `https://testing.example.com` | API di destinazione 3 | Questa richiesta soddisfa la regola di routing catch-all `efg456`. |
# Come utilizzare le regole di routing
Puoi creare una regola di routing utilizzando o qualsiasi AWS SDK. Console di gestione AWS AWS CLI Dopo aver creato una regola, è possibile modificarne la priorità.
## Creazione di una regola di routing
La procedura seguente mostra come creare una regola di routing per un nome di dominio personalizzato con la modalità di routing impostata su `ROUTING_RULE_THEN_API_MAPPING` o `ROUTING_RULE_ONLY`.
------
#### [ Console di gestione AWS ]
1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Scegliere **Custom Domain Names (Nomi di dominio personalizzati)** nel riquadro di navigazione principale.
1. Scegliere un nome di dominio personalizzato.
1. Nella scheda **Dettagli di routing**, scegliere **Aggiungi una regola di routing**.
1. Scegliere **Aggiungi una nuova condizione** per aggiungere una nuova condizione.
È possibile aggiungere una condizione di intestazione o di percorso di base. Per eseguire la corrispondenza di tutte le richieste in entrata al nome di dominio personalizzato, non aggiungere condizioni.
1. Per **Azione**, selezionare nel menu a discesa l’API e la fase di destinazione.
1. Scegli **Next (Successivo)**.
1. Nel campo Priorità, immettere un numero per la priorità.
Gateway API valuta le regole in ordine di priorità, dal valore più basso a quello più alto.
Se si crea una regola senza condizioni, è consigliabile utilizzare una priorità con valore elevato.
1. Scegliere **Crea una regola di routing**.
------
#### [ AWS CLI ]
Il [create-routing-rule](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-routing-rule.html)comando seguente crea una regola di routing con una priorità di 50. In questo esempio, Gateway API instrada tutte le richieste in entrata che hanno le intestazioni `Hello:World` e `x-version:beta` e il percorso di base `PetStoreShopper` all’API di destinazione `a1b2c3`.
```
aws apigatewayv2 create-routing-rule \
--domain-name 'api.example.com' \
--priority 50 \
--conditions '[
{
"MatchHeaders": {
"AnyOf": [
{
"Header": "Hello",
"ValueGlob": "World"
}
]
}
},
{
"MatchHeaders": {
"AnyOf": [
{
"Header": "x-version",
"ValueGlob": "beta"
}
]
}
},
{
"MatchBasePaths": {
"AnyOf": [
"PetStoreShopper"
]
}
}
]'\
--actions '[
{
"InvokeApi": {
"ApiId": "a1b2c3",
"Stage": "prod"
}
}
]'
```
L'output sarà simile al seguente.
```
{
"Actions": [
{
"InvokeApi": {
"ApiId": "a1b2c3",
"Stage": "prod",
"StripBasePath": false
}
}
],
"Conditions": [
{
"MatchHeaders": {
"AnyOf": [
{
"Header": "Hello",
"ValueGlob": "World"
}
]
}
},
{
"MatchHeaders": {
"AnyOf": [
{
"Header": "x-version",
"ValueGlob": "beta"
}
]
}
},
{
"MatchBasePaths": {
"AnyOf": [
"PetStoreShopper"
]
}
}
],
"Priority": 50,
"RoutingRuleArn": "arn:aws:apigateway:us-west-2:111122223333:/domainnames/api.example.com/routingrules/abc123",
"RoutingRuleId": "abc123"
}
```
------
## Modifica della priorità di una regola di routing
È possibile modificare la priorità di una regola di routing. La modifica ha effetto immediato e potrebbe influire sul modo in cui gli utenti delle API invocano i nomi di dominio personalizzati. Quando si impostano le priorità delle regole di routing, è consigliabile lasciare degli spazi vuoti tra le regole.
Ad esempio, si considerino due regole di routing, una regola `abc123` con la priorità 50 e una regola `zzz000` con la priorità 150. Per modificare la priorità delle regole in modo che Gateway API valuti prima la regola `zzz000`, è possibile impostare la priorità della regola `zzz000` su 30.
------
#### [ Console di gestione AWS ]
1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Scegliere **Custom Domain Names (Nomi di dominio personalizzati)** nel riquadro di navigazione principale.
1. Scegliere un nome di dominio personalizzato.
1. Nella scheda **Dettagli di routing**, scegliere la regola di routing, quindi scegliere **Modifica**.
1. Scegli **Next (Successivo)**.
1. Per Priorità, immettere la nuova priorità.
1. Scegli **Save changes** (Salva modifiche).
------
#### [ AWS CLI ]
Il [put-routing-rule](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/put-routing-rule.html)comando seguente modifica la priorità di una regola di routing. `abc123`
```
aws apigatewayv2 put-routing-rule \
--domain-name 'api.example.com' \
--priority 30 \
--routing-rule-id abc123 \
--conditions '[
{
"MatchHeaders": {
"AnyOf": [
{
"Header": "Hello",
"ValueGlob": "World"
}
]
}
},
{
"MatchHeaders": {
"AnyOf": [
{
"Header": "x-version",
"ValueGlob": "beta"
}
]
}
},
{
"MatchBasePaths": {
"AnyOf": [
"PetStoreShopper"
]
}
}
]'\
--actions '[
{
"InvokeApi": {
"ApiId": "a1b2c3",
"Stage": "prod"
}
}
]'
```
L'output sarà simile al seguente:
```
{
"Actions": [
{
"InvokeApi": {
"ApiId": "a1b2c3",
"Stage": "prod",
"StripBasePath": false
}
}
],
"Conditions": [
{
"MatchHeaders": {
"AnyOf": [
{
"Header": "Hello",
"ValueGlob": "World"
}
]
}
},
{
"MatchHeaders": {
"AnyOf": [
{
"Header": "x-version",
"ValueGlob": "beta"
}
]
}
},
{
"MatchBasePaths": {
"AnyOf": [
"PetStoreShopper"
]
}
}
],
"Priority": 38,
"RoutingRuleArn": "arn:aws:apigateway:us-west-2:111122223333:/domainnames/api.example.com/routingrules/abc123",
"RoutingRuleId": "abc123"
}
```
------
# Nuova creazione di una mappatura API utilizzando le regole di routing
È possibile creare nuovamente una mappatura API utilizzando le regole di routing. Per creare nuovamente una mappatura API, è necessario attivare l’eliminazione del percorso di base. Questo approccio preserva il comportamento delle mappature API. Per ulteriori informazioni, consulta [Eliminazione del percorso di base con le condizioni di percorso base](rest-api-routing-rules.md#rest-api-routing-rules-condition-path-split).
Il seguente tutorial mostra come creare nuovamente la mappatura API `https:// api.example.com/orders/v2/items/categories/5` come regola di routing e come aggiornare i log di accesso per registrare l’ID della regola di routing che Gateway API utilizza per inviare il traffico all’API.
------
#### [ Console di gestione AWS ]
**Per impostare la modalità di routing su ROUTING\$1RULE\$1THEN\$1 API\$1MAPPING**
1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Scegliere **Custom Domain Names (Nomi di dominio personalizzati)** nel riquadro di navigazione principale.
1. Scegliere il nome di dominio personalizzato.
1. Per **Dettagli del dominio**, scegliere **Modifica**.
1. **Per la modalità **Routing, scegliete ROUTING\$1RULE\$1THEN\$1**. API\$1MAPPING**
1. Seleziona **Salva**
Dopo aver impostato la modalità di routing, si crea la regola di routing.
**Per creare la regola di routing**
1. Nella scheda **Dettagli di routing**, scegliere **Aggiungi una regola di routing**.
1. Scegliere **Aggiungi una nuova condizione** e quindi scegliere **Percorso**.
1. Per **Percorso**, immettere **orders/v2/items/categories/5**.
1. Per **Percorso base della striscia**, scegliere **Attivo**.
1. Per **API di destinazione**, scegliere l’API di destinazione desiderata.
1. Per **Fase di destinazione**, scegliere la fase di destinazione desiderata.
1. Scegli **Next (Successivo)**.
1. Per Priorità, immettere una priorità.
Anche se si mantiene la mappatura API esistente, Gateway API utilizzerà sempre la nuova regola di routing poiché le regole di routing hanno sempre la priorità sulle mappature API.
1. Scegli **Save changes** (Salva modifiche).
Dopo aver creato la regola di routing, si aggiorna il formato del log di accesso per la fase o si crea un nuovo log per verificare che Gateway API utilizzi la regola di routing per inviare traffico all’API.
**Per aggiornare i log di accesso**
1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Scegliere l'API.
1. Nel riquadro di navigazione principale scegli **Fasi**.
1. Per **Log e tracciamento**, scegliere **Modifica**.
Se non è disponibile un gruppo di log, consulta [Configurare la CloudWatch registrazione per REST APIs in API Gateway](set-up-logging.md).
1. Aggiungere **\$1context.customDomain.routingRuleIdMatched** al formato dei log.
Questo gruppo di log registra l’ID della regola di routing utilizzato da Gateway API per inviare il traffico all’API. Per ulteriori informazioni, consulta [Non riesco a capire come API Gateway abbia inviato il traffico al mio APIs](rest-api-routing-rules-troubleshoot.md#rest-api-routing-rules-logging).
1. Scegli **Save** (Salva).
Dopo aver aggiornato i log di accesso, si invoca del nome di dominio personalizzato. Di seguito è riportato un esempio di comando curl per invocare il nome di dominio personalizzato `https://api.example.com` con il percorso di base `orders/v2/items/categories/5`.
```
curl "https://api.example.com/orders/v2/items/categories/5"
```
Dopo aver richiamato con successo il nome di dominio personalizzato, conferma che Logs mostri il. CloudWatch `routingRuleIdMatched` Per informazioni su come utilizzare la console CloudWatch Logs per visualizzare un gruppo di log, consulta. [Visualizza gli eventi di registro dell'API Gateway nella CloudWatch console](view-cloudwatch-log-events-in-cloudwatch-console.md)
------
#### [ AWS CLI ]
1. Utilizzare il [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-domain-name.html)comando seguente per aggiornare il nome di dominio in `api.example.com` modo da utilizzare la modalità di routing. `ROUTING_RULE_THEN_API_MAPPING`
```
aws apigatewayv2 update-domain-name \
--domain-name 'api.example.com' \
--routing-mode ROUTING_RULE_THEN_API_MAPPING
```
1. Utilizzare il [create-routing-rule](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-routing-rule.html)comando seguente per creare una nuova regola di routing per ricreare la mappatura delle API. `https://api.example.com/orders/v2/items/categories/5`
```
aws apigatewayv2 create-routing-rule \
--domain-name 'api.example.com' \
--priority 50 \
--conditions '[
{
"MatchBasePaths": {
"AnyOf": [
"orders/v2/items/categories/5"
]
}
}
]' \
--actions '[
{
"InvokeApi": {
"ApiId": "a1b2c3",
"Stage": "prod",
"StripBasePath": true
}
}
]'
```
1. Utilizza il seguente comando [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) per aggiornare il formato dei log di accesso in modo da includere la variabile `$context.customDomain.routingRuleIdMatched`. Questa variabile registra l’ID della regola di routing utilizzata da Gateway API per inviare il traffico all’API. Questo log si usa per verificare che Gateway API utilizzi la regola di routing per inviare traffico all’API. Per ulteriori informazioni, consulta [Non riesco a capire come API Gateway abbia inviato il traffico al mio APIs](rest-api-routing-rules-troubleshoot.md#rest-api-routing-rules-logging).
```
aws apigateway update-stage \
--rest-api-id a1bc2c3 \
--stage-name prod \
--patch-operations "op=replace,path=/accessLogSettings/format,value='\$context.path \$context.customDomain.routingRuleIdMatched \$context.requestId \$context.extendedRequestId'"
```
Se non è disponibile un gruppo di log, consulta [Configurare la CloudWatch registrazione per REST APIs in API Gateway](set-up-logging.md).
1. Utilizza il seguente comando curl di esempio per invocare il nome di dominio personalizzato con il percorso di base `orders/v2/items/categories/5`.
```
curl "https://api.example.com/orders/v2/items/categories/5
```
1. Utilizzate il [filter-log-events](https://docs.aws.amazon.com/cli/latest/reference/logs/filter-log-events.html)comando seguente per ottenere gli eventi di registro dal gruppo di log `access-log-group-orders` che contiene l'ID della regola di routing. `abc123`
```
aws logs filter-log-events --log-group-name access-log-group-orders --filter-pattern abc123
```
Questo comando conferma che Gateway API utilizza la regola di routing per inviare traffico all’API.
------
# Risoluzione dei problemi relativi alle regole di routing
La seguente guida può aiutare a risolvere i problemi relativi alle regole di routing.
## Non riesco a capire come API Gateway abbia inviato il traffico al mio APIs
È possibile utilizzare i log di accesso per la fase della REST API per registrare e risolvere i problemi delle regole di routing. È possibile visualizzare l’ID della regola di routing utilizzato da Gateway API per inviare il traffico all’API usando la variabile `$context.customDomain.routingRuleIdMatched`. Per visualizzare la mappatura API utilizzata da Gateway API per inviare il traffico all’API, si usa la variabile `$context.customDomain.basePathMatched`.
Per registrare le regole di routing, devi configurare [un ARN del ruolo CloudWatch Logs appropriato](set-up-logging.md#set-up-access-logging-permissions) per il tuo account e creare un gruppo di log.
Il gruppo di log di accesso di esempio seguente può recuperare le informazioni pertinenti per la risoluzione dei problemi relativi alle regole di routing e alle mappature API. Gateway API popola solo la variabile di contesto per il meccanismo di routing utilizzato, in caso contrario la variabile di contesto è `-`.
------
#### [ CLF ]
```
$context.path $context.customDomain.routingRuleIdMatched $context.customDomain.basePathMatched $context.requestId $context.extendedRequestId
```
------
#### [ JSON ]
```
{"requestPath": "$context.path", "routingRuleId" : "$context.customDomain.routingRuleIdMatched", "API mapping" : "$context.customDomain.basePathMatched", "requestId":"$context.requestId", "extendedRequestId":"$context.extendedRequestId"}
```
------
#### [ XML ]
```
$context.path $context.customDomain.routingRuleIdMatched $context.customDomain.basePathMatched $context.extendedRequestId
```
------
#### [ CSV ]
```
$context.path,$context.customDomain.routingRuleIdMatched,$context.customDomain.basePathMatched,$context.requestId,$context.extendedRequestId
```
------
È consigliabile inoltre verificare la modalità di routing per il nome di dominio personalizzato. Per ulteriori informazioni, consulta [Impostazione della modalità di routing per il nome di dominio personalizzato](set-routing-mode.md).
## Impossibile abilitare le regole di routing sul nome di dominio personalizzato
È possibile ricevere da Gateway API il seguente errore:
```
Your account doesn’t have permission to use RoutingRules.
This might be caused by an IAM policy in your account with a deny statement on BasePathMapping or ApiMapping.
To grant permission for this account to use RoutingRules, use the UpdateAccount API.
This will impact any existing IAM policies that deny access to BasePathMapping or ApiMapping.
See API Gateway documentation for further details.
```
Riceverai questo errore se disponi o disponi di una policy IAM che nega l'accesso a o. [BasePathMapping[ApiMapping](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonapigatewaymanagementv2.html#amazonapigatewaymanagementv2-resources-for-iam-policies)](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonapigatewaymanagement.html#amazonapigatewaymanagement-resources-for-iam-policies) Quando si abilitano le regole di routing per un nome di dominio personalizzato, anche se la policy continua a negare l’accesso a `BasePathMapping` o `ApiMapping`, è possibile utilizzare la stessa policy per accedere a `RoutingRule`. Ciò consente a un utente di modificare il comportamento di routing del nome di dominio personalizzato.
Ad esempio, se si dispone di una policy simile alla seguente:
```
{
"Sid": "DenyCreatingApiMappings",
"Effect": "Deny",
"Action": "apigateway:POST",
"Resource": [
"arn:aws:apigateway:us-west-2::/domainnames/example.com/apimappings"
]
}
```
Quando si abilitano le regole di routing per `example.com`, questa policy continua a negare l’accesso alla creazione di `ApiMapping` ma non nega l’accesso alla creazione di `RoutingRule`.
È consigliabile controllare le policy IAM dell’account. La policy di esempio seguente nega l’accesso alla creazione di `ApiMapping`, `BasePathMapping` e `RoutingRule`:
```
{
"Sid": "DenyCreatingBasePathMappingsApiMappings",
"Effect": "Deny",
"Action": "apigateway:POST",
"Resource": [
"arn:aws:apigateway:us-west-2::/domainnames/example.com/basepathmappings",
"arn:aws:apigateway:us-west-2::/domainnames/example.com/apimappings"
]
},
{
"Sid": "DenyCreatingRoutingRules",
"Effect": "Deny",
"Action": "apigateway:CreateRoutingRule",
"Resource": [
"arn:aws:apigateway:us-west-2:111122223333:/domainnames/example.com/routingrules/*"
]
}
```
Dopo aver verificato che tutte le policy sono state aggiornate, è possibile aggiornare le impostazioni dell’API a livello di account per abilitare le regole di routing per una Regione.
Utilizza il seguente comando [update-account](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-account.html) per aggiornare le impostazioni dell’API a livello di account per una Regione:
```
aws apigateway update-account --patch-operations 'op=remove,path=/features,value=BlockedForRoutingRules' --region us-west-2
```
Dopo aver aggiornato le impostazioni dell’API a livello di account, è possibile modificare la modalità di routing del nome di dominio personalizzato. È anche possibile continuare a utilizzare le policy IAM per negare l’accesso a `RoutingRules`, `ApiMapping` o `BasePathMapping`.
# Usa le mappature delle API per connettere le fasi dell'API a un nome di dominio personalizzato per REST APIs
È possibile utilizzare le mappature API per connettere le fasi API a un nome di dominio personalizzato. Questo invia traffico al tuo APIs tramite il tuo nome di dominio personalizzato.
Una mappatura API specifica un'API, una fase e, facoltativamente, un percorso da utilizzare per la mappatura. Ad esempio, puoi mappare `https://api.example.com/orders` lo `production` stadio di un'API.
È 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).
## Richieste in arrivo al tuo nome di dominio personalizzato
Quando mappi un nome di dominio personalizzato su una fase dell'API, API Gateway elimina il percorso di base in entrata. Ciò rimuove il percorso di base mappato dalla chiamata all'API. Ad esempio, se la mappatura del percorso di base era `https://api.example.com/orders/shop/5` allo `test` stage e utilizzassi la seguente richiesta`https://api.example.com/orders/shop/5/hats`, API Gateway richiamerebbe la `/hats` risorsa dello `test` stadio dell'API, non la `orders/shop/5/hats` risorsa.
## Mappatura delle richieste API
Di seguito viene spiegato come API Gateway valuta le mappature delle API.
È possibile creare una mappatura delle API utilizzando mappature a livello singolo, ad esempio una mappatura delle API dallo `orders` stadio di un'API e una mappatura dell'API `beta` dallo stadio di un'API allo stadio di un'API. `shipping` `alpha` Per i nomi di dominio personalizzati regionali con la politica di sicurezza TLS 1.2, API Gateway supporta mappature API a più livelli. È possibile creare una mappatura delle API dallo `orders/v1/items` `alpha` stadio di un'API `orders/v2/items` allo stadio di un'API. `beta` Quando si crea una mappatura con più livelli, API Gateway invia le richieste alla mappatura API con il percorso di corrispondenza più lungo.
È possibile creare una mappatura API sul percorso vuoto. `(none)` Se nessun percorso corrisponde alla richiesta, API Gateway invia la richiesta al percorso vuoto`(none)`.
In questo esempio, il nome di dominio personalizzato `https://api.example.com` presenta le seguenti mappature API.
| Mappatura delle API | API selezionata |
| --- | --- |
| `(none)` | API 1 |
| `orders` | API 2 |
| `orders/v1/items` | API 3 |
| `orders/v2/items` | API 4 |
| `orders/v1/items/categories` | API 5 |
La tabella seguente mostra come API Gateway applica le precedenti mappature API a richieste di esempio.
| 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. Consultare [Richieste in arrivo al tuo nome di dominio personalizzato](#rest-api-mappings-incoming-requests). |
| `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 quello mappato APIs devono trovarsi nello stesso AWS account.
+ 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 la mappatura delle API con livelli singoli, ad esempio. `/prod`
+ Puoi mappare HTTP solo su un nome APIs di dominio personalizzato regionale con la politica di sicurezza TLS 1.2.
+ Non è possibile eseguire il WebSocket APIs mapping allo stesso nome di dominio personalizzato di un'API HTTP o di un'API REST.
+ Dopo aver creato le mappature API, è necessario creare o aggiornare il record di risorse del provider DNS per eseguire la mappatura all'endpoint API.
+ 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. Il nome di dominio personalizzato deve avere una modalità di routing impostata su `ROUTING_RULE_THEN_API_MAPPING` o`API_MAPPING_ONLY`. Per informazioni su come impostare la modalità di routing, vedere. [Impostazione della modalità di routing per il nome di dominio personalizzato](set-routing-mode.md)
Per esempi AWS Serverless Application Model di modelli che creano tutte le risorse, vedi [Sessions With SAM](https://github.com/aws-samples/sessions-with-aws-sam/tree/master/custom-domains) on GitHub.
------
#### [ Console di gestione AWS ]
1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Scegliere **Custom Domain Names (Nomi di dominio personalizzati)** nel riquadro di navigazione principale.
1. Scegliere un nome di dominio personalizzato.
1. **Nella scheda **Dettagli di routing**, scegli Configura mappature API.**
1. Specifica **API**, **Fase** e **Percorso** per la mappatura.
1. Selezionare **Salva**.
------
#### [ AWS CLI ]
Il seguente comando della [create-api-mapping](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-api-mapping.html) crea una mappatura API. In questo esempio, API Gateway invia le richieste `api.example.com/v1/orders` all'API e alla fase specificate.
**Nota**
Per creare mappature API con più livelli, è necessario utilizzare `apigatewayv2`.
```
aws apigatewayv2 create-api-mapping \
--domain-name api.example.com \
--api-mapping-key v1/orders \
--api-id a1b2c3d4 \
--stage test
```
------
#### [ CloudFormation ]
L' CloudFormation esempio seguente crea una mappatura delle API.
**Nota**
Per creare mappature API con più livelli, è necessario utilizzare `AWS::ApiGatewayV2`.
```
MyApiMapping:
Type: 'AWS::ApiGatewayV2::ApiMapping'
Properties:
DomainName: api.example.com
ApiMappingKey: 'orders/v2/items'
ApiId: !Ref MyApi
Stage: !Ref MyStage
```
------
# Tipi di indirizzi IP per nomi di dominio personalizzati in API Gateway
Quando crei un nome di dominio personalizzato, specifichi il tipo di indirizzi IP che possono richiamare il tuo dominio. Puoi scegliere di risolvere IPv4 gli indirizzi IPv4 per richiamare il tuo dominio oppure puoi scegliere dualstack per consentire sia IPv4 agli indirizzi che agli IPv6 indirizzi di richiamare il tuo dominio. Ti consigliamo di impostare il tipo di indirizzo IP su dualstack per ridurre l'esaurimento dello spazio IP o per il tuo livello di sicurezza. [Per ulteriori informazioni sui vantaggi di un tipo di indirizzo IP dualstack, consulta on. IPv6 AWS](https://docs.aws.amazon.com/whitepapers/latest/ipv6-on-aws/internet-protocol-version-6.html)
È possibile modificare il tipo di indirizzo IP aggiornando la configurazione dell'endpoint del nome di dominio.
## Considerazioni sui tipi di indirizzi IP
Le seguenti considerazioni potrebbero influire sull'utilizzo dei tipi di indirizzi IP.
+ Il tipo di indirizzo IP predefinito per i nomi di dominio personalizzati per il pubblico di API Gateway APIs è IPv4.
+ I nomi di dominio personalizzati privati possono avere solo un tipo di indirizzo IP dualstack.
+ Non è necessario che il nome di dominio personalizzato abbia lo stesso tipo di indirizzo IP per tutti gli indirizzi APIs mappati su di esso. Se disabiliti l'endpoint API predefinito, ciò potrebbe influire sul modo in cui i chiamanti possono richiamare il tuo dominio.
## Modifica il tipo di indirizzo IP di un nome di dominio personalizzato
È possibile modificare il tipo di indirizzo IP aggiornando la configurazione dell'endpoint del nome di dominio. È possibile aggiornare la configurazione dell'endpoint utilizzando il 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. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Scegli un nome di dominio pubblico personalizzato.
1. Scegli la **configurazione dell'endpoint**.
1. Per il tipo di indirizzo IP, seleziona uno **IPv4**o **Dualstack**.
1. Scegli **Save** (Salva).
------
#### [ AWS CLI ]
Il [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-domain-name.html)comando seguente aggiorna un'API in modo che abbia un tipo di indirizzo IP dualstack:
```
aws apigateway update-domain-name \
--domain-name dualstack.example.com \
--patch-operations "op='replace',path='/endpointConfiguration/ipAddressType',value='dualstack'"
```
L'output sarà simile al seguente:
```
{
"domainName": "dualstack.example.com",
"certificateUploadDate": "2025-02-04T14:46:10-08:00",
"regionalDomainName": "d-abcd1234.execute-api.us-east-1.amazonaws.com",
"regionalHostedZoneId": "Z3LQWSYCGH4ADY",
"regionalCertificateArn": "arn:aws:acm:us-east-1:111122223333:certificate/a1b2c3d4-5678-90ab-cdef",
"endpointConfiguration": {
"types": [
"REGIONAL"
],
"ipAddressType": "dualstack"
},
"domainNameStatus": "AVAILABLE",
"securityPolicy": "TLS_1_2",
"tags": {}
}
```
------
# Scegli una politica di sicurezza per il tuo dominio personalizzato in API Gateway
Una *policy di sicurezza* è una combinazione predefinita di versione TLS minima e suite di crittografia offerta da Gateway API. Quando i client stabiliscono un handshake TLS sull’API o sul nome di dominio personalizzato, la policy di sicurezza applica la versione di TLS e il pacchetto di crittografia accettato da API Gateway. Le politiche di sicurezza proteggono i tuoi nomi di dominio APIs e quelli personalizzati da problemi di sicurezza della rete, come la manomissione e l'intercettazione tra un client e un server.
API Gateway supporta policy di sicurezza legacy e policy di sicurezza avanzate. `TLS_1_0`e `TLS_1_2` sono politiche di sicurezza obsolete. Utilizza queste politiche di sicurezza per carichi di lavoro generalizzati o per iniziare a creare un'API. Qualsiasi politica che inizia con `SecurityPolicy_` è una politica di sicurezza avanzata. Utilizza queste policy per carichi di lavoro regolamentati, governance avanzata o per utilizzare la crittografia post-quantistica. Quando utilizzi una policy di sicurezza avanzata, devi anche impostare la modalità di accesso agli endpoint per una governance aggiuntiva. Per ulteriori informazioni, consulta [Modalità di accesso agli endpoint](apigateway-security-policies.md#apigateway-security-policies-endpoint-access-mode).
## Considerazioni
Di seguito sono riportate le considerazioni relative alle politiche di sicurezza per i nomi di dominio personalizzati per REST APIs in API Gateway:
+ Non è possibile abilitare il TLS reciproco su un nome di dominio che utilizza una politica di sicurezza avanzata.
+ Non è possibile mappare un'API HTTP a un nome di dominio che utilizza una politica di sicurezza avanzata.
+ Se abiliti la mappatura del percorso di base a più livelli su un'API REST che utilizza una politica di sicurezza avanzata, non puoi creare una mappatura del percorso di base su un'API HTTP per lo stesso nome di dominio.
+ La tua API può essere mappata su un nome di dominio personalizzato con una politica di sicurezza diversa dalla tua API. Quando richiami quel nome di dominio personalizzato, API Gateway utilizza la politica di sicurezza dell'API per negoziare l'handshake TLS. Se si disabilita l’endpoint API predefinito, si potrebbe influire sul modo in cui i chiamanti possono invocare l’API.
+ API Gateway supporta le politiche di sicurezza su tutti APIs. Tuttavia, puoi scegliere solo una politica di sicurezza per REST APIs. API Gateway supporta solo la politica `TLS_1_2` di sicurezza per HTTP o WebSocket APIs.
+ API Gateway non supporta l'aggiornamento di una policy di sicurezza per un nome di dominio con più tipi di endpoint. Se disponi di più tipi di endpoint per un nome di dominio, eliminane uno per aggiornare la politica di sicurezza.
## In che modo API Gateway applica le politiche di sicurezza
L'esempio seguente mostra come API Gateway applica le policy di `SecurityPolicy_TLS13_1_3_2025_09` sicurezza utilizzando la policy di sicurezza come esempio.
La politica `SecurityPolicy_TLS13_1_3_2025_09` di sicurezza accetta il traffico TLS 1.3 e rifiuta il traffico TLS 1.2 e TLS 1.0. Per il traffico TLS 1.3, la politica di sicurezza accetta le seguenti suite di crittografia:
+ `TLS_AES_128_GCM_SHA256`
+ `TLS_AES_256_GCM_SHA384`
+ `TLS_CHACHA20_POLY1305_SHA256`
API Gateway non accetta altre suite di crittografia. Ad esempio, la politica di sicurezza rifiuterebbe qualsiasi traffico TLS 1.3 che utilizza la suite di crittografia. `AES128-SHA`
Per monitorare il protocollo TLS e i client di crittografia utilizzati per accedere al tuo API Gateway, puoi utilizzare le variabili `$context.tlsVersion` e di `$context.cipherSuite` contesto nei tuoi log di accesso. Per ulteriori informazioni, consulta [Monitoraggio delle REST API in Gateway API](rest-api-monitor.md).
Per visualizzare le politiche di sicurezza predefinite per tutti i nomi di dominio REST APIs e personalizzati, consulta. [Politiche di sicurezza predefinite](apigateway-security-policies-list.md#apigateway-security-policies-default) Per visualizzare le politiche di sicurezza supportate per tutti i nomi di dominio REST APIs e personalizzati, vedere[Policy di sicurezza supportate](apigateway-security-policies-list.md).
## Modifica la politica di sicurezza del tuo nome di dominio personalizzato
Se modifichi la politica di sicurezza, il completamento dell'aggiornamento richiede circa 15 minuti. Puoi monitorare il tuo nome `lastUpdateStatus` di dominio personalizzato. Man mano che il nome di dominio personalizzato `lastUpdateStatus` viene aggiornato, lo sarà `PENDING` e quando sarà `AVAILABLE` completato.
Quando utilizzi una politica di sicurezza che inizia con`SecurityPolicy_`, devi anche attivare la modalità di accesso agli endpoint. Per ulteriori informazioni, consulta [Modalità di accesso agli endpoint](apigateway-security-policies.md#apigateway-security-policies-endpoint-access-mode).
------
#### [ Console di gestione AWS ]
**Per modificare la politica di sicurezza di un nome di dominio personalizzato**
1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Scegli un nome di dominio personalizzato che invii il traffico a REST. APIs
Assicurati che ci sia un solo tipo di endpoint associato al tuo nome di dominio personalizzato.
1. Scegli **Impostazioni personalizzate del nome di dominio**, quindi scegli **Modifica**.
1. Per **Politica di sicurezza**, seleziona una nuova politica.
1. Per la **modalità di accesso agli endpoint**, scegli **Strict**.
1. Scegli **Save changes** (Salva modifiche).
------
#### [ AWS CLI ]
Il [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-domain-name.html)comando seguente aggiorna un nome di dominio per utilizzare la politica `SecurityPolicy_TLS13_1_3_2025_09` di sicurezza:
```
aws apigateway update-domain-name \
--domain-name example.com \
--patch-operations '[
{
"op": "replace",
"path": "/securityPolicy",
"value": "SecurityPolicy_TLS13_1_3_2025_09"
},
{
"op": "replace",
"path": "/endpointAccessMode",
"value": "STRICT"
}
]'
```
L'output sarà simile al seguente:
```
{
"domainName": "example.com",
"endpointConfiguration": {
"types": [ "REGIONAL" ],
"ipAddressType": "dualstack"
},
"regionalCertificateArn": "arn:aws:acm:us-west-2:111122223333:certificate/a1b2c3d4-5678-90ab-cdef",
"securityPolicy": "SecurityPolicy_TLS13_1_3_2025_09",
"endpointAccessMode": "STRICT"
}
```
------
## Informazioni su HTTP APIs e WebSocket APIs
Per ulteriori informazioni su HTTP APIs e WebSocket APIs, vedere [Politica di sicurezza per HTTP APIs in API Gateway](http-api-ciphers.md) e[Politica di sicurezza per WebSocket APIs API Gateway](websocket-api-ciphers.md).
# Disabilita l'endpoint predefinito per REST APIs
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. I client possono comunque connettersi all'endpoint predefinito, ma riceveranno un codice di stato `403 Forbidden`. La disabilitazione dell’endpoint predefinito influisce su tutte le fasi dell’API. Questa impostazione diventa effettiva quando si aggiorna un’impostazione su una fase, ad esempio quando si aggiorna l’implementazione sulla fase.
La procedura seguente mostra come disabilitare l'endpoint predefinito per una REST API.
------
#### [ Console di gestione AWS ]
1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Scegliere una REST API.
1. Nel pannello di navigazione principale scegli **Impostazioni API**.
1. Scegliere un'API.
1. In **Dettagli API** seleziona **Modifica**.
1. Per **Endpoint predefinito** seleziona **Inattivo**.
1. Scegli **Save changes** (Salva modifiche).
1. Nel pannello di navigazione principale scegli **Risorse**.
1. Seleziona **Deploy API (Distribuisci API)**.
1. Implementa nuovamente l’API in una fase o aggiorna un’impostazione su una fase per rendere effettivo l’aggiornamento.
------
#### [ AWS CLI ]
Il [update-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-rest-api.html)comando seguente disabilita l'endpoint predefinito:
```
aws apigateway update-rest-api \
--rest-api-id abcdef123 \
--patch-operations op=replace,path=/disableExecuteApiEndpoint,value='True'
```
Dopo aver disabilitato l'endpoint predefinito, è necessario distribuire l'API per rendere effettiva la modifica.
Il comando [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-deployment.html) seguente crea un’implementazione e la associa a una fase:
```
aws apigateway create-deployment \
--rest-api-id abcdef123 \
--stage-name dev
```
------
# Configurazione dei controlli dell'integrità personalizzati per failover DNS per un'API di Gateway API
Puoi utilizzare i controlli di integrità di Amazon Route 53 per controllare il failover DNS da un'API API Gateway in una regione primaria Regione AWS a una in una regione secondaria. Questo può aiutare a mitigare gli impatti in caso di problema regionale. Se si utilizza un dominio personalizzato, è possibile eseguire il failover senza richiedere ai client di modificare gli endpoint API.
Quando si sceglie [Evaluate Target Health](https://docs.aws.amazon.com/Route53/latest/APIReference/API_AliasTarget.html#Route53-Type-AliasTarget-EvaluateTargetHealth>Evaluate Target Health) (Valutazione dello stato target) per un record alias, tali record non riescono solo quando il servizio API Gateway non è disponibile nella regione. In alcuni casi, il tuo API Gateway APIs può subire interruzioni prima di quel momento. Per controllare direttamente il failover DNS, configura i controlli di integrità personalizzati di Route 53 per il tuo API Gateway. APIs Per questo esempio, si utilizza un CloudWatch allarme che aiuta gli operatori a controllare il failover DNS. Per altri esempi e altre considerazioni sulla configurazione del failover, consulta [Creazione di meccanismi di disaster recovery utilizzando Route 53](https://aws.amazon.com/blogs/networking-and-content-delivery/creating-disaster-recovery-mechanisms-using-amazon-route-53/) ed [Esecuzione dei controlli di integrità di Route 53 su risorse private in un VPC](https://aws.amazon.com/blogs/networking-and-content-delivery/performing-route-53-health-checks-on-private-resources-in-a-vpc-with-aws-lambda-and-amazon-cloudwatch/) con e. AWS Lambda CloudWatch
**Topics**
+ [
## Prerequisiti
](#dns-failover-prereqs)
+ [
## Fase 1: Configurazione delle risorse
](#dns-failover-intial-setup)
+ [
## Fase 2: Avvio del failover nella regione secondaria
](#dns-failover-initiate)
+ [
## Fase 3: Test del failover
](#dns-failover-test)
+ [
## Fase 4: Ritorno alla regione primaria
](#dns-failover-return)
+ [
## Fasi successive: personalizzare e verificare periodicamente
](#dns-failover-next-steps)
## Prerequisiti
Per completare questa procedura, è necessario creare e configurare le risorse seguenti:
+ Un nome di dominio di cui si è proprietari.
+ Un certificato ACM per quel nome di dominio in due. Regioni AWS Per ulteriori informazioni, consulta [Prerequisiti per i nomi di dominio personalizzati](how-to-custom-domains.md#how-to-custom-domains-prerequisites).
+ Una zona ospitata Route 53 per il nome di dominio in uso. Per ulteriori informazioni, consulta [Utilizzo delle zone ospitate](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/hosted-zones-working-with.html) nella Guida per gli sviluppatori di Amazon Route 53.
Per ulteriori informazioni su come creare record DNS di failover Route 53 per i nomi di dominio, consulta [Scelta una policy di instradamento](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-policy.html) nella Guida per sviluppatori Amazon Route 53. Per ulteriori informazioni su come monitorare un CloudWatch allarme, consulta [Monitoring a CloudWatch alarm](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/health-checks-creating-values.html#health-checks-creating-values-cloudwatch) nella Amazon Route 53 Developer Guide.
## Fase 1: Configurazione delle risorse
In questo esempio, vengono create le seguenti risorse per configurare il failover DNS per il nome di dominio in uso:
+ API Gateway APIs in due Regioni AWS
+ Nomi di dominio personalizzati API Gateway con lo stesso nome in due Regioni AWS
+ Mappature API Gateway che collegano l'API Gateway APIs ai nomi di dominio personalizzati
+ Record DNS di failover di Route 53 per i nomi di dominio
+ Un CloudWatch allarme nella regione secondaria
+ Un controllo dello stato di salute della Route 53 basato sull' CloudWatch allarme nella regione secondaria
Innanzitutto, accertarsi di disporre di tutte le risorse richieste nelle regioni primaria e secondaria. La regione secondaria deve contenere l'allarme e il controllo dell'integrità. In questo modo, non si dipende dalla regione primaria per eseguire il failover. Ad esempio, CloudFormation i modelli che creano queste risorse, vedi [samples/primary.zip](samples/primary.zip)e [samples/secondary.zip](samples/secondary.zip).
**Importante**
Prima del failover nella regione secondaria, accertarsi che tutte le risorse necessarie siano disponibili. In caso contrario, l'API non sarà pronta per il traffico nella regione secondaria.
## Fase 2: Avvio del failover nella regione secondaria
Nell'esempio seguente, la regione di standby riceve una CloudWatch metrica e avvia il failover. Utilizziamo una metrica personalizzata che richiede l'intervento dell'operatore per avviare il failover.
```
aws cloudwatch put-metric-data \
--metric-name Failover \
--namespace HealthCheck \
--unit Count \
--value 1 \
--region us-west-1
```
Sostituisci i dati metrici con i dati corrispondenti per l'allarme che hai configurato. CloudWatch
## Fase 3: Test del failover
Richiamare l'API e verificare di ricevere una risposta dalla regione secondaria. Se si sono utilizzati i modelli di esempio della fase 1, la risposta cambia da `{"message": "Hello from the primary Region!"}` a `{"message": "Hello from the secondary Region!"}` dopo il failover.
```
curl https://my-api.example.com
{"message": "Hello from the secondary Region!"}
```
## Fase 4: Ritorno alla regione primaria
Per tornare alla regione principale, invia una CloudWatch metrica che determini il superamento del controllo sanitario.
```
aws cloudwatch put-metric-data \
--metric-name Failover \
--namespace HealthCheck \
--unit Count \
--value 0 \
--region us-west-1
```
Sostituisci i dati metrici con i dati corrispondenti per l' CloudWatch allarme che hai configurato.
Richiamare l'API e verificare di ricevere una risposta dalla regione primaria. Se si sono utilizzati i modelli di esempio della fase 1, la risposta cambia da `{"message": "Hello from the secondary Region!"}` a `{"message": "Hello from the primary Region!"}`.
```
curl https://my-api.example.com
{"message": "Hello from the primary Region!"}
```
## Fasi successive: personalizzare e verificare periodicamente
Questo esempio dimostra un modo per configurare il failover DNS. È possibile utilizzare una varietà di CloudWatch metriche o endpoint HTTP per i controlli di integrità che gestiscono il failover. Verificare periodicamente i meccanismi di failover per accertarsi che funzionino come previsto e che gli operatori conoscano le procedure di failover.