Configurazione di un nome di dominio personalizzato ottimizzato per l'edge in Gateway API - Amazon API Gateway
ConsiderazioniCreazione di un nome di dominio personalizzato ottimizzato per l'edgeConfigurazione della mappatura del percorso di base di un'API con un nome di dominio personalizzato come nome hostCreazione di un record DNS per il nome di dominio personalizzato ottimizzato per l'edgeLogging della creazione di nomi di dominio personalizzati in CloudTrailRotazione di un certificato importato in ACMChiamata dell’API con nomi di dominio personalizzati quando si utilizza una mappatura percorso di base

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, Gateway API configura una distribuzione di CloudFront e un record DNS per mappare il nome di dominio dell'API al nome di dominio della distribuzione di CloudFront. Le richieste per l'API vengono quindi instradate ad API Gateway attraverso la distribuzione CloudFront mappata. Questa mappatura è per le richieste API associate al nome di dominio personalizzato da indirizzare ad API Gateway attraverso la distribuzione di 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 l'edge o per aggiornare il relativo certificato, è necessario disporre dell'autorizzazione per aggiornare le distribuzioni CloudFront.

    Per aggiornare le distribuzioni CloudFront, sono necessarie le seguenti autorizzazioni:

    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 distribuzione di CloudFront creata da API Gateway è di proprietà di un account specifico per la regione affiliato ad API Gateway. Quando si monitorano le operazioni per creare e aggiornare tale distribuzione di CloudFront in CloudTrail, è necessario utilizzare questo ID account di Gateway API. Per ulteriori informazioni, consulta Logging della creazione di nomi di dominio personalizzati in CloudTrail.

  • API Gateway supporta i nomi di dominio personalizzati ottimizzati per l'edge tramite SNI (Server Name Indication) nella distribuzione di CloudFront. Per ulteriori informazioni sull'uso di nomi di dominio personalizzati in una distribuzione CloudFront, tra cui il formato del certificato richiesto e la lunghezza massima di una chiave del certificato, consulta Using Alternate Domain Names and HTTPS nella Guida per gli sviluppatori di Amazon CloudFront.

  • 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 l'edge, devi creare un record DNS per mappare il nome di dominio personalizzato al nome della distribuzione di 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.

AWS Management Console

  1. Accedere alla console API Gateway all'indirizzo https://console.aws.amazon.com/apigateway.

  2. Scegliere Custom Domain Names (Nomi di dominio personalizzati) nel riquadro di navigazione principale.

  3. Scegli Aggiungi nome di dominio.

  4. In Domain name (Nome di dominio), immettere un nome di dominio.

  5. Per Modalità di routing, scegliere API_MAPPING_ONLY.

  6. Per Tipo di endpoint API, scegli Ottimizzato per l'edge.

  7. Scegliere una versione di TLS minima.

  8. Scegliere un certificato ACM.

  9. Scegli Aggiungi nome di dominio.

REST API

  1. Chiamare domainname:create, specificando il nome di dominio personalizzato e l'ARN di un certificato archiviato in AWS Certificate Manager.

    Se la chiamata API ha esito positivo, viene restituita una risposta 201 Created il cui payload contiene l'ARN del certificato e il nome della distribuzione di CloudFront associata.

  2. Prendi nota del nome di dominio della distribuzione CloudFront presente nel risultato. 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.

Affinché un nome di dominio personalizzato ottimizzato per l'edge sia pronto sono necessari circa 40 minuti, ma la console mostra immediatamente il nome di dominio della distribuzione CloudFront associata, sotto forma di distribution-id.cloudfront.net, insieme all'ARN del certificato. Nel frattempo, è possibile creare una mappatura 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 della distribuzione di CloudFront associata.

Configurazione della mappatura del percorso di base di un'API con un nome di dominio personalizzato come nome host

Poiché la regola di routing è stata impostata su API_MAPPING_ONLY, è possibile usare la mappatura percorso di base per utilizzare un singolo nome di dominio personalizzato come nome host di più API. 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 Utilizzo delle mappature API per connettere le fasi API a un nome di dominio personalizzato per REST API.

