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à.
# Nomi di dominio personalizzati per API HTTP in Gateway API
I *nomi di dominio personalizzati* sono URL più semplici e più intuitivi che è possibile fornire agli utenti delle API.
Dopo aver distribuito un'API, tu e i tuoi clienti potete richiamarla usando l'URL di base predefinito nel formato seguente:
```
https://api-id.execute-api.region.amazonaws.com/stage
```
dove *api-id* è generato da Gateway API, *region* è la Regione AWS e *stage* è il valore che è stato specificato al momento dell'implementazione dell'API.
La parte del nome host dell'URL, `api-id.execute-api.region.amazonaws.com`, fa riferimento a un endpoint API. Il nome dell'endpoint API predefinito viene generato casualmente, è complesso da richiamare e non è intuitivo.
Con i nomi di dominio personalizzati, è possibile impostare il nome host dell'API e scegliere un percorso base (ad esempio `myservice`) per mappare l'URL alternativo all'API. Ad esempio, un URL di base dell'API più intuitivo può diventare:
```
https://api.example.com/myservice
```
## Considerazioni
Le seguenti considerazioni potrebbero influire sull'utilizzo di un nome di dominio personalizzato.
+ Un nome di dominio personalizzato regionale può essere associato alle REST API e alle API HTTP. È possibile utilizzare le API di Gateway API Versione 2 per creare e gestire nomi di dominio personalizzati regionali per le REST API.
+ L'unica versione minima di TLS supportata è TLS 1.2.
+ È necessario creare o aggiornare il record di risorse del provider DNS per eseguire la mappatura all'endpoint API. In assenza di questa mappatura, le richieste API destinate al nome di dominio personalizzato non possono raggiungere API Gateway.
+ È possibile supportare un numero pressoché infinito di nomi di dominio senza superare la quota predefinita con un certificato jolly. Per ulteriori informazioni, consulta [Nomi di dominio personalizzati con caratteri jolly](#http-wildcard-custom-domain-names).
## Prerequisiti
Di seguito sono riportati i prerequisiti per la creazione di un nome di dominio personalizzato.
### Registrare un nome di dominio
Per configurare nomi di dominio personalizzati per le API, devi avere un nome di dominio Internet registrato. Puoi registrare un nome di dominio Internet utilizzando [Amazon Route 53](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/) oppure un registrar di dominio di terze parti a tua scelta. Il nome di dominio personalizzato può essere il nome di un sottodominio o del dominio root (detto anche "apex di zona") di un dominio Internet registrato.
Il nome di dominio deve seguire la specifica [RFC 1035](https://tools.ietf.org/html/rfc1035#section-2.3.4) e può avere un massimo di 63 ottetti per etichetta e 255 ottetti in totale.
### Certificati per nomi di dominio personalizzati
Prima di configurare un nome di dominio personalizzato per un'API, è necessario che sia già presente un certificato SSL/TLS in ACM. Se ACM non è disponibile nella Regione AWS in cui si sta creando il nome di dominio personalizzato, è necessario importare nella Regione un certificato in Gateway API.
Per importare un certificato SSL/TLS, devi fornire il corpo del certificato SSL/TLS in formato PEM, la sua chiave privata e la catena di certificati per il nome di dominio personalizzato.
Ogni certificato archiviato in ACM è identificato dal relativo ARN. Con i certificati emessi da ACM, non devi preoccuparti di esporre dettagli sensibili del certificato, come la chiave privata. Per usare un certificato gestito da AWS per un nome di dominio, devi semplicemente fare riferimento al relativo ARN.
Se l’applicazione utilizza il blocco dei certificati, talvolta denominato associazione SSL, per associare un certificato ACM, è possibile che l'applicazione non riesca a connettersi al tuo dominio dopo che AWS ha rinnovato il certificato. Per ulteriori informazioni, consulta [Probemi nel blocco dei certificati](https://docs.aws.amazon.com/acm/latest/userguide/troubleshooting-pinning.html) nella *Guida per l'utente di AWS Certificate Manager*.
## Nomi di dominio personalizzati con caratteri jolly
Con i nomi di dominio personalizzati con caratteri jolly, è possibile supportare un numero quasi infinito di nomi di dominio senza superare la [quota predefinita](limits.md). Ad esempio, è possibile dare a ciascuno dei clienti il proprio nome di dominio, `customername.api.example.com`.
Per creare un nome di dominio personalizzato con caratteri jolly, specificare un carattere jolly (`*`) come primo sottodominio di un dominio personalizzato che rappresenta tutti i possibili sottodomini di un dominio radice.
Ad esempio, il nome di dominio personalizzato con caratteri jolly `*.example.com` genera sottodomini quali `a.example.com`, `b.example.com` e `c.example.com`, indirizzati tutti allo stesso dominio.
I nomi di dominio personalizzati con caratteri jolly supportano configurazioni distinte dai nomi di dominio personalizzati standard di API Gateway. Ad esempio, in un singolo account AWS, è possibile configurare `*.example.com` e `a.example.com` affinché si comportino in modo diverso.
Per creare un nome di dominio personalizzato con caratteri jolly, è necessario fornire un certificato emesso da ACM che sia stato convalidato utilizzando il DNS o il metodo di convalida della posta elettronica.
**Nota**
Non è possibile creare un nome di dominio personalizzato con caratteri jolly se un account AWS diverso ha creato un nome di dominio personalizzato in conflitto con il nome di dominio personalizzato con caratteri jolly. Ad esempio, se l'account A ha creato `a.example.com`, l'account B non può creare il nome di dominio personalizzato con caratteri jolly `*.example.com`.
Se l'account A e l'account B condividono un proprietario, è possibile contattare il [Centro assistenza AWS](https://console.aws.amazon.com/support/home#/) per richiedere un'eccezione.
## Passaggi successivi per nomi di dominio personalizzati
Per configurare un nome di dominio personalizzato per un'API HTTP, consulta la documentazione disponibile nella sezione REST API della Guida per gli sviluppatori di Gateway API.
Per prima cosa, si specifica un certificato per il nome di dominio personalizzato. Per ulteriori informazioni, consulta [Prepara i certificati in AWS Certificate Manager](how-to-specify-certificate-for-custom-domain-name.md). Successivamente, si crea un nome di dominio personalizzato regionale. Per ulteriori informazioni, consulta [Configurazione di un nome di dominio personalizzato regionale in Gateway API](apigateway-regional-api-custom-domain-create.md).
# Mappatura delle fasi API a un nome di dominio personalizzato per le API HTTP
È possibile utilizzare le mappature API per connettere le fasi API a un nome di dominio personalizzato. Dopo aver creato un nome di dominio e aver configurato i record DNS, è possibile utilizzare le mappature API per inviare il traffico alle API tramite il nome di dominio personalizzato.
Una mappatura API specifica un'API, una fase e, facoltativamente, un percorso da utilizzare per la mappatura. Ad esempio, è possibile mappare la fase `production` di un'API su `https://api.example.com/orders`.
È possibile mappare le fasi HTTP e API REST allo stesso nome di dominio personalizzato.
Prima di creare una mappatura API, è necessario disporre di un'API, di una fase e di un nome di dominio personalizzato. Per ulteriori informazioni sulla creazione di un nome di dominio personalizzato, consulta [Configurazione di un nome di dominio personalizzato regionale in Gateway API](apigateway-regional-api-custom-domain-create.md).
## Routing delle richieste API
È possibile configurare le mappature API con più livelli, ad esempio `orders/v1/items` e `orders/v2/items`.
Per mappature API con più livelli, API Gateway instrada le richieste alla mappatura API che ha il percorso corrispondente più lungo. API Gateway considera solo i percorsi configurati per le mappature API, e non i percorsi API, per selezionare l'API da richiamare. Se nessun percorso corrisponde alla richiesta, API Gateway invia la richiesta all'API mappata al percorso vuoto `(none)`.
Per i nomi di dominio personalizzati che usano mappature API con più livelli, API Gateway instrada le richieste alla mappatura API che ha il percorso corrispondente più lungo.
Ad esempio, se si considera un nome di dominio personalizzato `https://api.example.com` con le seguenti mappature API:
1. `(none)` mappato all'API 1.
1. `orders` mappato all'API 2.
1. `orders/v1/items` mappato all'API 3.
1. `orders/v2/items` mappato all'API 4.
1. `orders/v2/items/categories` mappato all'API 5.
| Richiesta | API selezionata | Spiegazione |
| --- | --- | --- |
| `https://api.example.com/orders` | `API 2` | La richiesta corrisponde esattamente a questa mappatura API. |
| `https://api.example.com/orders/v1/items` | `API 3` | La richiesta corrisponde esattamente a questa mappatura API. |
| `https://api.example.com/orders/v2/items` | `API 4` | La richiesta corrisponde esattamente a questa mappatura API. |
| `https://api.example.com/orders/v1/items/123` | `API 3` | API Gateway sceglie la mappatura con il percorso corrispondente più lungo. `123` alla fine della richiesta non influisce sulla selezione. |
| `https://api.example.com/orders/v2/items/categories/5` | `API 5` | API Gateway sceglie la mappatura con il percorso corrispondente più lungo. |
| `https://api.example.com/customers` | `API 1` | API Gateway utilizza la mappatura vuota come catch-all. |
| `https://api.example.com/ordersandmore` | `API 2` | API Gateway sceglie la mappatura con il prefisso corrispondente più lungo. Per un nome di dominio personalizzato configurato con mappature a livello singolo, ad esempio solo `https://api.example.com/orders` e `https://api.example.com/`, API Gateway sceglie `API 1`, poiché non esiste un percorso corrispondente con `ordersandmore`. |
## Restrizioni
+ In una mappatura API, il nome di dominio personalizzato e le API mappate devono trovarsi nello stesso account AWS.
+ Le mappature API devono contenere solo lettere, numeri e i seguenti caratteri: `$-_.+!*'()/`.
+ La lunghezza massima per il percorso in una mappatura API è di 300 caratteri.
+ È possibile disporre di 200 mappature API con più livelli per ogni nome di dominio. Questo limite non include le mappature API con livelli singoli, ad esempio `/prod`.
+ È possibile mappare le API HTTP a un nome di dominio personalizzato regionale solo con la policy di sicurezza TLS 1.2.
+ Non è possibile mappare le API WebSocket allo stesso nome di dominio personalizzato di un'API HTTP o un'API REST.
+ Se si crea una mappatura API con più livelli, Gateway API converte tutti i nomi di intestazione in lettere minuscole.
## Creare una mappatura API
Per creare una mappatura API, innanzitutto è necessario creare un nome di dominio personalizzato, un'API e una fase. Per informazioni sulla creazione di un nome di dominio personalizzato, consulta [Configurazione di un nome di dominio personalizzato regionale in Gateway API](apigateway-regional-api-custom-domain-create.md).
Per modelli di esempio di AWS Serverless Application Model che creano tutte le risorse, consulta [Sessioni con SAM](https://github.com/aws-samples/sessions-with-aws-sam/tree/master/custom-domains) su GitHub.
------
#### [ Console di gestione AWS ]
**Per creare una mappatura API**
1. Accedere alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Scegliere **Nomi di dominio personalizzati**.
1. Selezionare un nome di dominio personalizzato già creato.
1. Scegliere **API mappings (mappature API)**.
1. Scegliere **Configure API mappings (Configura mappature API)**.
1. Scegliere **Add new mapping (Aggiungi nuova mappatura)**.
1. Immettere un'**API**, uno **Stage (Fase)**e, facoltativamente, un **Path (Percorso)**.
1. Selezionare **Salva**.
------
#### [ AWS CLI ]
Il comando [create-api-mapping](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-api.html) seguente crea una mappatura API. In questo esempio, API Gateway invia le richieste `api.example.com/v1/orders` all'API e alla fase specificate.
```
aws apigatewayv2 create-api-mapping \
--domain-name api.example.com \
--api-mapping-key v1/orders \
--api-id a1b2c3d4 \
--stage test
```
------
#### [ CloudFormation ]
Il seguente esempio di CloudFormation consente di creare una mappatura API.
```
MyApiMapping:
Type: 'AWS::ApiGatewayV2::ApiMapping'
Properties:
DomainName: api.example.com
ApiMappingKey: 'orders/v2/items'
ApiId: !Ref MyApi
Stage: !Ref MyStage
```
------
# Disabilitazione dell'endpoint predefinito per API HTTP
Per impostazione predefinita, i client possono richiamare l'API utilizzando l'endpoint `execute-api` generato da API Gateway per l'API. Per garantire che i client possano accedere all'API solo utilizzando un nome di dominio personalizzato con l'autenticazione TLS reciproca, disattivare l'endpoint `execute-api` predefinito. Quando si disattiva l'endpoint predefinito, questa operazione influisce su tutte le fasi di un'API.
La seguente procedura mostra come disabilitare l'endpoint predefinito per un'API HTTP.
------
#### [ Console di gestione AWS ]
1. Accedere alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Scegliere un'API HTTP.
1. Scegli l'ID dell'API per aprire la pagina **Dettagli API**.
1. In **Dettagli API** seleziona **Modifica**.
1. Per **Endpoint predefinito** seleziona **Disabilita**.
1. Selezionare **Salva**.
Se si attivano le implementazioni automatiche per la fase, non è necessario implementare nuovamente l'API per rendere effettiva la modifica. In caso contrario, è necessario implementare nuovamente l'API.
1. (Facoltativo) Scegli **Distribuzione**, quindi implementa nuovamente l'API o crea una nuova fase per rendere effettiva la modifica.
------
#### [ AWS CLI ]
Il comando [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-domain-name.html) seguente disabilita l’endpoint predefinito per un’API HTTP:
```
aws apigatewayv2 update-api \
--api-id abcdef123 \
--disable-execute-api-endpoint
```
Dopo aver disattivato l'endpoint predefinito, è necessario distribuire l'API per rendere effettiva la modifica, a meno che non siano abilitate le distribuzioni automatiche.
Il seguente comando [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-deployment.html) crea l'implementazione:
```
aws apigatewayv2 create-deployment \
--api-id abcdef123 \
--stage-name dev
```
------
# Tipi di indirizzo IP per nomi di dominio personalizzati per API HTTP
Quando si crea un’API, è possibile specificare il tipo di indirizzo IP che può invocare il dominio. È possibile scegliere IPv4 per risolvere gli indirizzi IPv4 per invocare il dominio oppure dualstack per consentire a entrambi gli indirizzi IPv4 e IPv6 di invocare il dominio. È consigliabile impostare il tipo di indirizzo IP su dualstack per ridurre l’esaurimento dello spazio IP o per il livello di sicurezza. Per ulteriori informazioni sui vantaggi del tipo di indirizzo IP dualstack, consultare [IPv6 on AWS](https://docs.aws.amazon.com/whitepapers/latest/ipv6-on-aws/internet-protocol-version-6.html).
## Considerazioni sui tipi di indirizzo IP
Le seguenti considerazioni potrebbero influire sull’utilizzo dei tipi di indirizzo IP.
+ Il tipo di indirizzo IP predefinito per i nomi di dominio personalizzati di Gateway API è IPv4.
+ Per il nome di dominio personalizzato, non è necessario che tutte le API mappate ad esso abbiano lo stesso tipo di indirizzo IP. Se si disabilita l’endpoint API predefinito, si potrebbe influire sul modo in cui i chiamanti possono invocare l’API.
## Modifica del tipo di indirizzo IP di un nome di dominio personalizzato
È possibile modificare il tipo di indirizzo IP aggiornando la configurazione dell’endpoint del dominio. È possibile aggiornare la configurazione dell’endpoint del dominio utilizzando la Console di gestione AWS, AWS CLI, CloudFormation o un AWS SDK.
------
#### [ Console di gestione AWS ]
**Per modificare il tipo di indirizzo IP di un nome di dominio personalizzato**
1. Accedere alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Scegliere un nome di dominio personalizzato pubblico.
1. Scegliere **Configurazione endpoint**.
1. Per Tipo di indirizzo IP, selezionare **IPv4** o **Dualstack**.
1. Selezionare **Salva**.
------
#### [ AWS CLI ]
Il comando [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-domain-name.html) seguente aggiorna un’API in modo che abbia un tipo di indirizzo IP dualstack:
```
aws apigatewayv2 update-domain-name \
--domain-name dualstack.example.com \
--domain-name-configurations CertificateArn=arn:aws:acm:us-east-1:111122223333:certificate/abcd1234-5678-abc,IpAddressType=dualstack
```
L'output sarà simile al seguente:
```
{
"ApiMappingSelectionExpression": "$request.basepath",
"DomainName": "dualstack.example.com",
"DomainNameConfigurations": [
{
"ApiGatewayDomainName": "d-abcd1234.execute-api.us-east-1.amazonaws.com",
"CertificateArn": "arn:aws:acm:us-east-1:111122223333:certificate/abcd1234-5678-abc",
"DomainNameStatus": "AVAILABLE",
"EndpointType": "REGIONAL",
"HostedZoneId": "Z3LQWSYCGH4ADY",
"SecurityPolicy": "TLS_1_2",
"IpAddressType": "dualstack"
}
],
"Tags": {}
}
```
------