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à.
# Pubblica REST APIs per i clienti da richiamare
La semplice creazione e sviluppo di un'API di API Gateway non la rende automaticamente richiamabile dagli utenti. Per renderla richiamabile, è necessario distribuire l'API in una fase. Inoltre, potrebbe essere necessario personalizzare l'URL che verrà utilizzato dagli utenti per accedere all'API. Puoi assegnarli un dominio che sia coerente con il tuo marchio o che sia più facile da ricordare dell'URL predefinito dell'API.
In questa sezione viene descritto come distribuire l'API e personalizzare l'URL fornito agli utenti per accedervi.
**Nota**
Per aumentare la sicurezza del tuo API Gateway APIs, il `execute-api.{region}.amazonaws.com` dominio è registrato nella [Public Suffix List (PSL](https://publicsuffix.org/)). Per una maggiore sicurezza, ti consigliamo di utilizzare i cookie con un `__Host-` prefisso se hai bisogno di impostare cookie sensibili nel nome di dominio predefinito per il tuo API Gateway APIs. Questa pratica ti aiuterà a difendere il tuo dominio dai tentativi CSRF (cross-site request forgery). Per ulteriori informazioni, consulta la pagina [Impostazione cookie](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#cookie_prefixes) nella pagina Mozilla Developer Network.
**Topics**
+ [Implementazione di REST API in Gateway API](how-to-deploy-api.md)
+ [Nome di dominio personalizzato per REST pubblico APIs in API Gateway](how-to-custom-domains.md)
# Implementazione di REST API in Gateway API
Dopo aver creato l'API, è necessario distribuirla per renderla chiamabile dagli utenti.
Per distribuire un'API, crea una distribuzione API e associala a una fase. Una fase è un riferimento logico a uno stato del ciclo di vita dell'API (ad esempio, `dev`, `prod`, `beta`, `v2`). Le fasi API sono identificate dall'ID API e dal nome della fase. Sono incluse nell'URL utilizzato per richiamare l'API. Ogni fase è un riferimento con nome a una distribuzione dell'API e viene resa disponibile per le applicazioni client da chiamare.
**Importante**
Ogni volta che si aggiorna un'API, è necessario distribuire nuovamente l'API in una fase esistente o in una nuova fase. L'aggiornamento di un'API include la modifica di instradamenti, metodi, integrazioni, sistemi di autorizzazione, policy delle risorse e qualsiasi altra cosa diversa dalle impostazioni di fase.
Con l'evoluzione dell'API, puoi continuare a distribuirla in fasi diverse come versioni differenti. Puoi inoltre distribuire gli aggiornamenti API come una [distribuzione di una release Canary](canary-release.md). Ciò consente ai client API di accedere, sulla stessa fase, alla versione di produzione tramite la release e alla versione aggiornata tramite la release Canary.
Per chiamare un'API distribuita, il client invia una richiesta all'URL di un'API. L'URL è determinato dal protocollo (HTTP(S) o (WSS)), nome host, nome fase e (per le API REST) dal percorso delle risorse di un'API. Il nome host e il nome della fase determinano l'URL di base dell'API.
Se, ad esempio, si utilizza il nome di dominio predefinito dell'API, il formato dell'URL di base di un'API REST (ad esempio) in una fase specifica (`{stageName}`) è il seguente:
```
https://{restapi-id}.execute-api.{region}.amazonaws.com/{stageName}
```
Per rendere più intuitivo l'URL di base predefinito dell'API, puoi creare un nome di dominio personalizzato (ad esempio, `api.example.com`) per sostituire il nome host predefinito dell'API. Per supportare più API con il nome di dominio personalizzato, è necessario mappare una fase API a un percorso di base.
Con il nome di dominio personalizzato `{api.example.com}` e la fase API mappata al percorso di base (`{basePath}`) nel nome di dominio personalizzato, l'URL di base di un'API REST diventa:
```
https://{api.example.com}/{basePath}
```
Per ogni fase puoi ottimizzare le prestazioni dell'API impostando i limiti di throttling predefiniti delle richieste a livello di account e abilitando il caching dell'API. Puoi inoltre abilitare la registrazione delle chiamate API in CloudTrail o CloudWatch e selezionare un certificato client per permettere al back-end di autenticare le richieste API. Inoltre, puoi ignorare le impostazioni a livello di fase per i singoli metodi e definire le variabili di fase per il passaggio di contesti di ambiente specifici della fase all'integrazione API al runtime.
Le fasi permettono un efficace controllo delle versioni dell'API. Ad esempio, puoi distribuire un'API in una fase `test` e una fase `prod` e utilizzare la fase `test` come build di test e la fase `prod` come build stabile. Dopo che gli aggiornamenti hanno superato il test, puoi promuovere la fase `test` alla fase `prod`. La promozione può essere eseguita implementando nuovamente l'API nella fase `prod` o aggiornando il valore di una variabile di fase dal nome `test` al nome `prod`.
In questa sezione viene illustrato come distribuire un'API utilizzando la [console API Gateway](https://console.aws.amazon.com/apigateway) o chiamando l'[API REST di API Gateway](https://docs.aws.amazon.com/apigateway/latest/api/). Per utilizzare altri strumenti, consulta la documentazione della [AWS CLI](https://docs.aws.amazon.com/cli/latest/reference/apigateway/) o di un [SDK AWS](https://aws.amazon.com/developer/tools/#sdk).
**Topics**
+ [Creazione di un'implementazione per una REST API in Gateway API](set-up-deployments.md)
+ [Configurazione di una fase per una REST API in Gateway API](set-up-stages.md)
+ [Configurare la distribuzione di una release Canary di API Gateway](canary-release.md)
+ [Aggiornamenti a REST APIs che richiedono una ridistribuzione](updating-api.md)
# Creazione di un'implementazione per una REST API in Gateway API
In API Gateway una distribuzione di API REST è rappresentata da una risorsa [Distribuzione](https://docs.aws.amazon.com/apigateway/latest/api/API_Deployment.html). È simile a un eseguibile di un'API rappresentato da una risorsa [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html).
Per consentire al client di chiamare l'API, è necessario creare una distribuzione e associarvi una fase. Una fase è rappresentata da una risorsa [Fase](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html). Rappresenta una snapshot dell'API, inclusi metodi, integrazioni, modelli, modelli di mappatura e autorizzazioni Lambda (in precedenza note come autorizzazioni ad hoc). Quando si aggiorna l'API, è possibile ridistribuirla associando una nuova fase alla distribuzione esistente. La procedura di creazione di una fase è illustrata in [Configurazione di una fase per una REST API in Gateway API](set-up-stages.md).
**Topics**
+ [Crea distribuzione](#create-deployment)
+ [Fasi successive per l'implementazione di un'API](#apigateway-deployment-next-steps)
## Crea distribuzione
Le procedure seguenti mostrano come creare l'implementazione di una REST API.
------
#### [ Console di gestione AWS ]
Per poter distribuire un'API REST per la prima volta, è necessario crearla. Per ulteriori informazioni, consulta [Sviluppa REST APIs in API Gateway](rest-api-develop.md).
La console API Gateway consente di distribuire un'API creando una distribuzione e associandola a una fase nuova o esistente.
1. Accedere alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Nel riquadro di navigazione **APIs (API)** scegliere l'API che si desidera distribuire.
1. Nel riquadro **Resources (Risorse)** scegliere **Deploy API (Distribuisci API)**.
1. In **Fase**, procedi come segue:
1. Per creare una nuova fase, seleziona **Nuova fase**, quindi immetti un nome in **Nome fase**. Facoltativamente, puoi immettere una descrizione dell'implementazione in **Descrizione distribuzione**.
1. Per scegliere una fase esistente, seleziona il nome della fase nel menu a discesa. Se lo desideri, puoi specificare una descrizione della nuova implementazione in **Descrizione distribuzione**.
1. Per creare un'implementazione non associata a una fase, seleziona **Nessuna fase**. Successivamente, puoi associare questa implementazione a una fase.
1. Seleziona **Deploy (Implementa)**.
------
#### [ AWS CLI ]
Quando si crea una distribuzione, viene creata un'istanza della risorsa [Distribuzione](https://docs.aws.amazon.com/apigateway/latest/api/API_Deployment.html).
Il comando [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-deployment.html) seguente crea una nuova implementazione:
```
aws apigateway create-deployment --rest-api-id rest-api-id
```
Non è possibile chiamare l’API fino a quando non si associa questa implementazione a una fase. Con una fase esistente, è possibile eseguire questa operazione aggiornando la proprietà [deploymentId](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#deploymentId) della fase con l’ID di implementazione appena creato. Il comando [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) seguente aggiorna la fase con una nuova implementazione. Nella console, questa azione è chiamata **Implementazione attiva**.
```
aws apigateway update-stage \
--rest-api-id rest-api-id \
--stage-name 'stage-name' \
--patch-operations op='replace',path='/deploymentId',value='deployment-id'
```
Quando si crea l’implementazione, è possibile contemporaneamente associarla a una nuova fase. Il comando [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-deployment.html) seguente crea una nuova implementazione e la associa a una nuova fase chiamata `beta`:
```
aws apigateway create-deployment \
--rest-api-id rest-api-id \
--stage-name beta
```
------
Per implementare nuovamente un'API, esegui la stessa procedura. È possibile riutilizzare la stessa fase.
## Fasi successive per l'implementazione di un'API
Di seguito sono riportati i passaggi successivi per l'implementazione dell'API.
Modifica delle impostazioni di fase
Dopo che un'API è stata distribuita, puoi modificare le impostazioni delle fasi per abilitare o disabilitare la cache, la registrazione o il throttling delle richieste dell'API. Puoi inoltre scegliere un certificato client per consentire al back-end di autenticare API Gateway e impostare le variabili delle fasi per passare il contesto della distribuzione all'integrazione dell'API al runtime. Per ulteriori informazioni, consulta [Modifica delle impostazioni di fase](set-up-stages.md#how-to-stage-settings)
Dopo avere modificato le impostazioni della fase, per renderle effettive sarà necessario eseguire di nuovo la ridistribuzione dell'API.
Se le impostazioni aggiornate, come l'abilitazione della registrazione, richiedono un nuovo ruolo IAM, puoi aggiungere il ruolo IAM richiesto senza ridistribuire l'API. Tuttavia potrebbero essere necessari alcuni minuti prima che il nuovo ruolo IAM diventi effettivo. Fino ad allora, le tracce delle chiamate API non vengono registrate, anche se hai abilitato l'opzione di registrazione.
Scelta di diverse combinazioni di fase-implementazione
Dal momento che una distribuzione rappresenta una snapshot dell'API e una fase definisce un percorso in una snapshot, puoi scegliere combinazioni diverse di distribuzione-fase per controllare il modo in cui gli utenti effettuano chiamate nelle diverse versioni dell'API. Ciò risulta utile se ad esempio desideri eseguire il rollback a uno stato precedente della distribuzione dell'API o unire una branca privata dell'API in quella pubblica.
La procedura seguente illustra come eseguire questa operazione tramite **Stage Editor (Editor fasi)** nella console API Gateway. Si presume che un'API sia stata distribuita più di una volta.
1. Se non sei già nel riquadro **Fasi**, nel pannello di navigazione principale, scegli **Fasi**.
1. Seleziona la fase da aggiornare.
1. Nella scheda **Cronologia delle distribuzioni** seleziona l'implementazione da utilizzare per la fase.
1. Scegli **Cambia implementazione attiva**.
1. Conferma di voler cambiare l'implementazione attiva e scegli **Cambia implementazione attiva** nella finestra di dialogo **Rendi attiva l'implementazione**.
Passare i dati specifici dell'implementazione all'API.
Per una distribuzione, puoi impostare o modificare le variabili delle fasi per passare i dati specifici della distribuzione all'integrazione dell'API in fase di runtime. Puoi eseguire questa operazione nella scheda **Stage Variables (Variabili di fase)** in **Stage Editor (Editor fasi)**. Per ulteriori informazioni, consulta le istruzioni in [Utilizzo delle variabili di fase per una REST API in Gateway API](stage-variables.md).
# Configurazione di una fase per una REST API in Gateway API
Una fase è un riferimento con nome a un'implementazione, corrispondente a uno snapshot dell'API. Utilizzare una [Stage (Fase)](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html) per gestire e ottimizzare una specifica distribuzione. Ad esempio, puoi configurare le impostazioni di fase per abilitare la memorizzazione nella cache, personalizzare il throttling della richiesta, configurare la registrazione, definire le variabili di fase o collegare una release Canary a scopi di test. La sezione seguente illustra come creare e configurare la fase.
## Creazione di una nuova fase
Dopo la distribuzione iniziale, puoi aggiungere altre fasi e associarle alle distribuzioni esistenti. Puoi usare la console API Gateway per creare una nuova fase oppure puoi scegliere una fase esistente durante la distribuzione di un'API. In generale, puoi aggiungere una nuova fase a una distribuzione API prima di ridistribuirla. Per creare una nuova fase mediante la console Gateway API procedi come riportato di seguito:
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 riquadro di navigazione principale scegli **Fasi** sotto un'API.
1. Dal riquadro di navigazione **Fasi** scegli **Crea fase**.
1. Per **Nome fase** immetti un nome, ad esempio **prod**.
**Nota**
I nomi di fasi possono contenere solo caratteri alfanumerici, trattini e caratteri di sottolineatura. La lunghezza massima è 128 caratteri.
1. (Facoltativo). In **Descrizione** inserisci una breve descrizione.
1. In **Implementazione** seleziona la data e l'ora dell'implementazione API esistente che intendi associare a questa fase.
1. In **Impostazioni aggiuntive** puoi specificare le impostazioni aggiuntive per la fase.
1. Scegli **Crea fase**.
## Modifica delle impostazioni di fase
Dopo una distribuzione riuscita di un'API, la fase viene popolata di impostazioni predefinite. Per modificare le impostazioni di una fase, incluso caching e registrazione delle API, puoi utilizzare la console o l'API REST di API Gateway. Se è stato modificato l’endpoint predefinito della REST API, quando si aggiorna una fase, la modifica viene propagata a tutte le fasi dell’API. La procedura seguente illustra come effettuare questa operazione tramite l'**editor della fase** della console Gateway API.
1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Scegliere una REST API.
1. Nel riquadro di navigazione principale scegli **Fasi** sotto un'API.
1. Nel riquadro **Stages (Fasi)**, selezionare il nome della fase.
1. Nella sezione **Dettagli fase** scegli **Modifica**.
1. (Facoltativo) In **Descrizione fase** modifica la descrizione.
1. In **Impostazioni aggiuntive** modifica le seguenti impostazioni:
**Impostazioni cache**
Per abilitare il caching delle API per la fase, attiva **Cache API con provisioning**. Quindi configura la memorizzazione nella cache a **livello di metodo predefinita, la capacità della cache****, la** **crittografia dei dati della cache, la cache time-to-live** **(TTL)** e tutti i requisiti per l'invalidazione della cache per chiave.
Il caching non è attivo finché non viene attivato il caching predefinito a livello di metodo o il caching a livello di metodo per un metodo specifico.
Per ulteriori informazioni sulle impostazioni della cache, consulta [Impostazioni della cache per REST APIs in API Gateway](api-gateway-caching.md).
Se abiliti la memorizzazione nella cache delle API per una fase dell'API, al tuo account potrebbe essere addebitato un costo per la memorizzazione nella cache delle API. AWS Il caching non è idoneo per il AWS piano gratuito.
**Impostazioni di limitazione (della larghezza di banda della rete)**
Per impostare le destinazioni di limitazione (della larghezza di banda della rete) a livello di fase per tutti i metodi associati a questa API, attiva **Throttling**.
Per **Rate**(Tasso), inserire un tasso di destinazione. Questa è la velocità, espressa in richieste al secondo, con cui i token vengono aggiunti al bucket di token. La velocità a livello di fase non deve essere superiore alla velocità a [livello di account](api-gateway-request-throttling.md#apig-request-throttling-account-level-limits) come specificato in [Quote per la configurazione e l’esecuzione di una REST API in Gateway API](api-gateway-execution-service-limits-table.md).
Per **Burst** (ottimizzazione), inserisci un tasso di destinazione. La frequenza di burst è la capacità del token bucket. Ciò consente di passare più richieste per un periodo di tempo rispetto al tasso di destinazione. Questo tasso di ottimizzazione a livello di fase non deve essere superiore al tasso di ottimizzazione a [livello di account](api-gateway-request-throttling.md#apig-request-throttling-account-level-limits) come specificato in [Quote per la configurazione e l’esecuzione di una REST API in Gateway API](api-gateway-execution-service-limits-table.md).
I tassi di limitazione (della larghezza di banda della rete) non sono limiti rigidi e vengono applicati sulla base del miglior tentativo. In alcuni casi, i client possono superare gli obiettivi impostati. Non fare affidamento sulla limitazione (della larghezza di banda della rete) per controllare i costi o bloccare l'accesso a un'API. Considera l'utilizzo di [Budget AWS](https://docs.aws.amazon.com/cost-management/latest/userguide/budgets-managing-costs.html) per monitorare i costi e di [AWS WAF](https://docs.aws.amazon.com/waf/latest/developerguide/waf-chapter.html) per gestire le richieste API.
**Impostazioni di firewall e certificati**
Per associare un ACL AWS WAF Web allo stage, selezionate un ACL Web dall'elenco a discesa **Web ACL**. Se si desidera, scegliere **Block API Request if WebACL cannot be evaluated (Blocca richiesta API se non è possibile valutare WebACL)**.
Per selezionare un certificato client per la fase, scegli un certificato dal menu a discesa **Certificati client**.
1. Scegli **Continua**.
1. Esamina le modifiche e scegli **Salva modifiche**.
1. **Per abilitare Amazon CloudWatch Logs per tutti i metodi associati a questa fase di questa API API Gateway, nella sezione **Logs and tracing**, scegli Modifica.**
**Nota**
Per abilitare CloudWatch i log, devi anche specificare l'ARN di un ruolo IAM che consente ad API Gateway di scrivere informazioni nei log CloudWatch per conto del tuo utente. Per farlo, scegli **Impostazioni dal pannello** di navigazione **APIs**principale. Quindi, per il **ruolo di CloudWatch registro**, inserisci l'ARN di un ruolo IAM.
Per scenari applicativi comuni, il ruolo IAM potrebbe allegare la policy gestita di [Amazon APIGateway PushToCloudWatchLogs](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AmazonAPIGatewayPushToCloudWatchLogs.html).
Il ruolo IAM deve anche contenere la seguente dichiarazione di relazione di attendibilità:
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "",
"Effect": "Allow",
"Principal": {
"Service": "apigateway.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
```
Per ulteriori informazioni CloudWatch, consulta la *[Amazon CloudWatch User Guide](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/WhatIsCloudWatch.html)*.
1. Seleziona un livello di registrazione dal menu a discesa **CloudWatch Logs.** I livelli di registrazione dei log sono:
+ **Inattivo**: la registrazione dei log non è attivata per questa fase.
+ **Solo errori**: la registrazione dei log è abilitata solo per gli errori.
+ **Errori e log informativi**: la registrazione dei log è abilitata per tutti gli eventi.
1. Seleziona **Data tracing** per fare in modo che API Gateway riferisca alla registrazione CloudWatch della traccia dei dati per la tua fase. Questo può essere utile per la risoluzione dei problemi APIs, ma può comportare la registrazione di dati sensibili.
**Nota**
Ti consigliamo di non utilizzare il **tracciamento dei dati** per la produzione. APIs
1. Seleziona **Metriche dettagliate** per fare in modo che API Gateway CloudWatch riferisca alle metriche API di`API calls`,`Latency`, `Integration latency``400 errors`, e. `500 errors` Per ulteriori informazioni CloudWatch, consulta il [monitoraggio di base e il monitoraggio dettagliato](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/cloudwatch-metrics-basic-detailed.html) nella Amazon CloudWatch User Guide.
**Importante**
Al tuo account viene addebitato l'accesso ai parametri a livello di metodo, ma non ai CloudWatch parametri a livello di API o a livello di fase.
1. Per abilitare la registrazione degli accessi a una destinazione, attiva **Registrazione accesso personalizzato**.
1. In **ARN di destinazione del log degli accessi** inserisci l'ARN di un gruppo di log o un flusso Firehose.
Il formato dell'ARN per Firehose è `arn:aws:firehose:{region}:{account-id}:deliverystream/amazon-apigateway-{your-stream-name}`. Il nome del flusso di Firehose deve essere `amazon-apigateway-{your-stream-name}`.
1. In **Formato log** immetti un formato di log. Per ulteriori informazioni sui formati di log di esempio, consulta [CloudWatch formati di registro per API Gateway](set-up-logging.md#apigateway-cloudwatch-log-formats).
1. Per abilitare il tracciamento [AWS X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/xray-services-apigateway.html) per la fase API, seleziona **Tracciamento X-Ray**. Per ulteriori informazioni, consulta [Traccia delle richieste degli utenti alle REST API utilizzando X-Ray in Gateway API](apigateway-xray.md).
1. Scegli **Salva modifiche**. Implementa nuovamente l'API per rendere effettive le nuove impostazioni.
## Sostituzione delle impostazioni a livello di fase
Dopo aver personalizzato le impostazioni a livello di fase, è possibile sostituirle per ogni metodo API. Alcune di queste opzioni potrebbero comportare costi aggiuntivi per il tuo Account AWS.
1. Per configurare le sostituzioni dei metodi, espandi la fase nel pannello di navigazione secondario, quindi scegli un metodo.
![\[Espandi la fase nel pannello di navigazione secondario e scegli un metodo.\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/method-override-view-new-console.png)
1. Per **Sostituzioni del metodo** scegli **Modifica**.
1. Per attivare CloudWatch le impostazioni a livello di metodo, per **CloudWatch Registri**, seleziona un livello di registrazione.
1. Per attivare la registrazione dei log della traccia dei dati per il metodo, seleziona **Tracciamento dei dati.**
**Nota**
Si consiglia di non utilizzare il tracciamento **dei dati** per la produzione. APIs
1. Per attivare i parametri dettagliati a livello di metodo, seleziona **Parametri dettagliati**. Al tuo account viene addebitato l'accesso alle metriche a livello di metodo, ma non alle CloudWatch metriche a livello di API o a livello di fase.
1. Per attivare la limitazione (della larghezza di banda della rete) a livello di metodo, seleziona **Throttling**. Immetti le opzioni appropriate a livello di metodo. Per ulteriori informazioni sulla limitazione, consulta [Limita le richieste al tuo REST APIs per una migliore velocità di trasmissione in API Gateway](api-gateway-request-throttling.md).
1. Per configurare la cache a livello di metodo, seleziona **Abilita cache metodo**. La modifica dell'impostazione del caching predefinito a livello di metodo nei **dettagli della fase** non influisce su questa impostazione.
1. Scegli **Save** (Salva).
# Aggiungi un'API API Gateway REST come destinazione per Amazon Bedrock AgentCore Gateway
Un Amazon Bedrock AgentCore Gateway offre agli sviluppatori di agenti AI un modo sicuro per esporre il tuo API Gateway REST APIs come strumenti compatibili con il Model Context Protocol (MCP). AgentCore Gateway utilizza obiettivi per definire gli strumenti. Quando aggiungi la tua fase come destinazione, il tuo Gateway diventa un singolo URL MCP che consente l'accesso agli strumenti per un agente. Per ulteriori informazioni, consulta le [fasi dell'API REST di API Gateway come obiettivi](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-target-api-gateway.html) nella *Amazon Bedrock AgentCore Gateway Developer Guide*.
Gli obiettivi API Gateway collegano il AgentCore gateway alle fasi del REST APIs. Puoi includere l'intera fase come obiettivo o selezionare risorse. Dopo aver creato l'oggetto API Gateway, AgentCore Gateway traduce le richieste MCP in entrata in richieste HTTP e gestisce la formattazione della risposta. I client MCP possono recuperare la documentazione dell'API utilizzando il metodo e richiamarla utilizzando il `tools/list` metodo. APIs `tools/call`
## Considerazioni
Le seguenti considerazioni potrebbero influire sull'utilizzo dell'aggiunta di una fase come destinazione a un Gateway: AgentCore
+ È necessario disporre già di un AgentCore Gateway.
+ Sono supportati solo APIs i REST pubblici.
+ L'endpoint predefinito dell'API non può essere disabilitato.
+ Per ogni metodo dell'API deve essere definito un [nome di operazione](https://docs.aws.amazon.com/apigateway/latest/api/API_PutMethod.html#apigw-PutMethod-request-operationName) oppure è necessario creare un nome sostitutivo quando si aggiunge lo stage come destinazione. Questo nome viene utilizzato come nome dello strumento utilizzato dagli agenti per interagire con il metodo.
+ È possibile utilizzare `API_KEY` tipi di provider di `GATEWAY_IAM_ROLE` credenziali per Outbound Auth per consentire al gateway di accedere all'API. `NO_AUTH` Il provider di `API_KEY` credenziali è definito da Gateway. AgentCore Puoi utilizzare la tua chiave API Gateway esistente. Per ulteriori informazioni, consulta [Configurazione dell'autenticazione in uscita](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-outbound-auth.html).
+ Se utilizzi un pool di utenti Amazon Cognito o un autorizzatore Lambda per controllare l'accesso alla tua API, i client MCP non possono accedervi.
+ L'API deve trovarsi nello stesso account e nella stessa regione del gateway. AgentCore
## Aggiungi una fase di un'API come destinazione per un AgentCore gateway
La procedura seguente mostra come aggiungere una fase di un'API come destinazione per un AgentCore Gateway.
**Per aggiungere una fase di un'API come destinazione per un AgentCore Gateway**
1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Scegli un'API REST distribuita in una fase.
1. Nel riquadro di navigazione principale scegli **Fasi**.
1. Scegli **Stage actions**, quindi scegli **Create MCP target.**
1. Per **AgentCore Gateway**, selezionate un AgentCore Gateway.
1. Per **Nome destinazione**, inserisci un nome di destinazione.
1. Per **Descrizione dell'oggetto**, inserisci una descrizione.
1. Conserva l'API e lo stage forniti.
1. Per **le risorse Select API**, seleziona le risorse della tua API a cui possono accedere gli agenti che utilizzano il tuo AgentCore Gateway.
Se non selezioni una risorsa, un agente non può visualizzare la documentazione o richiamare l'endpoint.
1. La combinazione della risorsa e del metodo sono le operazioni dello strumento. Se l'operazione non ha un nome, crea un nome override.
È inoltre possibile definire un nome di operazione per un metodo al momento della creazione.
1. Per la **configurazione di autenticazione in uscita**, scegli **IAM Role**, **Nessuna autorizzazione** o **API** key.
1. Seleziona **Crea destinazione**.
Per visualizzare tutti i AgentCore gateway che hanno accesso al tuo APIs, scegli la sezione **MCP targets** nel pannello di navigazione principale. In questa sezione, puoi creare un target MCP per qualsiasi API nella tua regione distribuita in una fase. Scegli **Crea obiettivo MCP** e segui i passaggi precedenti.
Puoi anche visualizzare gli strumenti disponibili per il tuo target e modificarlo nella console AgentCore Gateway. Per ulteriori informazioni, consulta [Aggiungere obiettivi a un AgentCore gateway esistente](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-building-adding-targets.html).
# Eliminazione di una fase
Quando una fase non è più necessaria, puoi eliminarla per evitare di pagare per risorse inutilizzate. Le fasi seguenti mostrano come utilizzare la console API Gateway per eliminare una fase.
**avvertimento**
L'eliminazione di una fase potrebbe rendere inutilizzabile parte o tutta l'API corrispondente per i chiamanti dell'API. L'eliminazione di una fase non può essere annullata, tuttavia è possibile creare nuovamente una fase e associarla alla stessa distribuzione.
1. Accedere 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 riquadro di navigazione principale scegli **Fasi**.
1. Nel riquadro **Fasi** scegli la fase che vuoi eliminare, quindi seleziona **Operazioni fase**, **Elimina fase**.
1. Quando richiesto, immetti **confirm**, quindi scegli **Elimina**.
# Configurazione dei tag per una fase API in Gateway API
In API Gateway è possibile aggiungere un tag a una fase API, rimuoverlo o visualizzarlo. A tale scopo è possibile utilizzare la console API Gateway, la AWS CLI/l'SDK o l'API REST di API Gateway.
Una fase può anche ereditare i tag dalla sua API REST padre. Per ulteriori informazioni, consulta [Eredità dei tag nell'API di Amazon API Gateway V1](apigateway-tagging-supported-resources.md#apigateway-tagging-inheritance).
Per ulteriori informazioni sull'assegnazione di tag alle risorse dell'API Gateway, consulta [Tagging delle risorse API Gateway](apigateway-tagging.md).
**Topics**
+ [Configurare i tag per una fase API utilizzando la console si API Gateway](#set-up-tags-using-console)
+ [Configurazione dei tag per una fase API usando AWS CLI](#set-up-tags-using-cli)
+ [Impostare i tag per una fase API utilizzando l'API REST di API Gateway](#set-up-tags-using-api)
## Configurare i tag per una fase API utilizzando la console si API Gateway
La procedura seguente descrive come configurare i tag per una fase API.
**Per configurare i tag per una fase API mediante la console API Gateway**
1. Accedere alla console API Gateway.
1. Seleziona un'API esistente o crea una nuova API che includa risorse, metodi e le integrazioni corrispondenti.
1. Seleziona una fase o distribuisci l'API in una nuova fase.
1. Nel riquadro di navigazione principale scegli **Fasi**.
1. Seleziona la scheda **Tags** (Tag). Potrebbe essere necessario scegliere il pulsante freccia destra per visualizzare la scheda.
1. Scegliere **Gestisci tag**.
1. In **Editor di tag** scegli **Aggiungi nuovo tag**. Immetti una chiave di tag (ad esempio, `Department`) nella colonna **Key (Chiave)**, quindi immetti un valore di tag (ad esempio, `Sales`) nella colonna **Value (Valore)**. Per salvare il tag scegli **Salva**.
1. Se necessario, ripeti la fase 5 per aggiungere altri tag alla fase API. Il numero massimo di tag per ogni fase è 50.
1. Per rimuovere un tag esistente dalla fase scegli **Rimuovi**.
1. Se l'API è stata implementata in precedenza nella console API Gateway, sarà necessario ridistribuirla per rendere effettive le modifiche.
## Configurazione dei tag per una fase API usando AWS CLI
È possibile impostare i tag per una fase API usando AWS CLI con il comando [create-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-stage.html) o il comando [tag-resource](https://docs.aws.amazon.com/cli/latest/reference/apigateway/tag-resource.html). È possibile eliminare uno o più tag da una fase API eseguendo il comando [untag-resource](https://docs.aws.amazon.com/cli/latest/reference/apigateway/untag-resource.html).
Il comando [create-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-stage.html) seguente aggiunge un tag durante la creazione di una fase `test`:
```
aws apigateway create-stage --rest-api-id abc1234 --stage-name test --description 'Testing stage' --deployment-id efg456 --tag Department=Sales
```
Il comando [tag-resource](https://docs.aws.amazon.com/cli/latest/reference/apigateway/tag-resource.html) seguente aggiunge un tag a una fase `prod`:
```
aws apigateway tag-resource --resource-arn arn:aws:apigateway:us-east-2::/restapis/abc123/stages/prod --tags Department=Sales
```
Il comando [untag-resource](https://docs.aws.amazon.com/cli/latest/reference/apigateway/untag-resource.html) seguente rimuove il tag `Department=Sales` dalla fase `test`:
```
aws apigateway untag-resource --resource-arn arn:aws:apigateway:us-east-2::/restapis/abc123/stages/test --tag-keys Department
```
## Impostare i tag per una fase API utilizzando l'API REST di API Gateway
È possibile configurare i tag per una fase API utilizzando l'API REST di API Gateway con una delle operazioni seguenti:
+ Richiamare [https://docs.aws.amazon.com/apigateway/latest/api/API_TagResource.html](https://docs.aws.amazon.com/apigateway/latest/api/API_TagResource.html) per aggiungere tag a una fase API.
+ Richiamare [https://docs.aws.amazon.com/apigateway/latest/api/API_UntagResource.html](https://docs.aws.amazon.com/apigateway/latest/api/API_UntagResource.html) per eliminare uno o più tag da una fase API.
+ Richiamare [https://docs.aws.amazon.com/apigateway/latest/api/API_CreateStage.html](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateStage.html) per aggiungere uno o più tag a una fase API in fase di creazione.
È anche possibile richiamare [https://docs.aws.amazon.com/apigateway/latest/api/API_GetTags.html](https://docs.aws.amazon.com/apigateway/latest/api/API_GetTags.html) per descrivere i tag in una fase API.
### Aggiunta di tag a una fase API
Dopo avere distribuito un'API (`m5zr3vnks7`) in una fase (`test`), è possibile aggiungere tag alla fase richiamando [https://docs.aws.amazon.com/apigateway/latest/api/API_TagResource.html](https://docs.aws.amazon.com/apigateway/latest/api/API_TagResource.html). L'Amazon Resource Name (ARN) richiesto della fase (`arn:aws:apigateway:us-east-1::/restapis/m5zr3vnks7/stages/test`) deve avere codifica URL (`arn%3Aaws%3Aapigateway%3Aus-east-1%3A%3A%2Frestapis%2Fm5zr3vnks7%2Fstages%2Ftest`).
```
PUT /tags/arn%3Aaws%3Aapigateway%3Aus-east-1%3A%3A%2Frestapis%2Fm5zr3vnks7%2Fstages%2Ftest
{
"tags" : {
"Department" : "Sales"
}
}
```
Puoi anche usare la richiesta precedente per aggiornare un tag esistente in un nuovo valore.
È possibile aggiungere tag a una fase richiamando [https://docs.aws.amazon.com/apigateway/latest/api/API_CreateStage.html](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateStage.html) per la relativa creazione:
```
POST /restapis//stages
{
"stageName" : "test",
"deploymentId" : "adr134",
"description" : "test deployment",
"cacheClusterEnabled" : "true",
"cacheClusterSize" : "500",
"variables" : {
"sv1" : "val1"
},
"documentationVersion" : "test",
"tags" : {
"Department" : "Sales",
"Division" : "Retail"
}
}
```
### Rimozione di tag da una fase API
Per rimuovere il tag `Department` dalla fase, richiamare [https://docs.aws.amazon.com/apigateway/latest/api/API_UntagResource.html](https://docs.aws.amazon.com/apigateway/latest/api/API_UntagResource.html):
```
DELETE /tags/arn%3Aaws%3Aapigateway%3Aus-east-1%3A%3A%2Frestapis%2Fm5zr3vnks7%2Fstages%2Ftest?tagKeys=Department
Host: apigateway.us-east-1.amazonaws.com
Authorization: ...
```
Per rimuovere più di un tag, usare un elenco di chiavi di tag separate da virgole nell'espressione di query, ad esempio `?tagKeys=Department,Division,…`.
### Descrizione dei tag per una fase API
Per descrivere i tag esistenti per una fase specifica, richiamare [https://docs.aws.amazon.com/apigateway/latest/api/API_GetTags.html](https://docs.aws.amazon.com/apigateway/latest/api/API_GetTags.html):
```
GET /tags/arn%3Aaws%3Aapigateway%3Aus-east-1%3A%3A%2Frestapis%2Fm5zr3vnks7%2Fstages%2Ftags
Host: apigateway.us-east-1.amazonaws.com
Authorization: ...
```
La risposta con esito positivo è simile a quella riportata di seguito.
```
200 OK
{
"_links": {
"curies": {
"href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-tags-{rel}.html",
"name": "tags",
"templated": true
},
"tags:tag": {
"href": "/tags/arn%3Aaws%3Aapigateway%3Aus-east-1%3A%3A%2Frestapis%2Fm5zr3vnks7%2Fstages%2Ftags"
},
"tags:untag": {
"href": "/tags/arn%3Aaws%3Aapigateway%3Aus-east-1%3A%3A%2Frestapis%2Fm5zr3vnks7%2Fstages%2Ftags{?tagKeys}",
"templated": true
}
},
"tags": {
"Department": "Sales"
}
}
```
# Utilizzo delle variabili di fase per una REST API in Gateway API
Le variabili di fase sono coppie chiave-valore che è possibile definire come attributi di configurazione associati a una fase di implementazione di una REST API. Fungono da variabili di ambiente e possono essere utilizzate nei modelli di mappatura e configurazione dell'API. Con le fasi di implementazione in Gateway API, puoi gestire più fasi di rilascio per ogni API e utilizzare le variabili di fase per configurare una fase di implementazione dell'API per l'interazione con endpoint di backend diversi.
Le variabili di fase non sono destinate ad essere utilizzate per i dati sensibili, come le credenziali. Per trasferire dati sensibili alle integrazioni, usa un AWS Lambda autorizzatore. È possibile passare dati sensibili alle integrazioni nell'output del provider di autorizzazioni Lambda. Per ulteriori informazioni, consulta [Output da un sistema di autorizzazione Lambda di Gateway API](api-gateway-lambda-authorizer-output.md).
## Casi d'uso per le variabili di fase
Di seguito sono riportati alcuni casi d'uso per le variabili di fase.
**Specificare un endpoint di backend diverso**
L'API può passare una richiesta `GET` come proxy HTTP all'host web di backend. Puoi utilizzare una variabile di fase per far sì che, quando i chiamanti dell'API invocano l'endpoint di produzione, Gateway API chiami `example.com`. Quindi, quando i chiamanti dell'API invocano la fase beta, Gateway API chiama un host web diverso, ad esempio `beta.example.com`. Analogamente, le variabili di fase si possono utilizzare per specificare un nome di funzione AWS Lambda per ogni fase dell'API. Non puoi utilizzare una variabile di fase per impostare un endpoint di integrazione diverso, ad esempio per far sì che la richiesta `GET` punti a un'integrazione di proxy HTTP in una fase e a un'integrazione di proxy Lambda in un'altra fase.
Quando si specifica un nome di funzione Lambda come valore della variabile di fase, è necessario configurare manualmente le autorizzazioni per la funzione Lambda. Quando specifichi una funzione Lambda nella console API Gateway, verrà visualizzato un AWS CLI comando per configurare le autorizzazioni appropriate. A tale scopo è inoltre possibile utilizzare il seguente AWS CLI comando.
```
aws lambda add-permission --function-name "arn:aws:lambda:us-east-2:123456789012:function:my-function" --source-arn "arn:aws:execute-api:us-east-2:123456789012:api_id/*/HTTP_METHOD/resource" --principal apigateway.amazonaws.com --statement-id apigateway-access --action lambda:InvokeFunction
```
**Passare le informazioni utilizzando modelli di mappatura**
Puoi accedere alle variabili di fase nei modelli di mappatura o passare i parametri di configurazione a AWS Lambda o al backend HTTP. Ad esempio, potrebbe essere necessario riutilizzare la stessa funzione Lambda per più fasi nell'API, ma la funzione deve leggere i dati da una tabella di Amazon DynamoDB diversa a seconda della fase. Nei modelli di mappatura che generano la richiesta per la funzione Lambda è possibile usare le variabili di fase per passare il nome della tabella a Lambda.
Per utilizzare una variabile di fase, è necessario prima configurare una variabile di fase e quindi assegnarle un valore. Ad esempio, per personalizzare l'endpoint di integrazione HTTP, crea prima la variabile di fase `url` e poi, nella richiesta di integrazione dell'API, inserisci il valore della variabile di fase **http://\$1\$1stageVariables.url\$1**. Questo valore indica ad API Gateway di sostituire la variabile di fase `${}` al runtime, a seconda della fase di esecuzione dell'API. Per ulteriori informazioni, consulta [Imposta le variabili di fase per REST APIs in API Gateway](how-to-set-stage-variables-aws-console.md).
# Imposta le variabili di fase per REST APIs in API Gateway
Questa sezione mostra come configurare le variabili di fase per due fasi di implementazione di un'API di esempio utilizzando la console Gateway Amazon API. Per capire come utilizzare le variabili di fase in Gateway API, ti consigliamo di seguire tutte le procedure illustrate in questa sezione.
## Prerequisiti
Prima di iniziare, verifica che siano soddisfatti i seguenti requisiti preliminari:
+ Devi disporre di un'API in API Gateway. Segui le istruzioni in [Sviluppa REST APIs in API Gateway](rest-api-develop.md).
+ Devi avere distribuito l'API almeno una volta. Segui le istruzioni in [Implementazione di REST API in Gateway API](how-to-deploy-api.md).
+ Devi aver creato la prima fase per un'API distribuita. Segui le istruzioni in [Creazione di una nuova fase](set-up-stages.md#how-to-create-stage-console).
## Invocazione di un endpoint HTTP mediante un'API con una variabile di fase
Questa procedura descrive come creare una variabile di fase per un endpoint HTTP e due fasi per l'API. Inoltre, vengono create le variabili di fase `url`, `stageName` e `function`, che vengono utilizzate nelle procedure seguenti di questa sezione.
**Per invocare un endpoint HTTP mediante un'API con una variabile di fase**
1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Crea un'API, quindi crea un metodo `GET` nella risorsa radice dell'API. Imposta il tipo di integrazione su **HTTP** e imposta l'**URL dell'endpoint** su **http://\$1\$1stageVariables.url\$1**.
1. Implementa l'API in una nuova fase denominata **beta**.
1. Nel riquadro di navigazione scegli **Fasi**, quindi seleziona la fase **beta**.
1. Nella scheda **Variabili di fase** scegli **Modifica**.
1. Scegli **Aggiungi variabile di fase**.
1. In **Nome**, inserisci **url**. In **Valore**, inserisci **httpbin.org/get**.
1. Scegli **Aggiungi variabile di fase**, quindi effettua le seguenti operazioni:
In **Nome**, inserisci **stageName**. In **Valore**, inserisci **beta**.
1. Scegli **Aggiungi variabile di fase**, quindi effettua le seguenti operazioni:
In **Nome**, inserisci **function**. In **Valore**, inserisci **HelloWorld**.
1. Scegli **Save** (Salva).
1. Ora crea una seconda fase. Dal riquadro di navigazione **Fasi** scegli **Crea fase**. In **Stage name (Nome fase)** immettere **prod**. Seleziona un'implementazione recente da **Implementazione** e scegli **Crea**.
1. Come per la fase **beta**, imposta le stesse tre variabili di fase (**url**, **version** e **function**) su valori diversi (rispettivamente **petstore-demo-endpoint.execute-api.com/petstore/pets**, **prod** e **HelloEveryone**).
1. Nel riquadro di navigazione **Stages (Fasi)** scegli **beta**. In **Dettagli fase** scegli l'icona Copia per copiare l'URL di richiamo dell'API, quindi immetti l'URL di richiamo dell'API in un browser Web. Viene avviata la richiesta `GET` della fase **beta** nella risorsa radice dell'API.
**Nota**
Il collegamento **Invoke URL** (URL chiamata) punta alla risorsa radice dell'API nella rispettiva fase **beta**. L'immissione dell'URL in un browser Web chiama il metodo `GET` della fase **beta** nella risorsa radice. Se i metodi vengono definiti nelle risorse figlio e non nella risorsa radice stessa, scegliendo l'URL in un browser Web viene restituita la risposta di errore `{"message":"Missing Authentication Token"}`. In questo caso, devi aggiungere al collegamento **Invoke URL (URL chiamata)** il nome di una risorsa figlio specifica.
1. La risposta che si ottiene dalla richiesta `GET` della fase **beta** è mostrata più avanti. Puoi verificare il risultato anche utilizzando un browser per accedere a **http://httpbin.org/get**. Questo valore è stato assegnato alla variabile `url` nella fase **beta**. Le due risposte sono identiche.
1. Nel riquadro di navigazione **Stages (Fasi)** scegli la fase **prod**. In **Dettagli fase** scegli l'icona Copia per copiare l'URL di richiamo dell'API, quindi immetti l'URL di richiamo dell'API in un browser Web. Viene avviata la richiesta `GET` della fase **prod** nella risorsa radice dell'API.
1. La risposta che si ottiene dalla richiesta `GET` della fase **prod** è mostrata più avanti. È possibile verificare il risultato utilizzando un browser per accedere a **http://.execute-api. petstore-demo-endpoint com/petstore/pets**. Questo valore è stato assegnato alla variabile `url` nella fase **prod**. Le due risposte sono identiche.
## Passare i metadati specifici della fase in un backend HTTP
Questa procedura descrive come utilizzare un valore di variabile di fase in un'espressione di parametri di query per passare i metadati specifici delle fasi in un back-end HTTP. Utilizzeremo la variabile di fase `stageName` dichiarata nella procedura precedente.
**Per passare metadati specifici della fase in un backend HTTP**
1. Nel riquadro di navigazione **Resource (Risorsa)** scegli il metodo **GET**.
Per aggiungere un parametro della stringa di query all'URL del metodo, seleziona la scheda **Richiesta del metodo**, quindi nella sezione **Impostazioni della richiesta del metodo**, scegli **Modifica**.
1. Scegli i **parametri della stringa di query URL** ed effettua le seguenti operazioni:
1. Scegliere **Add query string (Aggiungi stringa di query)**.
1. In **Nome**, inserisci **stageName**.
1. Mantieni **Obbligatorio** e **Caching** disattivati.
1. Scegli **Save** (Salva).
1. Scegli la scheda **Richiesta di integrazione**, quindi seleziona **Modifica** nella sezione **Impostazioni della richiesta di integrazione**.
1. Per **URL dell'endpoint** aggiungi **?stageName=\$1\$1stageVariables.stageName\$1** al valore URL definito in precedenza, in modo che sia l'intero **URL dell'endpoint** sia **http://\$1\$1stageVariables.url\$1?stageName=\$1\$1stageVariables.stageName\$1**.
1. Scegli **Implementa API** e seleziona la fase **beta**.
1. Nel riquadro di navigazione principale scegli **Fasi**. Nel riquadro di navigazione **Stages (Fasi)** scegli **beta**. In **Dettagli fase** scegli l'icona Copia per copiare l'URL di richiamo dell'API, quindi immetti l'URL di richiamo dell'API in un browser Web.
**Nota**
Qui usiamo la fase beta perché l'endpoint HTTP (come specificato dalla variabile `url`, "http://httpbin.org/get") accetta le espressioni dei parametri di query e le restituisce come oggetto `args` nella rispettiva risposta.
1. Si ottiene la risposta seguente. `beta`, assegnato alla variabile di fase `stageName`, viene passata nel back-end come argomento `stageName`.
![\[Risposta dal metodo GET dell'API con un endpoint HTTP utilizzando la variabile di fase url.\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/stageVariables-new-console-invoke-beta-stage-with-url-and-stageName-response.png)
## Invocare una funzione Lambda attraverso un'API con una variabile di fase
Questa procedura descrive come utilizzare una variabile di fase per chiamare una funzione Lambda come back-end dell'API. Utilizzerai la variabile di fase `function` dichiarata in [Invocazione di un endpoint HTTP mediante un'API con una variabile di fase](#how-to-set-stage-variables-aws-console-http-endpoint).
Quando imposti una funzione Lambda come valore di una variabile di fase, usa il nome locale della funzione, se possibile includendo l'alias o la specifica della versione, come in **HelloWorld**, **HelloWorld:1** o **HelloWorld:alpha**. Non usare l'ARN della funzione (ad esempi, **arn:aws:lambda:us-east-1:123456789012:function:HelloWorld**). La console API Gateway assume il valore della variabile di fase per una funzione Lambda come nome di funzione non qualificato ed espande la variabile di fase specificata in un ARN.
**Per invocare la funzione Lambda mediante un'API con una variabile di fase**
1. Crea una funzione Lambda denominata **HelloWorld** utilizzando il runtime Node.js predefinito. Il codice deve contenere quanto segue:
```
export const handler = function(event, context, callback) {
if (event.stageName)
callback(null, 'Hello, World! I\'m calling from the ' + event.stageName + ' stage.');
else
callback(null, 'Hello, World! I\'m not sure where I\'m calling from...');
};
```
Per ulteriori informazioni su come creare una funzione Lambda, consulta [Nozioni di base sulla console REST API](getting-started-rest-new-console.md#getting-started-rest-new-console-create-function).
1. Nel riquadro **Risorse** seleziona **Crea risorsa**, quindi procedi come segue:
1. Per **Percorso risorsa**, seleziona **/**.
1. Per **Resource Name (Nome risorsa)** immetti **lambdav1**.
1. Scegli **Crea risorsa**.
1. Scegli la risorsa **/lambdav1** e poi scegli **Crea metodo**.
Successivamente, esegui queste operazioni:
1. Per **Tipo di metodo** seleziona **GET**.
1. Per **Tipo di integrazione** seleziona **Funzione Lambda**.
1. Mantieni l'opzione **Integrazione proxy Lambda** disattivata.
1. Per **Lambda function (Funzione Lambda)**, immetti `${stageVariables.function}`.
![\[Creazione di un metodo GET integrato con una funzione Lambda come specificato dalla variabile di fase function\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/stageVariables-new-console-create-lambda-get-method.png)
**Suggerimento**
Quando richiesto da **Aggiungi comando di autorizzazione**, copia il comando [add-permission](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html). Esegui il comando per ciascuna funzione Lambda che sarà assegnata alla variabile di fase `function`. Ad esempio, se il valore di `$stageVariables.function` è `HelloWorld`, esegui il comando AWS CLI seguente:
```
aws lambda add-permission --function-name arn:aws:lambda:us-east-1:account-id:function:HelloWorld --source-arn arn:aws:execute-api:us-east-1:account-id:api-id/*/GET/lambdav1 --principal apigateway.amazonaws.com --statement-id statement-id-guid --action lambda:InvokeFunction
```
In caso contrario, riceverai una risposta `500 Internal Server Error` quando verrà invocato il metodo. Sostituisci `${stageVariables.function}` con il nome della funzione Lambda assegnato alla variabile di fase.
![\[AWS CLI comando per aggiungere il permesso alla funzione Lambda da invocare dal metodo creato.\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/stageVariables-new-console-add-permission-to-lambda-function.png)
1. Scegli **Crea metodo**.
1. Implementa l'API in entrambe le fasi **prod** e **beta**.
1. Nel riquadro di navigazione principale scegli **Fasi**. Nel riquadro di navigazione **Stages (Fasi)** scegli **beta**. In **Dettagli fase** scegli l'icona Copia per copiare l'URL di richiamo dell'API, quindi immetti l'URL di richiamo dell'API in un browser Web. Aggiungi **/lambdav1** all'URL prima di premere invio.
Si ottiene la risposta seguente.
```
"Hello, World! I'm not sure where I'm calling from..."
```
## Passaggio dei metadati specifici delle fasi a una funzione Lambda mediante una variabile di fase
Questa procedura descrive come utilizzare una variabile di fase per passare i metadata di configurazione specifici delle fasi in una funzione Lambda. Crei un metodo `POST` e un modello di mappatura di input per generare il payload utilizzando la variabile di fase `stageName` dichiarata precedentemente.
**Per passare i metadati specifici delle fasi a una funzione Lambda mediante una variabile di fase**
1. Scegli la risorsa **/lambdav1** e poi scegli **Crea metodo**.
Successivamente, esegui queste operazioni:
1. Per **Tipo di metodo** seleziona **POST**.
1. Per **Tipo di integrazione** seleziona **Funzione Lambda**.
1. Mantieni l'opzione **Integrazione proxy Lambda** disattivata.
1. Per **Lambda function (Funzione Lambda)**, immetti `${stageVariables.function}`.
1. Quando richiesto da **Aggiungi comando di autorizzazione**, copia il comando [add-permission](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html). Esegui il comando per ciascuna funzione Lambda che sarà assegnata alla variabile di fase `function`.
1. Scegli **Crea metodo**.
1. Scegli la scheda **Richiesta di integrazione**, quindi seleziona **Modifica** nella sezione **Impostazioni della richiesta di integrazione**.
1. Scegli **Modelli di mappatura**, quindi seleziona **Aggiungi modello di mappatura**.
1. Per **Tipo di contenuto** inserisci **application/json**.
1. Per **Corpo del modello** inserisci il seguente modello:
```
#set($inputRoot = $input.path('$'))
{
"stageName" : "$stageVariables.stageName"
}
```
**Nota**
In un modello di mappatura il riferimento a una variabile di fase deve essere racchiuso tra apici (come in `"$stageVariables.stageName"` o `"${stageVariables.stageName}"`), mentre altrove non si devono utilizzare gli apici (come in `${stageVariables.function}`).
1. Scegli **Save** (Salva).
1. Implementa l'API in entrambe le fasi **beta** e **prod**.
1. Per utilizzare un client REST API per passare i metadati specifici della fase, procedi come segue:
1. Nel riquadro di navigazione **Stages (Fasi)** scegli **beta**. In **Dettagli fase** scegli l'icona Copia per copiare l'URL di richiamo dell'API, quindi immetti l'URL di richiamo dell'API nel campo di input di un client REST API. Aggiungi **/lambdav1** prima di inviare la richiesta.
Si ottiene la risposta seguente.
```
"Hello, World! I'm calling from the beta stage."
```
1. Nel riquadro di navigazione **Fasi** scegli **prod**. In **Dettagli fase** scegli l'icona Copia per copiare l'URL di richiamo dell'API, quindi immetti l'URL di richiamo dell'API nel campo di input di un client REST API. Aggiungi **/lambdav1** prima di inviare la richiesta.
Si ottiene la risposta seguente.
```
"Hello, World! I'm calling from the prod stage."
```
1. Per utilizzare la funzionalità **Test** per trasmettere i metadati specifici della fase, procedi come segue:
1. Nel riquadro di navigazione **Risorse** scegli la scheda **Test**. Potrebbe essere necessario scegliere il pulsante freccia destra per visualizzare la scheda.
1. Per **function** immetti **HelloWorld**.
1. Per **stageName** immetti **beta**.
1. Scegli **Test (Esegui test)**. Non è necessario aggiungere un corpo alla richiesta `POST`.
Si ottiene la risposta seguente.
```
"Hello, World! I'm calling from the beta stage."
```
1. Puoi ripetere i passaggi precedenti per testare la fase **Prod**. Per **stageName** immetti **Prod**.
Si ottiene la risposta seguente.
```
"Hello, World! I'm calling from the prod stage."
```
# Riferimento alle variabili di fase API Gateway per REST APIs in API Gateway
È possibile usare le variabili di fase di API Gateway nei casi seguenti.
## Espressioni di mappatura dei parametri
Una variabile di fase può essere utilizzata in un'espressione di mappatura dei parametri per un parametro di intestazione di risposta o di richiesta del metodo API, senza alcuna sostituzione parziale. Nell'esempio che segue si fa riferimento alla variabile di fase senza il simbolo `$` e il simbolo `{...}` di chiusura.
+ `stageVariables.`
## Modelli di mappatura
Una variabile di fase può essere utilizzata ovunque in un modello di mappatura, come mostrato negli esempi seguenti.
+ `{ "name" : "$stageVariables."}`
+ `{ "name" : "${stageVariables.}"}`
## Integrazione HTTP URIs
Una variabile di fase può essere utilizzata come parte di un URL di integrazione HTTP, come mostrato negli esempi seguenti:
+ Un URI completo senza protocoll – `http://${stageVariables.}`
+ Un dominio completo – `http://${stageVariables.}/resource/operation`
+ Un sottodominio – `http://${stageVariables.}.example.com/resource/operation`
+ Un percorso – `http://example.com/${stageVariables.}/bar`
+ Una stringa di query – `http://example.com/foo?q=${stageVariables.}`
## AWS integration URIs
Una variabile di fase può essere utilizzata come parte dell'azione AWS URI o dei componenti del percorso, come illustrato nell'esempio seguente.
+ `arn:aws:apigateway:::${stageVariables.}`
## AWS integrazione URIs (funzioni Lambda)
Una variabile di fase può essere utilizzata al posto del nome o della versione/dell'alias di una funzione Lambda, come mostrato negli esempi seguenti.
+ `arn:aws:apigateway::lambda:path/2015-03-31/functions/arn:aws:lambda:::function:${stageVariables.}/invocations`
+ `arn:aws:apigateway::lambda:path/2015-03-31/functions/arn:aws:lambda:::function::${stageVariables.}/invocations`
**Nota**
Per utilizzare una variabile di fase per una funzione Lambda, la funzione deve essere nello stesso account dell'API. Le variabili di fase non supportano le funzioni Lambda tra più account.
## Bacino d’utenza di Amazon Cognito
Una variabile di fase può essere utilizzata al posto di un pool di utenti di Amazon Cognito per un sistema di autorizzazione `COGNITO_USER_POOLS`.
+ `arn:aws:cognito-idp:::userpool/${stageVariables.}`
## AWS credenziali di integrazione
Una variabile stage può essere utilizzata come parte dell'ARN delle AWS credenziali utente/ruolo, come illustrato nell'esempio seguente.
+ `arn:aws:iam:::${stageVariables.}`
# Configurare la distribuzione di una release Canary di API Gateway
Con [release Canary](https://martinfowler.com/bliki/CanaryRelease.html) si intende una strategia di sviluppo software in cui una nuova versione di un'API o di un altro software viene distribuita a scopo di test e contemporaneamente la versione di base rimane distribuita come release di produzione per le normali operazioni nella stessa fase. In questa documentazione la versione di base viene detta release di produzione. È possibile applicare una release Canary a qualsiasi versione non di produzione a scopo di test.
Nella distribuzione di una release Canary, il traffico API totale viene separato in modo casuale tra release di produzione e release Canary, in base a un rapporto preconfigurato. In genere, la release Canary riceve una piccola percentuale di traffico API e il resto viene assegnato alla release di produzione. Le caratteristiche API aggiornate sono visibili solo al traffico API nella release Canary. Puoi modificare la percentuale di traffico nella release Canary per ottimizzare le prestazioni o la copertura dei test.
Mantenendo limitato il traffico nella release Canary e la selezione casuale, la maggior parte degli utenti non riscontra conseguenze negative a causa di bug potenziali nella nuova versione e nessun utente riscontra conseguenze negative durature.
Se i parametri di test soddisfano i requisiti, puoi promuovere la release Canary a release di produzione e disabilitarne la distribuzione. Le nuove caratteristiche vengono così rese disponibili nella fase di produzione.
**Topics**
+ [Distribuzione di una release Canary in API Gateway](#api-gateway-canary-release-deployment-overview)
+ [Creazione di una distribuzione di una release Canary](create-canary-deployment.md)
+ [Aggiornamento di una release Canary](update-canary-deployment.md)
+ [Promozione di una release Canary](promote-canary-deployment.md)
+ [Disabilitazione di una release Canary](delete-canary-deployment.md)
## Distribuzione di una release Canary in API Gateway
In API Gateway la distribuzione di una release Canary utilizza la fase di distribuzione per il rilascio di produzione di una versione di base di un'API e collega alla fase una release Canary per le versioni dell'API nuove rispetto alla versione di base. La fase è associata alla distribuzione iniziale e la release Canary alle distribuzioni successive. All'inizio, sia la fase che la release Canary puntano alla stessa versione API. In questa sezione i termini fase e release di produzione vengono usati in modo intercambiabile, come pure i termini Canary e release Canary.
Per distribuire un'API con una release Canary devi creare una distribuzione della release Canary aggiungendo le [impostazioni Canary](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#canarySettings) alla [fase](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html) di una [distribuzione](https://docs.aws.amazon.com/apigateway/latest/api/API_Deployment.html) standard. Le impostazioni Canary descrivono la release Canary sottostante e la fase rappresenta la release di produzione dell'API nella distribuzione. Per aggiungere le impostazioni Canary, imposta `canarySettings` nella fase di distribuzione e specifica quanto segue:
+ Un ID di distribuzione, inizialmente identico all'ID della distribuzione della versione di base impostato nella fase.
+ Una [percentuale di traffico API](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#percentTraffic), con un valore compreso tra 0,0 e 100,0 inclusi, per la release Canary.
+ [Variabili di fase per la release Canary](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#stageVariableOverrides) che possono sovrascrivere le variabili di fase per la release di produzione.
+ L'[uso della cache dello stage](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#useStageCache) per le richieste Canary, se [useStageCache](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#useStageCache)è impostata e la memorizzazione nella cache delle API è abilitata sullo stage.
Dopo l'abilitazione di una release Canary, la fase di distribuzione non può essere associata a un'altra distribuzione di una release non Canary fino a quando la release Canary non viene disabilitata e le impostazioni Canary non vengono rimosse dalla fase.
Quando si abilita il logging delle esecuzioni API, per la release Canary vengono generati log e parametri per tutte le richieste Canary. Vengono segnalate a un gruppo di log CloudWatch Logs in fase di produzione e a un gruppo di log Logs specifico per Canary CloudWatch . Lo stesso vale per il logging degli accessi. I log specifici della release Canary sono utili per convalidare le nuove modifiche dell'API e stabilire se accettare le modifiche e promuovere la release Canary alla fase di produzione o se eliminare le modifiche e annullare la release Canary nella fase di produzione.
Il gruppo di log delle esecuzioni della fase di produzione è denominato `API-Gateway-Execution-Logs/{rest-api-id}/{stage-name}` e il gruppo di log delle esecuzioni della release Canary è denominato `API-Gateway-Execution-Logs/{rest-api-id}/{stage-name}/Canary`. Per il logging degli accessi, è necessario creare un nuovo gruppo di log o sceglierne uno esistente. Al nome del gruppo di log degli accessi della release Canary scelto viene aggiunto il suffisso `/Canary`.
Una versione canary può utilizzare lo stage cache, se abilitato, per memorizzare le risposte e utilizzare le voci memorizzate nella cache per restituire i risultati alle successive richieste Canary, entro un periodo preconfigurato (TTL). time-to-live
Nella distribuzione di una release Canary, la release di produzione e la release Canary dell'API possono essere associate alla stessa versione o a versioni diverse. Quando sono associate a versioni diverse, le risposte per le richieste di produzione e Canary vengono memorizzate nella cache separatamente e la cache di fase restituisce i risultati corrispondenti per le richieste di produzione e Canary. Quando la release di produzione e la release Canary sono associate alla stessa distribuzione, la cache di fase usa una singola chiave cache per entrambi i tipi di richieste e restituisce la stessa risposta per le stesse richieste dalla release di produzione e dalla release Canary.
# Creazione di una distribuzione di una release Canary
Puoi creare una distribuzione di una release Canary quando distribuisci l'API con [impostazioni Canary](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateDeployment.html#canarySettings) come input aggiuntivo all'operazione di [creazione della distribuzione](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateDeployment.html).
Puoi anche creare una distribuzione di una release Canary da una distribuzione non Canary esistente effettuando una richiesta [https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateStage.html](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateStage.html) per aggiungere le impostazioni Canary nella fase.
Quando crei una distribuzione di una release non Canary, puoi specificare un nome di fase non esistente. Se la fase specificata non esiste, API Gateway la crea. Non puoi tuttavia specificare un nome di fase non esistente quando crei una distribuzione di una release Canary. In questo caso si verificherà un errore e API Gateway non creerà una distribuzione della release Canary.
Puoi creare una distribuzione Canary Release in API Gateway utilizzando la console API Gateway AWS CLI, o un AWS SDK.
**Topics**
+ [Creare una distribuzione Canary utilizzando la console API Gateway](#create-canary-deployment-using-console)
+ [Crea una distribuzione Canary utilizzando il AWS CLI](#create-canary-deployment-using-cli)
## Creare una distribuzione Canary utilizzando la console API Gateway
Per usare la console API Gateway per creare una distribuzione di una release Canary, segui queste istruzioni:
**Per creare la distribuzione di una release Canary iniziale**
1. Accedere alla console API Gateway.
1. Crea una nuova REST API o scegline una esistente.
1. Nel riquadro di navigazione principale scegli **Risorse**, quindi seleziona **Distribuisci l'API**. Seguire le istruzioni visualizzate sullo schermo in **Deploy API (Distribuisci API)** per distribuire l'API in una nuova fase.
Al momento, l'API è stata distribuita in una fase della release di produzione. Configura quindi le impostazioni Canary nella fase e, se necessario, abilita il caching, imposta le variabili di fase o configura i log degli accessi o delle esecuzioni dell'API.
1. **Per abilitare la memorizzazione nella cache delle API o associare un ACL AWS WAF web allo stage, nella sezione **Dettagli dello stage**, scegli Modifica.** Per ulteriori informazioni, consulta [Impostazioni della cache per REST APIs in API Gateway](api-gateway-caching.md) o [Per associare un ACL AWS WAF Web a uno stadio API Gateway API utilizzando la console API Gateway](apigateway-control-access-aws-waf.md#apigateway-control-access-aws-waf-console).
1. Per configurare la registrazione degli accessi o delle esecuzioni, scegli **Modifica** nella sezione **Log e tracciamento** e segui le istruzioni visualizzate sullo schermo. Per ulteriori informazioni, consulta [Configurare la CloudWatch registrazione per REST APIs in API Gateway](set-up-logging.md).
1. Per impostare le variabili di fase, scegli la scheda **Variabili di fase** e segui le istruzioni visualizzate sullo schermo per aggiungere o modificare le variabili di fase. Per ulteriori informazioni, consulta [Utilizzo delle variabili di fase per una REST API in Gateway API](stage-variables.md).
1. Scegli la scheda **Canary**, quindi seleziona **Crea Canary**. Potrebbe essere necessario scegliere il pulsante freccia destra per visualizzare la scheda **Canary**.
1. In **Impostazioni di Canary**, inserisci in **Canary** la percentuale di richieste da deviare al Canary.
1. Se lo desideri, seleziona **Cache della fase** per attivare il caching per la release Canary. La cache non è disponibile per la release Canary fino a quando non viene abilitato il caching dell'API.
1. Per sovrascrivere le variabili di fase esistenti, inserisci in **Sostituzione canary** un nuovo valore per la variabile di fase.
Dopo l'inizializzazione della release Canary nella fase di distribuzione, puoi modificare l'API e testare le modifiche. Puoi ridistribuire l'API nella stessa fase in modo che sia la versione di base che quella aggiornata siano accessibili tramite la stessa fase. Di seguito viene descritto come fare.
**Per distribuire la versione API più recente in una release Canary**
1. Con ogni aggiornamento dell'API scegli **Distribuisci l'API.**
1. In **Distribuisci l'API** scegli la fase contenente un canary nell'elenco a discesa **Fase della distribuzione**.
1. (Facoltativo) Immetti una descrizione in **Descrizione distribuzione**.
1. Scegliere **Deploy (Distribuisci)** per inviare la versione API più recente alla release Canary.
1. Se lo desideri, riconfigura le impostazioni della fase, i log o le impostazioni Canary, come descritto in [Per creare la distribuzione di una release Canary iniziale](#to-create-canary-release-on-new-deployment).
La release Canary punta ora alla versione più recente, mentre la release di produzione continua a puntare alla versione iniziale dell'API. Per [https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#canarySettings](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#canarySettings) è ora presente un nuovo valore **deploymentId**, mentre la fase ha ancora il valore [https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#deploymentId](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#deploymentId) iniziale. In background la console chiama [https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateStage.html](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateStage.html).
## Crea una distribuzione Canary utilizzando il AWS CLI
**Per creare una distribuzione canary per una nuova fase**
1. Utilizza il seguente comando [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-deployment.html) per creare un’implementazione con due variabili di fase, ma senza un canary:
```
aws apigateway create-deployment \
--variables sv0=val0,sv1=val1 \
--rest-api-id abcd1234 \
--stage-name 'prod'
```
L'output sarà simile al seguente:
```
{
"id": "du4ot1",
"createdDate": 1511379050
}
```
1. Utilizza il seguente comando [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-deployment.html) per creare una distribuzione canary per la fase `prod`:
```
aws apigateway create-deployment \
--rest-api-id abcd1234 \
--canary-settings percentTraffic=10.5,stageVariableOverrides={sv1='val2',sv2='val3'},useStageCache=false \
--stage-name 'prod'
```
L'output sarà simile al seguente:
```
{
"id": "a6rox0",
"createdDate": 1511379433
}
```
Il valore `id` della distribuzione risultante identifica la versione di verifica dell'API per la release Canary. Di conseguenza, la fase associata è abilitata per la release Canary.
1. (Facoltativo) Utilizza il seguente comando [get-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/get-stage.html) per visualizzare la rappresentazione della fase:
```
aws apigateway get-stage --rest-api-id acbd1234 --stage-name prod
```
Di seguito è illustrata una rappresentazione dell'oggetto `Stage` come output del comando:
```
{
"stageName": "prod",
"variables": {
"sv0": "val0",
"sv1": "val1"
},
"cacheClusterEnabled": false,
"cacheClusterStatus": "NOT_AVAILABLE",
"deploymentId": "du4ot1",
"lastUpdatedDate": 1511379433,
"createdDate": 1511379050,
"canarySettings": {
"percentTraffic": 10.5,
"deploymentId": "a6rox0",
"useStageCache": false,
"stageVariableOverrides": {
"sv2": "val3",
"sv1": "val2"
}
},
"methodSettings": {}
}
```
In questo esempio la versione di base dell'API usa le variabili di fase `{"sv0":val0", "sv1":val1"}`, mentre la versione di test usa le variabili di fase `{"sv1":val2", "sv2":val3"}`. Sia la release di produzione che la release Canary usano la stessa variabile di fase `sv1`, ma con valori diversi, `val1` e `val2`, rispettivamente. La variabile di fase `sv0` viene usata unicamente nella release di produzione e la variabile di fase `sv2` viene usata unicamente nella release Canary.
È anche possibile creare una distribuzione di rilascio canary da un’implementazione standard esistente aggiornando la fase per abilitare un canary.
**Per creare una distribuzione di rilascio canary da un’implementazione esistente**
1. Utilizza il comando [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-deployment.html) per creare un’implementazione senza un canary:
```
aws apigateway create-deployment \
--variables sv0=val0,sv1=val1 \
--rest-api-id abcd1234 \
--stage-name 'beta'
```
1. Utilizza il comando [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) per aggiornare la fase e abilitare un canary:
```
aws apigateway update-stage \
--rest-api-id abcd1234 \
--stage-name 'beta' \
--patch-operations '[{
"op": "replace",
"value": "0.0",
"path": "/canarySettings/percentTraffic"
}, {
"op": "copy",
"from": "/canarySettings/stageVariableOverrides",
"path": "/variables"
}, {
"op": "copy",
"from": "/canarySettings/deploymentId",
"path": "/deploymentId"
}]'
```
L'output sarà simile al seguente:
```
{
"stageName": "beta",
"variables": {
"sv0": "val0",
"sv1": "val1"
},
"cacheClusterEnabled": false,
"cacheClusterStatus": "NOT_AVAILABLE",
"deploymentId": "cifeiw",
"lastUpdatedDate": 1511381930,
"createdDate": 1511380879,
"canarySettings": {
"percentTraffic": 10.5,
"deploymentId": "cifeiw",
"useStageCache": false,
"stageVariableOverrides": {
"sv2": "val3",
"sv1": "val2"
}
},
"methodSettings": {}
}
```
Poiché è stato abilitato un canary in una versione esistente dell’API, sia il rilascio di produzione (`Stage`) sia il rilascio canary (`canarySettings`) puntano alla stessa implementazione. Dopo aver modificato l'API e averla distribuita di nuovo in questa fase, la nuova versione sarà nella release Canary, mentre la versione di base rimane nella release di produzione. Ciò si manifesta nell'evoluzione della fase quando il valore `deploymentId` nella release Canary viene aggiornato al valore `id` della nuova distribuzione e il valore `deploymentId` nella release di produzione rimane invariato.
# Aggiornamento di una release Canary
Dopo la distribuzione di una release Canary, è possibile modificare la percentuale di traffico nella release Canary oppure abilitare o disabilitare l'uso di una cache di fase per ottimizzare le prestazioni di test. È anche possibile modificare le variabili di fase usate nella release Canary quando il contesto di esecuzione viene aggiornato. Per eseguire tali aggiornamenti, chiama l'operazione [https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateStage.html](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateStage.html) con i nuovi valori in [canarySettings](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#canarySettings).
Puoi aggiornare una versione Canary utilizzando la console API Gateway, il comando AWS CLI [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) o un SDK. AWS
**Topics**
+ [Aggiornare una release Canary utilizzando la console API Gateway](#update-canary-deployment-using-console)
+ [Aggiorna una versione Canary utilizzando il AWS CLI](#update-canary-deployment-using-cli)
## Aggiornare una release Canary utilizzando la console API Gateway
Per usare la console API Gateway per aggiornare le impostazioni Canary esistenti in una fase, esegui queste operazioni:
**Per aggiornare le impostazioni di Canary esistenti**
1. Accedi alla console Gateway API e scegli una REST API esistente.
1. Nel riquadro di navigazione principale scegli **Fasi**, quindi seleziona una fase esistente.
1. Seleziona la scheda **Canary**, quindi scegli **Modifica**. Potrebbe essere necessario scegliere il pulsante freccia destra per visualizzare la scheda **Canary**.
1. Aggiorna il campo **Distribuzione richiesta** aumentando o diminuendo il valore percentuale scegliendo un numero compreso tra 0,0 e 100,0 inclusi.
1. Seleziona o deseleziona la casella di controllo **Cache della fase**.
1. Aggiungi, rimuovi o modifica le **Variabili di fase di Canary**.
1. Scegli **Save** (Salva).
## Aggiorna una versione Canary utilizzando il AWS CLI
Per usare AWS CLI per aggiornare un canary, usa il [https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html)comando e modifica l'operazione di patch per ogni parametro del canary.
Il comando [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) seguente aggiorna se il canary utilizza la cache della fase:
```
aws apigateway update-stage \
--rest-api-id {rest-api-id} \
--stage-name '{stage-name}' \
--patch-operations op=replace,path=/canarySettings/useStageCache,value=true
```
Il comando [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) seguente aggiorna la percentuale di traffico del canary:
```
aws apigateway update-stage \
--rest-api-id {rest-api-id} \
--stage-name '{stage-name}' \
--patch-operations op=replace,path=/canarySettings/percentTraffic,value=25.0
```
Il comando [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) seguente aggiorna le variabili di fase. L’esempio mostra come creare una nuova variabile di fase denominata `newVar`, sostituire la variabile di fase `var2` e rimuovere la variabile di fase `var1`:
```
aws apigateway update-stage \
--rest-api-id {rest-api-id} \
--stage-name '{stage-name}' \
--patch-operations '[{
"op": "replace",
"path": "/canarySettings/stageVariableOverrides/newVar",
"value": "newVal"
}, {
"op": "replace",
"path": "/canarySettings/stageVariableOverrides/var2",
"value": "val4"
}, {
"op": "remove",
"path": "/canarySettings/stageVariableOverrides/var1"
}]'
```
È possibile aggiornare tutti gli elementi precedenti combinando le operazioni in un singolo valore `patch-operations`:
```
aws apigateway update-stage \
--rest-api-id {rest-api-id} \
--stage-name '{stage-name}' \
--patch-operations '[{
"op": "replace",
"path": "/canarySettings/percentTraffic",
"value": "20.0"
}, {
"op": "replace",
"path": "/canarySettings/useStageCache",
"value": "true"
}, {
"op": "remove",
"path": "/canarySettings/stageVariableOverrides/var1"
}, {
"op": "replace",
"path": "/canarySettings/stageVariableOverrides/newVar",
"value": "newVal"
}, {
"op": "replace",
"path": "/canarySettings/stageVariableOverrides/val2",
"value": "val4"
}]'
```
# Promozione di una release Canary
Quando si promuove una release canary, questa sostituisce le impostazioni correnti della fase. La promozione di una release Canary non comporta la disabilitazione della release Canary nella fase. Per disabilitare una release Canary, è necessario rimuovere le impostazioni Canary nella fase. Per promuovere una release canary, procedi come descritto di seguito.
+ Reimpostazione dell'[ID distribuzione](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#deploymentId) della fase con le impostazioni dell'[ID distribuzione](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#canarySettings) della release Canary. Questa operazione comporta l'aggiornamento dello snapshot API della fase con lo snapshot della release Canary e l'impostazione della versione di test come release di produzione.
+ Aggiornamento delle variabili di fase con le variabili di fase della release Canary, se presenti. Questa operazione comporta l'aggiornamento del contesto di esecuzione dell'API della fase con quello della release Canary. Senza questo aggiornamento, la nuova versione API può produrre risultati imprevisti se la versione di test usa variabili di fase diverse o valori diversi delle variabili di fase esistenti.
+ Impostazione della percentuale del traffico della release Canary su 0,0%.
**Topics**
+ [Promuovere una release Canary utilizzando la console API Gateway](#promote-canary-release-deployment-console)
+ [Promuovi una versione canaria usando il AWS CLI](#promote-canary-release-cli)
## Promuovere una release Canary utilizzando la console API Gateway
Per usare la console API Gateway per promuovere una distribuzione di una release Canary, esegui queste operazioni:
**Per promuovere l'implementazione di una release Canary**
1. Accedi alla console API Gateway e seleziona un'API esistente nel riquadro di navigazione principale.
1. Nel riquadro di navigazione principale scegli **Fasi**, quindi seleziona una fase esistente.
1. Scegli la scheda **Canary**.
1. Scegli **Promuovi Canary**.
1. Verifica le modifiche da apportare e scegli **Promuovi Canary**.
Dopo la promozione, la release di produzione fa riferimento alla stessa versione API (**deploymentId**) della release Canary. È possibile verificarlo utilizzando il. AWS CLI Per un esempio, consulta [Promuovi una versione canaria usando il AWS CLI](#promote-canary-release-cli).
## Promuovi una versione canaria usando il AWS CLI
Per promuovere una versione canary alla versione di produzione utilizzando AWS CLI i comandi, chiamate il `update-stage` comando per copiare il file canary-associato `deploymentId` a quello associato allo stage`deploymentId`, per reimpostare la percentuale di traffico canarino a zero (`0.0`) e per copiare qualsiasi variabile dello stage canary-bound su quelle corrispondenti.
Supponiamo di avere una distribuzione di rilascio di Canary, descritta da una fase simile alla seguente:
```
{
"_links": {
...
},
"accessLogSettings": {
...
},
"cacheClusterEnabled": false,
"cacheClusterStatus": "NOT_AVAILABLE",
"canarySettings": {
"deploymentId": "eh1sby",
"useStageCache": false,
"stageVariableOverrides": {
"sv2": "val3",
"sv1": "val2"
},
"percentTraffic": 10.5
},
"createdDate": "2017-11-20T04:42:19Z",
"deploymentId": "nfcn0x",
"lastUpdatedDate": "2017-11-22T00:54:28Z",
"methodSettings": {
...
},
"stageName": "prod",
"variables": {
"sv1": "val1"
}
}
```
Utilizza il seguente comando [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) per promuovere il canary:
```
aws apigateway update-stage \
--rest-api-id {rest-api-id} \
--stage-name '{stage-name}' \
--patch-operations '[{
"op": "replace",
"value": "0.0",
"path": "/canarySettings/percentTraffic"
}, {
"op": "copy",
"from": "/canarySettings/stageVariableOverrides",
"path": "/variables"
}, {
"op": "copy",
"from": "/canarySettings/deploymentId",
"path": "/deploymentId"
}]'
```
L'output sarà simile al seguente:
```
{
"_links": {
...
},
"accessLogSettings": {
...
},
"cacheClusterEnabled": false,
"cacheClusterStatus": "NOT_AVAILABLE",
"canarySettings": {
"deploymentId": "eh1sby",
"useStageCache": false,
"stageVariableOverrides": {
"sv2": "val3",
"sv1": "val2"
},
"percentTraffic": 0
},
"createdDate": "2017-11-20T04:42:19Z",
"deploymentId": "eh1sby",
"lastUpdatedDate": "2017-11-22T05:29:47Z",
"methodSettings": {
...
},
"stageName": "prod",
"variables": {
"sv2": "val3",
"sv1": "val2"
}
}
```
La promozione di una release canary nella fase non disabilita il canary e l'implementazione rimane un'implementazione di release canary. Per renderla una normale distribuzione di produzione, è necessario disabilitare le impostazioni Canary. Per ulteriori informazioni su come disabilitare una distribuzione di release Canary, consulta [Disabilitazione di una release Canary](delete-canary-deployment.md).
# Disabilitazione di una release Canary
Per disabilitare l'implementazione di una release Canary, è necessario impostare [https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#canarySettings](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#canarySettings) su null per rimuoverla dalla fase.
Puoi disabilitare una distribuzione Canary Release utilizzando la console API Gateway AWS CLI, o un AWS SDK.
**Topics**
+ [Disabilitazione di una release Canary utilizzando la console Gateway API](#delete-canary-release-console)
+ [Disattiva una versione canary usando il AWS CLI](#delete-canary-release-cli)
## Disabilitazione di una release Canary utilizzando la console Gateway API
Per usare la console Gateway API per disabilitare l'implementazione di una release Canary, procedi come segue:
**Per disabilitare l'implementazione di una release Canary**
1. Accedi alla console Gateway API e seleziona un'API esistente nel riquadro di navigazione principale.
1. Nel riquadro di navigazione principale scegli **Fasi**, quindi seleziona una fase esistente.
1. Scegli la scheda **Canary**.
1. Scegli **Elimina**.
1. Confermare che si desidera eliminare la release Canary scegliendo **Delete (Elimina)**.
Di conseguenza, la proprietà [https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#canarySettings](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#canarySettings) diventa `null` e viene rimossa dalla [fase](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html) di distribuzione. Puoi verificarlo utilizzando. AWS CLI Per un esempio, consulta [Disattiva una versione canary usando il AWS CLI](#delete-canary-release-cli).
## Disattiva una versione canary usando il AWS CLI
Il comando [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) seguente disattiva la distribuzione di rilascio canary:
```
aws apigateway update-stage \
--rest-api-id abcd1234 \
--stage-name canary \
--patch-operations '[{"op":"remove", "path":"/canarySettings"}]'
```
L'output sarà simile al seguente:
```
{
"stageName": "prod",
"accessLogSettings": {
...
},
"cacheClusterEnabled": false,
"cacheClusterStatus": "NOT_AVAILABLE",
"deploymentId": "nfcn0x",
"lastUpdatedDate": 1511309280,
"createdDate": 1511152939,
"methodSettings": {
...
}
}
```
Come illustrato nell’output, la proprietà [canarySettings](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#canarySettings) non è più presente nella [fase](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html) della distribuzione di rilascio canary disabilitata.
# Aggiornamenti a REST APIs che richiedono una ridistribuzione
Gestire un'API significa visualizzare, aggiornare ed eliminare le configurazioni API esistenti. Puoi gestire un'API utilizzando la console API Gateway, AWS CLI CloudFormation, un SDK o l'API REST API Gateway. L'aggiornamento di un'API implica la modifica di determinate proprietà delle risorse o delle impostazioni di configurazione dell'API. Gli aggiornamenti delle risorse richiedono una nuova implementazione dell'API, operazione non necessaria per gli aggiornamenti di configurazione.
La tabella seguente descrive le risorse API che richiedono una nuova implementazione dell'API quando vengono aggiornate.
| Risorsa | Note |
| --- | --- |
| [ApiKey](https://docs.aws.amazon.com/apigateway/latest/api/API_ApiKey.html) | Per le proprietà applicabili e le operazioni supportate, consulta [apikey:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateApiKey.html). L'aggiornamento richiede la ridistribuzione dell'API. |
| [Authorizer](https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html) | Per le proprietà applicabili e le operazioni supportate, consulta [authorizer:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateAuthorizer.html). L'aggiornamento richiede la ridistribuzione dell'API. |
| [disableExecuteApiEndpoint](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateRestApi.html#apigw-UpdateRestApi-response-disableExecuteApiEndpoint) | L’aggiornamento richiede la modifica di una fase per l’API, ad esempio una nuova implementazione dell’API in una fase. |
| [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) | Per le proprietà applicabili e le operazioni supportate, consulta [documentationpart:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateDocumentationPart.html). L'aggiornamento richiede la ridistribuzione dell'API. |
| [DocumentationVersion](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html) | Per le proprietà applicabili e le operazioni supportate, consulta [documentationversion:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateDocumentationVersion.html). L'aggiornamento richiede la ridistribuzione dell'API. |
| [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html) | Per le proprietà applicabili e le operazioni supportate, consulta [gatewayresponse:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateGatewayResponse.html#remarks). L'aggiornamento richiede la ridistribuzione dell'API. |
| [Integration](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) | Per le proprietà applicabili e le operazioni supportate, consulta [integration:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateIntegration.html). L'aggiornamento richiede la ridistribuzione dell'API. |
| [IntegrationResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html) | Per le proprietà applicabili e le operazioni supportate, consulta [integrationresponse:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateIntegrationResponse.html). L'aggiornamento richiede la ridistribuzione dell'API. |
| [Metodo](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html) | Per le proprietà applicabili e le operazioni supportate, consulta [method:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateMethod.html). L'aggiornamento richiede la ridistribuzione dell'API. |
| [MethodResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html) | Per le proprietà applicabili e le operazioni supportate, consulta [methodresponse:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateMethodResponse.html). L'aggiornamento richiede la ridistribuzione dell'API. |
| [Modello](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html) | Per le proprietà applicabili e le operazioni supportate, consulta [model:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateModel.html). L'aggiornamento richiede la ridistribuzione dell'API. |
| [RequestValidator](https://docs.aws.amazon.com/apigateway/latest/api/API_RequestValidator.html) | Per le proprietà applicabili e le operazioni supportate, consulta [requestvalidator:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateRequestValidator.html). L'aggiornamento richiede la ridistribuzione dell'API. |
| [Risorsa](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) | Per le proprietà applicabili e le operazioni supportate, consulta [resource:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateResource.html). L'aggiornamento richiede la ridistribuzione dell'API. |
| [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateRestApi.html) | Per le proprietà applicabili e le operazioni supportate, consulta [restapi:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateRestApi.html). L'aggiornamento richiede la ridistribuzione dell'API. È inclusa la modifica delle policy di risorse. |
| [VpcLink](https://docs.aws.amazon.com/apigateway/latest/api/API_VpcLink.html) | Per le proprietà applicabili e le operazioni supportate, consulta [vpclink:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateVpcLink.html). L'aggiornamento richiede la ridistribuzione dell'API. |
La tabella seguente descrive le configurazioni API che non richiedono una nuova implementazione dell'API quando vengono aggiornate.
| Configurazione | Note |
| --- | --- |
| [Account](https://docs.aws.amazon.com/apigateway/latest/api/API_GetAccount.html) | Per le proprietà applicabili e le operazioni supportate, consulta [account:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateAccount.html). L'aggiornamento non richiede la ridistribuzione dell'API. |
| [Distribuzione](https://docs.aws.amazon.com/apigateway/latest/api/API_Deployment.html) | Per le proprietà applicabili e le operazioni supportate, consulta [deployment:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateDeployment.html). |
| [DomainName](https://docs.aws.amazon.com/apigateway/latest/api/API_DomainName.html) | Per le proprietà applicabili e le operazioni supportate, consulta [domainname:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateDomainName.html). L'aggiornamento non richiede la ridistribuzione dell'API. |
| [BasePathMapping](https://docs.aws.amazon.com/apigateway/latest/api/API_BasePathMapping.html) | Per le proprietà applicabili e le operazioni supportate, consulta [basepathmapping:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateBasePathMapping.html). L'aggiornamento non richiede la ridistribuzione dell'API. |
| [Tipo di indirizzo IP](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateRestApi.html) | L'aggiornamento non richiede la ridistribuzione dell'API. |
| [Fase](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html) | Per le proprietà applicabili e le operazioni supportate, consulta [stage:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateStage.html). L'aggiornamento non richiede la ridistribuzione dell'API. |
| [Utilizzo](https://docs.aws.amazon.com/apigateway/latest/api/API_GetUsage.html) | Per le proprietà applicabili e le operazioni supportate, consulta [usage:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateUsage.html). L'aggiornamento non richiede la ridistribuzione dell'API. |
| [UsagePlan](https://docs.aws.amazon.com/apigateway/latest/api/API_UsagePlan.html) | Per le proprietà applicabili e le operazioni supportate, consulta [usageplan:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateUsagePlan.html). L'aggiornamento non richiede la ridistribuzione dell'API. |
# 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.