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à.
# 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
```
------