La procedura seguente consente di impostare le mappature dell'API per mappare percorsi dal nome di dominio personalizzato alle fasi API.

AWS Management Console

  1. Accedere alla console API Gateway all'indirizzo https://console.aws.amazon.com/apigateway.

  2. Seleziona Custom Domain Names (Nomi di dominio personalizzati) nel riquadro di navigazione principale della console API Gateway.

  3. Scegliere un nome di dominio personalizzato.

  4. Scegliere Configure API mappings (Configura mappature API).

  5. Scegliere Add new mapping (Aggiungi nuova mappatura).

  6. Specificare API, Stage (Fase) e Path (Percorso) (facoltativo) per la mappatura.

  7. Selezionare Salva.

REST API

Richiamare basepathmapping:create 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.

Per una maggiore flessibilità su come instradare il traffico alle API, è 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 Invio del traffico alle API tramite il nome di dominio personalizzato in Gateway API.

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.

È consigliabile utilizzare Route 53 per creare un alias di record A per il nome di dominio personalizzato e specificare il nome di dominio della distribuzione di CloudFront come target 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 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 nella Guida per gli sviluppatori di Amazon Route 53.

Logging della creazione di nomi di dominio personalizzati in CloudTrail

Quando CloudTrail è abilitato per il logging delle chiamate di API Gateway dall'account, API Gateway registra gli aggiornamenti della distribuzione di CloudFront associata quando un nome di dominio personalizzato viene creato o aggiornato per un'API. Questi log sono disponibili in us-east-1. Poiché queste distribuzioni di CloudFront sono di proprietà di API Gateway, ognuna di queste distribuzioni di CloudFront segnalate viene identificata da uno dei seguenti ID account di API Gateway specifici della regione, anziché dall'ID account 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 i certificati emessi da ACM per i nomi di dominio personalizzati. CloudFront gestisce l'operazione 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. Successivamente, puoi lasciare che ACM e CloudFront gestiscano automaticamente la rotazione dei certificati. Per creare o importare un nuovo certificato ACM, segui la procedura riportata in Creazione o importazione di un certificato SSL/TLS in ACM.

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.

AWS Management Console

  1. Richiedi o importa un certificato in ACM.

  2. Accedere alla console API Gateway all'indirizzo https://console.aws.amazon.com/apigateway.

  3. Seleziona Custom Domain Names (Nomi di dominio personalizzati) nel riquadro di navigazione principale della console API Gateway.

  4. Scegli un nome di dominio personalizzato ottimizzato per l'edge.

  5. Per Configurazione endpoint scegli Modifica.

  6. Seleziona un certificato nell'elenco a discesa Certificato ACM.

  7. Scegli Salva per iniziare la rotazione del certificato per il nome di dominio personalizzato.

REST API

Richiama l'operazione domainname:update indicando l'ARN del nuovo certificato ACM per il nome di dominio specificato.

AWS CLI

Il comando update-domain-name seguente 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'"

Il comando update-domain-name seguente 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 mettono a confronto un set di URL predefiniti con i corrispondenti URL personalizzati di due API (udxjef e qf3duz) in una regione specificata (us-east-1) e per un 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/petstore
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/bookstore
qf3duz tst https://qf3duz.execute-api.us-east-1.amazonaws.com/tst /bookstand https://api.example.com/bookstand

Per una maggiore flessibilità su come instradare il traffico alle API, è possibile creare una regola di routing. Per ulteriori informazioni, consulta Invio del traffico alle API tramite il nome di dominio personalizzato in Gateway API.

API Gateway supporta i nomi di dominio personalizzati per un'API usando SNI (Server Name Indication, Indicazione nome server). 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 distribuzione di CloudFront. Per ulteriori informazioni sulle modalità di utilizzo dei nomi di dominio personalizzati in CloudFront, consulta SSL personalizzato per Amazon CloudFront.