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à. # Tutorial: crea e richiama un nome di dominio personalizzato per uso privato APIs In questo tutorial creerai un nome di dominio personalizzato privato da invocare in un VPC nel tuo account. A questo scopo, sei il provider e il consumatore di API. Per completare questo tutorial devi disporre di un'API privata e di un endpoint VPC. Se disponi di un endpoint VPC che utilizzi per accedere a un nome di dominio personalizzato pubblico, non utilizzarlo per questo tutorial o per creare associazioni di accesso a nomi di dominio. ## Passaggio 1: creare un nome di dominio personalizzato privato Puoi creare un nome di dominio personalizzato privato specificando il nome di dominio, il certificato ACM e la policy per il servizio `execute-api` per controllare quali endpoint VPC possono invocarlo. ------ #### [ Console di gestione AWS ] **Per creare un nome di dominio personalizzato privato** 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 **Aggiungi nome di dominio**. 1. In **Domain name (Nome di dominio)**, immettere un nome di dominio. Il certificato ACM deve coprire questo nome di dominio, ma non è necessario che il nome di dominio sia univoco. 1. Seleziona **Privato**. 1. Per **Modalità di routing**, scegli **Solo mappature API.** 1. Per **Certificato ACM**, seleziona un certificato. 1. Scegli **Aggiungi nome di dominio**. Gateway API effettua il provisioning di un nome di dominio con una policy `deny` per tutte le risorse. Questa è la policy delle risorse per il servizio `execute-api`. Devi aggiornare questa policy delle risorse per concedere l'accesso agli endpoint VPC per invocare il tuo nome di dominio personalizzato privato. **Per aggiornare la policy delle risorse** 1. Scegli la scheda **Policy delle risorse**, quindi scegli **Modifica policy delle risorse**. 1. Inserisci la policy delle risorse seguente nell'editor di codice. Sostituisci l'endpoint VPC *vpce-abcd1234efg* con il tuo ID endpoint VPC. **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": "*", "Action": "execute-api:Invoke", "Resource": [ "execute-api:/*" ] }, { "Effect": "Deny", "Principal": "*", "Action": "execute-api:Invoke", "Resource": [ "execute-api:/*" ], "Condition" : { "StringNotEquals": { "aws:SourceVpce": "vpce-abcd1234" } } } ] } ``` 1. Scegli **Save changes** (Salva modifiche). ------ #### [ AWS CLI ] Quando crei un nome di dominio privato personalizzato utilizzando il AWS CLI, fornisci una politica di risorse affinché il `execute-api` servizio conceda l'accesso agli endpoint VPC per richiamare il tuo nome di dominio personalizzato privato, utilizzando il parametro. `--policy file://policy.json` È possibile modificare questa policy in un secondo momento. In questo esempio si collega la seguente policy di risorse come `policy` caricando i parametri da un file. Copia e salva questo file come `policy.json`. Questa politica consente solo il traffico in entrata verso un nome di dominio personalizzato privato dall'endpoint * `vpce-abcd1234efg`* VPC: **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": "*", "Action": "execute-api:Invoke", "Resource": [ "execute-api:/*" ] }, { "Effect": "Deny", "Principal": "*", "Action": "execute-api:Invoke", "Resource": [ "execute-api:/*" ], "Condition" : { "StringNotEquals": { "aws:SourceVpce": "vpce-abcd1234" } } } ] } ``` Il [create-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-domain-name.html)comando seguente crea un nome di dominio privato personalizzato: ``` aws apigateway create-domain-name \ --domain-name 'private.example.com' \ --certificate-arn 'arn:aws:acm:us-west-2:111122223333:certificate/a1b2c3d4-5678-90ab-cdef' \ --security-policy 'TLS_1_2' \ --endpoint-configuration '{"types":["PRIVATE"]}' \ --policy file://policy.json ``` 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" ] }, "domainNameStatus": "AVAILABLE", "securityPolicy": "TLS_1_2", "routingMode" : "API_MAPPING_ONLY", "policy": "..." } ``` ------ ## Passaggio 2: creare una mappatura del percorso di base per mappare l'API privata al nome di dominio personalizzato privato Dopo aver creato il nome di dominio personalizzato privato, mappa un'API privata a tale nome. Con una mappatura del percorso di base, un'API è accessibile tramite la combinazione di nome di dominio personalizzato privato e percorso di base associato. Si consiglia di utilizzare un singolo nome di dominio privato personalizzato come nome host di più nomi privati APIs. Tutti i provider di API devono creare una mappatura del percorso di base, anche se non hai intenzione di invocare la tua API. Inoltre, devi concedere l'accesso agli endpoint VPC per richiamare qualsiasi privato APIs mappato al tuo nome di dominio privato personalizzato. ------ #### [ Console di gestione AWS ] **Per creare una mappatura del percorso di base** 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 privato. 1. Nella scheda **Mappature API** scegli **Configura mappature**. 1. Scegliere **Add new mapping (Aggiungi nuova mappatura)**. 1. Immettere un'**API**, uno **Stage (Fase)**e, facoltativamente, un **Path (Percorso)**. 1. Selezionare **Salva**. ------ #### [ AWS CLI ] Il [create-base-path-mapping](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-base-path-mapping.html)comando seguente crea una mappatura tra un'API privata e un nome di dominio personalizzato privato: ``` aws apigateway create-base-path-mapping \ --domain-name-id abcd1234 \ --domain-name 'private.example.com' \ --rest-api-id a1b2c3 \ --stage prod \ --base-path v1 ``` L'output sarà simile al seguente. ``` { "basePath": "v1", "restApiId": "a1b2c3", "stage": "prod" } ``` ------ Per una maggiore flessibilità nel modo in cui indirizzate il traffico verso il vostro APIs, potete 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). **Nota** Se vuoi che altri Account AWS invochino il tuo nome di dominio privato personalizzato, dopo aver completato questo tutorial, segui i passaggi indicati. [Provider di API: condividi il tuo nome di dominio privato personalizzato utilizzando AWS RAM](apigateway-private-custom-domains-provider-share.md) ## Passaggio 3: creare un'associazione di accesso al nome di dominio tra il nome di dominio personalizzato e un endpoint VPC A questo punto, creerai un'associazione di accesso al nome di dominio tra il nome di dominio personalizzato privato e l'endpoint VPC. L'endpoint VPC utilizza l'associazione di accesso al nome di dominio per invocare il nome di dominio personalizzato privato mentre è isolato dalla rete Internet pubblica. ------ #### [ Console di gestione AWS ] **Per creare un'associazione di accesso al nome di dominio** 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 privato. 1. Nella scheda **Condivisione delle risorse**, per le **Associazioni di accesso ai nomi di dominio**, scegli **Crea associazione di accesso al nome di dominio**. 1. In **ARN del nome di dominio** digita il tuo nome di dominio. 1. In **ID endpoint VPC** seleziona l'ID endpoint VPC a cui hai fornito l'accesso nel passaggio 1. 1. Scegli **Associazione di accesso al nome di dominio**. Puoi anche creare l'associazione di accesso al nome di dominio utilizzando la pagina **Associazioni di accesso ai nomi di dominio** della console. ------ #### [ AWS CLI ] Il seguente comando `create-domain-name-access-association` crea un'associazione di accesso al nome di dominio tra il nome di dominio personalizzato privato e l'endpoint VPC. ``` aws apigateway create-domain-name-access-association \ --domain-name-arn arn:aws:apigateway:us-west-2:111122223333:/domainnames/private.example.com+abcd1234 \ --access-association-source vpce-abcd1234efg \ --access-association-source-type VPCE \ --region us-west-2 ``` L'output sarà simile al seguente. ``` { "domainNameAccessAssociationARN": "arn:aws:apigateway:us-west-2:111122223333:/domainnameaccessassociations/domainname/private.example.com+abcd1234/vpcesource/vpce-abcd1234efg", "accessAssociationSource": "vpce-abcd1234efg", "accessAssociationSourceType": "VPCE", "domainNameARN" : "arn:aws:apigateway:us-west-2:111122223333:/domainnames/private.example.com+abcd1234" } ``` ------ Affinché l'associazione di accesso al nome di dominio sia pronta sono necessari circa 15 minuti. Durante l'attesa, puoi eseguire i passaggi seguenti. ## Passaggio 4: creare una zona ospitata Route 53 Dopo aver aggiornato la policy delle risorse e associato il nome di dominio personalizzato privato all'endpoint VPC, crea una zona ospitata privata in Route 53 per risolvere il nome di dominio personalizzato. Una zona ospitata è un contenitore che contiene informazioni su come si desidera indirizzare il traffico per un dominio all'interno di uno o più domini VPCs senza esporre le proprie risorse a Internet. Per ulteriori informazioni, consulta [Utilizzo delle zone ospitate private](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/hosted-zones-private.html). ------ #### [ Console di gestione AWS ] Per utilizzare la Console di gestione AWS, consulta [Creazione di una zona ospitata privata](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/hosted-zone-private-creating.html) nella *Amazon Route 53 Developer Guide*. Per **Nome**, usa il tuo nome di dominio personalizzato privato. Per **ID VPC**, usa il VPC contenente l'endpoint VPC utilizzato nei passaggi precedenti. ------ #### [ AWS CLI ] Il [create-hosted-zone](https://docs.aws.amazon.com/cli/latest/reference/route53/create-hosted-zone.html)comando seguente crea una zona ospitata privata: ``` aws route53 create-hosted-zone --name private.example.com \ --caller-reference 2014-04-01-18:47 \ --hosted-zone-config Comment="command-line version",PrivateZone=true \ --vpc VPCRegion=us-west-2,VPCId=vpc-abcd1234 ``` L'output contiene l'ID della zona ospitata. L'ID della zona ospitata viene utilizzato nei passaggi seguenti. ------ ## Passaggio 5: creare un record DNS di Route 53 Dopo aver creato la zona ospitata, devi creare un record per risolvere il tuo nome di dominio personalizzato privato. Userai l'ID della zona ospitata che hai creato nel passaggio precedente. In questo esempio viene creato un tipo di record A. Se lo utilizzi IPv6 per il tuo endpoint VPC, crea un tipo di record AAAA. Se utilizzi dualstack per il tuo endpoint VPC, crea un tipo di record sia AAAA che A. ------ #### [ Console di gestione AWS ] Per utilizzare il Console di gestione AWS, consulta [Routing del traffico verso un'API Amazon API Gateway utilizzando il tuo nome di dominio](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-api-gateway.html). Usa **Creazione rapida** e attiva **Alias**. Per l'endpoint, utilizza il nome DNS dell'endpoint VPC. ------ #### [ AWS CLI ] Per configurare i record DNS in modo da mappare il nome di dominio personalizzato privato al relativo nome host dell'ID della zona ospitata, devi creare un file JSON contenente la configurazione per configurare un record DNS per il nome di dominio privato. Il seguente `setup-dns-record.json` mostra come creare un record `A` DNS per mappare un nome di dominio personalizzato privato al relativo nome host privato. Fornisci il `DNSName` del tuo ID DNS VPC e l'ID della zona ospitata che hai creato nel passaggio precedente. ``` { "Changes": [ { "Action": "UPSERT", "ResourceRecordSet": { "Name": "private.example.com", "Type": "A", "AliasTarget": { "DNSName": "vpce-abcd1234.execute-api.us-west-2.vpce.amazonaws.com", "HostedZoneId": "Z2OJLYMUO9EFXC", "EvaluateTargetHealth": false } } } ] } ``` Il [change-resource-record-sets](https://docs.aws.amazon.com/cli/latest/reference/route53/change-resource-record-sets.html)comando seguente crea un record DNS per il tuo nome di dominio privato personalizzato: ``` aws route53 change-resource-record-sets \ --hosted-zone-id ZABCDEFG1234 \ --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. ------ Se non intendi invocare il tuo nome di dominio personalizzato privato, dopo aver verificato che il nome di dominio personalizzato privato funzioni, puoi eliminare queste risorse. ## Passaggio 6: invocare il nome di dominio personalizzato privato Ora puoi invocare il tuo nome di dominio personalizzato privato nel tuo Account AWS. Nel tuo VPC, usa il seguente comando curl per accedere al tuo nome di dominio personalizzato privato. ``` curl https://private.example.com/v1 ``` Per ulteriori informazioni su altri modi per invocare la tua API privata, consulta [Invocazione di un'API privata utilizzando un nome di dominio personalizzato](apigateway-private-api-test-invoke-url.md#apigateway-private-custom-domains-provider-invoke). ## Passaggio 7: eseguire l'eliminazione Per evitare costi inutili, elimina l'associazione tra l'endpoint VPC e il nome di dominio personalizzato privato, quindi elimina il nome di dominio personalizzato privato. ------ #### [ Console di gestione AWS ] **Per eliminare l'associazione di accesso al nome di dominio** 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 **Associazioni di accesso ai nomi di dominio**. 1. Seleziona l'associazione di accesso al nome di dominio, quindi scegli **Elimina**. 1. Conferma la tua scelta, quindi scegli **Elimina**. Dopo aver eliminato l'associazione di accesso al nome di dominio, puoi eliminare il tuo nome di dominio personalizzato privato. **Per eliminare il nome di dominio personalizzato privato** 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 il tuo nome di dominio personalizzato privato. 1. Scegli **Elimina**. 1. Conferma la tua scelta, quindi scegli **Elimina**. Se necessario, puoi anche eliminare il tuo endpoint VPC. Per ulteriori informazioni, consulta [Eliminazione di un endpoint dell'interfaccia](https://docs.aws.amazon.com/vpc/latest/privatelink/delete-interface-endpoint.html). ------ #### [ AWS CLI ] **Per eliminare** 1. Il seguente comando `delete-access-association` elimina l'associazione di accesso al nome di dominio: ``` aws apigateway delete-domain-name-access-association \ --domain-name-access-association-arn 'arn:aws:apigateway:us-west-2:111122223333:/domainnameaccessassociations/domainname/private.example.com+abcd1234/vpcesource/vpce-abcd1234efg' \ --region us-west-2 ``` 1. Il seguente comando `delete-domain-name` elimina il nome di dominio personalizzato privato. Questo comando rimuove anche tutte le mappature dei percorsi di base. ``` aws apigateway delete-domain-name \ --domain-name test.private.com \ --domain-name-id abcd1234 ``` Se necessario, puoi anche eliminare il tuo endpoint VPC. Per ulteriori informazioni, consulta [Eliminazione di un endpoint dell'interfaccia](https://docs.aws.amazon.com/vpc/latest/privatelink/delete-interface-endpoint.html). ------ ## Best practice Di seguito sono riportate le best practice consigliate per la creazione di un nome di dominio personalizzato privato: + Utilizza la mappatura del percorso di base o le regole di routing per inviare il traffico da un nome di dominio privato personalizzato a più nomi privati. APIs + Quando un endpoint VPC non ha più bisogno di accedere a un nome di dominio personalizzato privato, elimina l'associazione. Inoltre, rimuovi l'endpoint VPC da `execute-api` per il servizio `policy` per il dominio personalizzato privato. + Configura almeno due zone di disponibilità per endpoint VPC. + Disabilita l'endpoint predefinito. È consigliabile disabilitare l'endpoint predefinito per consentire ai consumatori dell'API di chiamare l'API solo dal nome di dominio personalizzato. Per ulteriori informazioni, consulta [Disabilita l'endpoint predefinito per REST APIs](rest-api-disable-default-endpoint.md). + È consigliabile effettuare il provisioning di una zona ospitata privata di Route 53 e di un record di tipo A durante la configurazione del nome di dominio personalizzato privato. Se non hai intenzione di invocare il tuo nome di dominio personalizzato privato, puoi eliminare queste risorse in un secondo momento.