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à. # Piani di utilizzo e chiavi API per REST APIs in API Gateway Dopo aver creato, testato e distribuito i tuoi APIs, puoi utilizzare i piani di utilizzo di API Gateway per renderli disponibili come offerte di prodotti per i tuoi clienti. Puoi configurare piani di utilizzo e chiavi API per consentire ai clienti di accedere a determinati APIs piani di utilizzo e iniziare a limitare le richieste a quelle APIs basate su limiti e quote definiti. Questi possono essere impostati a livello API o metodo API. ## Cosa sono i piani di utilizzo e le chiavi API? Un *piano di utilizzo* consente di specificare chi può accedere a una o più fasi e metodi API distribuiti, inclusa la frequenza di richiesta di destinazione per iniziare a limitare le richieste. Il piano utilizza chiavi API per identificare client API e chi può accedere akke fasi API associate a ciascuna chiave. Le *chiavi API* sono valori stringa alfanumerici che vengono distribuiti ai clienti degli sviluppatori di applicazioni per concedere l'accesso all'API. Puoi utilizzare le chiavi API insieme agli [autorizzatori Lambda](apigateway-use-lambda-authorizer.md), ai [ruoli IAM](permissions.md) o [Amazon Cognito per controllare l'accesso](apigateway-integrate-with-cognito.md) al tuo. APIs API Gateway può generare chiavi API per tuo conto o puoi importarle da un [file CSV](api-key-file-format.md). Puoi generare una chiave API in API Gateway o importarla in API Gateway da un'origine esterna. Per ulteriori informazioni, consulta [Configura le chiavi API per REST APIs in API Gateway](api-gateway-setup-api-keys.md). Una chiave API ha un nome e un valore. I termini "chiave API" e "valore di chiave API" vengono spesso usati in modo intercambiabile. Il nome non può superare 1024 caratteri. Il valore è una stringa alfanumerica tra 20 e 128 caratteri, ad esempio, `apikey1234abcdefghij0123456789`. **Importante** I valori di chiave API devono essere univoci. Se provi a creare due chiavi API con nomi diversi e lo stesso valore, queste vengono considerate da API Gateway la stessa chiave API. Una chiave API può essere associata a più piani di utilizzo. Un piano di utilizzo può essere associato a più fasi. Tuttavia, una determinata chiave API può essere associata a un solo piano di utilizzo per ogni fase dell'API. Un *limite di throttling* imposta il punto di destinazione in cui dovrebbe iniziare la limitazione delle richieste. Può essere impostato a livello API o metodo API. Un *limite di quota* è il numero massimo di richieste con una determinata chiave API che possono essere inviate in un intervallo di tempo specificato. Puoi configurare singoli metodi API per richiedere l'autorizzazione per le chiavi API in base alla configurazione del piano di utilizzo. I limiti di throttling e di quote si applicano alle richieste per le singole chiavi API che vengono aggregate nelle fasi API in un piano di utilizzo. **Nota** I piani di utilizzo della limitazione (della larghezza di banda della rete) e le quote non sono limiti rigidi e vengono applicati sulla base del miglior tentativo. In alcuni casi, i client possono superare le quote impostate. Non fare affidamento sulle quote del piano di utilizzo o limitazione (della larghezza di banda della rete) per controllare i costi o bloccare l'accesso a un'API. Considerare l’utilizzo di [Budget AWS](https://docs.aws.amazon.com/cost-management/latest/userguide/budgets-managing-costs.html) per monitorare i costi e [AWS WAF](https://docs.aws.amazon.com/waf/latest/developerguide/waf-chapter.html) gestire le richieste API. ## Best practice per le chiavi API e i piani di utilizzo Di seguito vengono fornite le best practice da seguire quando usi chiavi API e piani di utilizzo. **Importante** Non utilizzare chiavi API per l'autenticazione o l'autorizzazione per controllare l'accesso ai tuoi. APIs Se ne hai più APIs in un piano di utilizzo, un utente con una chiave API valida per un'API in quel piano di utilizzo può accedere APIs a *tutte le* API di quel piano di utilizzo. Per controllare gli accessi all'API, utilizza invece un ruolo IAM, un [sistema di autorizzazione Lambda](apigateway-use-lambda-authorizer.md) o un [pool di utenti di Amazon Cognito](apigateway-integrate-with-cognito.md). Utilizzare le chiavi API generate da API Gateway. Le chiavi API non devono includere informazioni riservate; i client in genere le trasmettono in intestazioni che possono essere registrate. + Se utilizzi un portale per sviluppatori per pubblicare i tuoi APIs, tieni presente che tutti i tuoi contenuti APIs in un determinato piano di utilizzo possono essere sottoscritti dai clienti, anche se non li hai resi visibili ai tuoi clienti. + In alcuni casi, i client possono superare le quote impostate. Non fare affidamento sui piani di utilizzo per controllare i costi. 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. + Dopo aver aggiunto una chiave API a un piano di utilizzo, il completamento dell'operazione di aggiornamento potrebbe richiedere alcuni minuti. # Scelta dell'origine di una chiave API in Gateway API Quando associ un piano di utilizzo a un'API e abiliti chiavi API su metodi API, ogni richiesta in ingresso all'API deve contenere una [chiave API](api-gateway-basic-concept.md#apigateway-definition-api-key). API Gateway legge la chiave e la confronta con le chiavi nel piano di utilizzo. Se esiste una corrispondenza, API Gateway esegue il throttling delle richieste in base alla quota e al limite delle richieste del piano. In caso contrario, genera un'eccezione `InvalidKeyParameter` e l'intermediario riceve una risposta `403 Forbidden`. L'API di API Gateway è in grado di ricevere chiavi API da una delle due seguenti origini: **`HEADER`** Devi distribuire le chiavi API ai clienti e chiedere loro di passare la chiave API come intestazione `X-API-Key` di ogni richiesta in ingresso. **`AUTHORIZER`** Puoi fare in modo che la chiave API venga restituita da un'autorizzazione Lambda come parte della risposta di autorizzazione. Per ulteriori informazioni sulla risposta delle autorizzazioni, consulta [Output da un sistema di autorizzazione Lambda di Gateway API](api-gateway-lambda-authorizer-output.md). **Nota** Per informazioni sulle best practice da prendere in considerazione, consulta [Best practice per le chiavi API e i piani di utilizzo](api-gateway-api-usage-plans.md#apigateway-usage-plans-best-practices). La procedura seguente descrive come scegliere un’origine della chiave API per un’API. ------ #### [ Console di gestione AWS ] **Per scegliere un’origine della chiave API per un’API** 1. Accedere alla console API Gateway. 1. Seleziona un'API esistente o creane una nuova. 1. Nel riquadro di navigazione principale, scegli **Impostazioni API**. 1. Nella sezione **Dettagli API**, scegli **Modifica**. 1. In **Origine chiave API**, seleziona `Header` o `Authorizer` nell'elenco a discesa. 1. Scegli **Save changes** (Salva modifiche). ------ #### [ AWS CLI ] Il [update-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-rest-api.html)comando seguente aggiorna un'API per impostare l'origine della chiave API su`AUTHORIZER`: ``` aws apigateway update-rest-api --rest-api-id 1234123412 --patch-operations op=replace,path=/apiKeySource,value=AUTHORIZER ``` Per fare in modo che il client invii una chiave API, impostare `value` su `HEADER` nel comando precedente. ------ #### [ REST API ] Per scegliere un'origine di chiave API per un'API utilizzando l'API REST API Gateway, invoca [https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateRestApi.html](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateRestApi.html) come segue: ``` PATCH /restapis/fugvjdxtri/ HTTP/1.1 Content-Type: application/json Host: apigateway.us-east-1.amazonaws.com X-Amz-Date: 20160603T205348Z Authorization: AWS4-HMAC-SHA256 Credential={access_key_ID}/20160603/us-east-1/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature={sig4_hash} { "patchOperations" : [ { "op" : "replace", "path" : "/apiKeySource", "value" : "HEADER" } ] } ``` Per fare in modo che un'autorizzazione restituisca una chiave API, imposta `value` su `AUTHORIZER` nell'input `patchOperations` precedente. ------ # Formato file chiave API di API Gateway API Gateway può importare le chiavi API dai file esterni in formato CSV (comma-separated value), quindi associare le chiavi importate a uno o più piani di utilizzo. Il file importato deve contenere le colonne `Name` e `Key`. Per i nomi delle intestazioni di colonna non viene rilevata la distinzione tra maiuscole e minuscole e le colonne possono essere disposte in qualsiasi ordine, come mostrato nel'esempio seguente: ``` Key,name apikey1234abcdefghij0123456789,MyFirstApiKey ``` Il valore di `Key` deve essere costituito da un numero di caratteri compreso tra 20 e 128. Un valore `Name` non può superare 1024 caratteri. Un file di chiavi API può includere anche la colonna `Description`, `Enabled` o `UsagePlanIds`, come mostrato nell'esempio seguente: ``` Name,key,description,Enabled,usageplanIds MyFirstApiKey,apikey1234abcdefghij0123456789,An imported key,TRUE,c7y23b ``` Quando una chiave è associata a più di un piano di utilizzo, il `UsagePlanIds` valore è una stringa separata da virgole del piano di utilizzo IDs, racchiusa tra un paio di virgolette doppie o singole, come illustrato nell'esempio seguente: ``` Enabled,Name,key,UsageplanIds true,MyFirstApiKey,apikey1234abcdefghij0123456789,"c7y23b,glvrsr" ``` Le colonne non riconosciute sono consentite ma vengono ignorate. Il valore predefinito è una stringa vuota o il valore booleano `true`. La stessa chiave API può essere importata più volte e la versione più recente sovrascrive la precedente. Due chiavi API sono identiche se hanno lo stesso valore `key`. **Nota** Per informazioni sulle best practice da prendere in considerazione, consulta [Best practice per le chiavi API e i piani di utilizzo](api-gateway-api-usage-plans.md#apigateway-usage-plans-best-practices). # Configura le chiavi API per REST APIs in API Gateway Per configurare le chiavi API, completa queste operazioni: + Configura i metodi API in modo che richiedano una chiave API. + Crea o importa in una Regione una chiave API per l’API. Prima di impostare le chiavi API, è necessario aver creato un'API e averla distribuita in una fase. Una volta creata una chiave API, non può essere modificata. Per istruzioni su come creare e distribuire un'API utilizzando la console API Gateway, consulta rispettivamente [Sviluppa REST APIs in API Gateway](rest-api-develop.md) e [Implementazione di REST API in Gateway API](how-to-deploy-api.md). Dopo aver creato una chiave API, è necessario associarla a un piano di utilizzo. Per ulteriori informazioni, consulta [Configurazione dei piani di utilizzo per REST APIs in API Gateway](api-gateway-create-usage-plans.md). **Nota** Per informazioni sulle best practice da prendere in considerazione, consulta [Best practice per le chiavi API e i piani di utilizzo](api-gateway-api-usage-plans.md#apigateway-usage-plans-best-practices). **Topics** + [ ## Richiesta di una chiave API per un metodo ](#api-gateway-usage-plan-configure-apikey-on-method) + [ ## Crea una chiave API ](#api-gateway-usage-plan-create-apikey) + [ ## Importazione di chiavi API ](#api-gateway-usage-pan-import-apikey) ## Richiesta di una chiave API per un metodo La procedura seguente mostra come configurare un metodo API in modo che richieda una chiave API. ------ #### [ Console di gestione AWS ] **Per configurare un metodo API in modo che richieda una chiave 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 di API Gateway, scegliere **Resources (Risorse)**. 1. In **Resources (Risorse)** creare un nuovo metodo o sceglierne uno esistente. 1. Nella scheda **Richiesta metodo**, in **Impostazioni richiesta metodo**, scegli **Modifica**. ![\[Aggiunta di una chiave API a un metodo\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/api-gateway-new-console-add-key-to-method.png) 1. Seleziona **Chiave API necessaria**. 1. Scegli **Save** (Salva). 1. Distribuisci o ridistribuisci l'API per rendere effettivo il requisito. Se l'opzione **Chiave API necessaria** è impostata su `false` e non si esegue la procedura precedente, la chiave API associata a una fase API non viene utilizzata per il metodo. ------ #### [ AWS CLI ] Il comando [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) seguente crea un metodo `PUT` che richiede una chiave API: ``` aws apigateway put-method \ --rest-api-id 1234123412 \ --resource-id a1b2c3 \ --http-method PUT \ --authorization-type "NONE" \ --api-key-required ``` Il comando [update-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-method.html) seguente aggiorna un metodo esistente in modo che richieda una chiave API: ``` aws apigateway update-method \ --rest-api-id 1234123412 \ --resource-id a1b2c3 \ --http-method PUT \ --patch-operations op="replace",path="/apiKeyRequired",value="true" ``` ------ #### [ REST API ] Per configurare un metodo in modo che richieda una chiave API, procedi in uno dei seguenti modi: + Invoca [https://docs.aws.amazon.com/apigateway/latest/api/API_PutMethod.html](https://docs.aws.amazon.com/apigateway/latest/api/API_PutMethod.html) per creare un metodo. Imposta `apiKeyRequired` un `true` nel payload di richiesta. + Invoca [https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateMethod.html](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateMethod.html) per impostare `apiKeyRequired` su `true`. ------ ## Crea una chiave API La procedura seguente mostra come creare una chiave API. Non tenere conto di questo passaggio se desideri importare la chiave API. ------ #### [ Console di gestione AWS ] **Per creare una chiave 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 di Gateway API, scegli **Chiavi API**. 1. Scegli **Crea chiave API**. ![\[Creazione di chiavi API per i piani di utilizzo\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/api-gateway-new-console-usage-plan-keys-choose-create-api-key-from-actions-menu.png) 1. In **Nome**, immetti un nome. 1. (Facoltativo) In **Descrizione**, immetti una descrizione. 1. In **Chiave API**, scegli **Genera automaticamente** per fare in modo che Gateway API generi il valore della chiave oppure scegli **Personalizza** per creare il tuo valore di chiave. 1. Scegli **Save** (Salva). ------ #### [ AWS CLI ] Il [create-api-key](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-api-key.html)comando seguente crea una chiave API: ``` aws apigateway create-api-key \ --name 'Dev API key' \ --description 'API key for Devs' \ --enabled ``` ------ #### [ REST API ] Invoca [https://docs.aws.amazon.com/apigateway/latest/api/API_CreateApiKey.html](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateApiKey.html) per creare una chiave API. ------ ## Importazione di chiavi API La procedura seguente descrive come importare le chiavi API. Non tenere conto di questo passaggio se è già stata creata una chiave API. ------ #### [ Console di gestione AWS ] **Per importare chiavi 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 **Chiavi API**. 1. Scegli il menu a discesa **Operazioni** e quindi **Importa chiavi API**. 1. Per caricare un file di chiavi con valori separati da virgole, scegli **Scegli file**. Puoi anche immettere le chiavi nell'editor di testo. Per informazioni sul formato del file, consulta [Formato file chiave API di API Gateway](api-key-file-format.md). 1. Scegli **Errore su avvertenze** per arrestare l'importazione se si verifica un errore oppure **Ignora avvisi** per continuare a importare voci di chiavi valide in caso di presenza di avvisi. 1. Scegli **Importa** per importare le tue chiavi API. ------ #### [ AWS CLI ] Il [import-api-keys](https://docs.aws.amazon.com/cli/latest/reference/apigateway/import-api-keys.html)comando seguente importa una chiave API: ``` aws apigateway import-api-key \ a--body fileb://keys.csv \ --format csv ``` ------ #### [ REST API ] Invoca [https://docs.aws.amazon.com/apigateway/latest/api/API_ImportApiKeys.html](https://docs.aws.amazon.com/apigateway/latest/api/API_ImportApiKeys.html) per importare una chiave API da un file. Per il formato file, consulta [Formato file chiave API di API Gateway](api-key-file-format.md). ------ Non è possibile modificare il valore della nuova chiave API. Dopo aver creato l’API, si configura un piano di utilizzo. Per ulteriori informazioni, consulta [Configurazione dei piani di utilizzo per REST APIs in API Gateway](api-gateway-create-usage-plans.md). # Configurazione dei piani di utilizzo per REST APIs in API Gateway Prima di creare un piano di utilizzo, è necessario avere configurato le chiavi API desiderate. Per ulteriori informazioni, consulta [Configura le chiavi API per REST APIs in API Gateway](api-gateway-setup-api-keys.md). **Topics** + [ ## Eseguire la migrazione dell'API a Piani di utilizzo predefiniti (se necessario) ](#api-gateway-usage-plan-migrate-to-default) + [ ## Creazione di un piano di utilizzo ](#api-gateway-usage-plan-create) + [ ## Aggiunta di una fase a un piano di utilizzo ](#api-gateway-usage-plan-add-stage) + [ ## Aggiunta di una chiave API a un piano di utilizzo ](#api-gateway-usage-plan-add-key) ## Eseguire la migrazione dell'API a Piani di utilizzo predefiniti (se necessario) Se hai iniziato a usare API Gateway *dopo* l'introduzione della caratteristica dei piani di utilizzo l'11 agosto 2016, troverai che i piani di utilizzo sono abilitati automaticamente in tutte le regioni supportate. Se hai iniziato a utilizzare API Gateway prima di quella data, potrebbe essere necessario migrare ai piani di utilizzo predefiniti. Ti verrà proposta l'opzione **Enable Usage Plans (Abilita piani di utilizzo)** prima di usare i piani di utilizzo per la prima volta nella regione selezionata. Quando abiliti questa opzione, vengono creati piani di utilizzo predefiniti per ogni fase API univoca associata alle chiavi API esistenti. Nel piano di utilizzo predefinito, non vengono impostati inizialmente throttle o limiti di quota e le associazioni tra le chiavi API e le fasi API sono copiate sui piani di utilizzo. Il comportamento dell'API resta inalterato. Tuttavia, è necessario utilizzare la [https://docs.aws.amazon.com/apigateway/latest/api/API_UsagePlan.html](https://docs.aws.amazon.com/apigateway/latest/api/API_UsagePlan.html)`apiStages`proprietà per associare i valori di fase dell'API specificati (`apiId`and`stage`) alle chiavi API incluse (via [https://docs.aws.amazon.com/apigateway/latest/api/API_UsagePlanKey.html](https://docs.aws.amazon.com/apigateway/latest/api/API_UsagePlanKey.html)), anziché utilizzare la [ApiKey](https://docs.aws.amazon.com/apigateway/latest/api/API_ApiKey.html)`stageKeys`proprietà. Per controllare se hai già eseguito la migrazione ai piani di utilizzo predefiniti, utilizza il comando della CLI [https://docs.aws.amazon.com/cli/latest/reference/apigateway/get-account.html](https://docs.aws.amazon.com/cli/latest/reference/apigateway/get-account.html). Nell'output del comando, l'elenco `features` include una voce `"UsagePlans"` quando i piani di utilizzo sono abilitati. Puoi anche APIs migrare i tuoi piani di utilizzo predefiniti utilizzando AWS CLI quanto segue: **Per migrare ai piani di utilizzo predefiniti utilizzando il AWS CLI** 1. Invoca questo comando della CLI: [https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-account.html](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-account.html). 1. Per il parametro `cli-input-json`, utilizza il seguente JSON: ``` [ { "op": "add", "path": "/features", "value": "UsagePlans" } ] ``` ## Creazione di un piano di utilizzo La procedura seguente illustra come creare un piano di utilizzo. ------ #### [ Console di gestione AWS ] **Per creare un piano di utilizzo** 1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway) 1. Nel riquadro di navigazione principale di Gateway API, scegli **Piani di utilizzo** e quindi **Crea piano di utilizzo**. ![\[Entità dei piani di utilizzo delle API\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/api-gateway-new-console-usage-plan-keys-create-setup.png) 1. In **Nome**, immetti un nome. 1. (Facoltativo) In **Descrizione**, immetti una descrizione. 1. Per impostazione predefinita, i piani di utilizzo abilitano la limitazione (della larghezza di banda della rete). Immetti un valore in **Tariffa** e **Ottimizzazione** per il tuo piano di utilizzo. Scegli **Throttling** per disattivare la limitazione (della larghezza di banda della rete). 1. Per impostazione predefinita, i piani di utilizzo abilitano una quota per un periodo di tempo. In **Richieste**, immetti il numero totale di richieste che un utente può effettuare nel periodo di validità del tuo piano di utilizzo. Scegli **Quota** per disattivare la quota. 1. Scegli **Crea piano di utilizzo**. ------ #### [ AWS CLI ] Il [create-usage-plan](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-usage-plan.html)comando seguente crea un piano di utilizzo che viene ripristinato all'inizio del mese: ``` aws apigateway create-usage-plan \ --name "New Usage Plan" \ --description "A new usage plan" \ --throttle burstLimit=10,rateLimit=5 \ --quota limit=500,offset=0,period=MONTH ``` ------ #### [ REST API ] Invoca [https://docs.aws.amazon.com/apigateway/latest/api/API_CreateUsagePlan.html](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateUsagePlan.html) per creare un piano di utilizzo. ------ ## Aggiunta di una fase a un piano di utilizzo La procedura seguente illustra come aggiungere una fase a un piano di utilizzo. ------ #### [ Console di gestione AWS ] **Per aggiungere una fase a un piano di utilizzo** 1. Seleziona il piano di utilizzo. 1. Nella scheda **Fasi associate**, scegli **Aggiungi fase**. ![\[Aggiungi una fase API a un piano di utilizzo.\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/api-gateway-new-console-usage-plan-keys-create-add-stage.png) 1. In **API**, seleziona un'API. 1. In **Fase**, seleziona una fase. 1. (Facoltativo) Per attivare la limitazione (della larghezza di banda della rete) a livello di metodo, esegui le operazioni indicate di seguito: 1. Scegli **Throttling a livello di metodo** e quindi **Aggiungi metodo**. 1. In**Risorsa**, seleziona una risorsa nella tua API. 1. In **Metodo**, seleziona un metodo nella tua API. 1. Immetti un valore in **Tariffa** e **Ottimizzazione** per il tuo piano di utilizzo. 1. Scegli **Aggiungi al piano di utilizzo**. ------ #### [ AWS CLI ] Il [update-usage-plan](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-usage-plan.html)comando seguente aggiunge lo `Prod` stadio di un'API a un piano di utilizzo: ``` aws apigateway update-usage-plan \ --usage-plan-id abc123 \ --patch-operations op="add",path="/apiStages",value="a1b1c2:Prod" ``` ------ #### [ REST API ] Chiama [https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateUsagePlan.html](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateUsagePlan.html) per aggiornare un piano di utilizzo. ------ ## Aggiunta di una chiave API a un piano di utilizzo La procedura seguente descrive come aggiungere una chiave API a un piano di utilizzo. ------ #### [ Console di gestione AWS ] **Per aggiungere una chiave a un piano di utilizzo** 1. Nella scheda **Chiavi API associate**, scegli **Aggiungi chiave API**. ![\[Entità dei piani di utilizzo delle API\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/api-gateway-new-console-usage-plan-keys-create-add-key.png) 1. 1. Per associare una chiave esistente al tuo piano di utilizzo, seleziona **Aggiungi chiave esistente**, quindi seleziona la chiave esistente nel menu a discesa. 1. Per creare una nuova chiave API, seleziona **Crea e aggiungi nuova chiave**, quindi crea una nuova chiave. Per ulteriori informazioni su come creare una nuova chiave, consulta [Crea una chiave API](api-gateway-setup-api-keys.md#api-gateway-usage-plan-create-apikey). 1. Scegli **Aggiungi chiave API**. ------ #### [ AWS CLI ] Il [create-usage-plan-key](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-usage-plan-key.html)comando seguente associa una chiave API esistente a un piano di utilizzo: ``` aws apigateway create-usage-plan-key \ --usage-plan-id a1b2c3 \ --key-type "API_KEY" \ --key-id aaa111bbb ``` ------ #### [ REST API ] Chiama [https://docs.aws.amazon.com/apigateway/latest/api/API_CreateUsagePlanKey.html](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateUsagePlanKey.html) per associare una chiave API esistente a un piano di utilizzo. Puoi anche associare direttamente APIs le tue chiavi a un piano di utilizzo quando le importi. Invoca [https://docs.aws.amazon.com/apigateway/latest/api/API_ImportApiKeys.html](https://docs.aws.amazon.com/apigateway/latest/api/API_ImportApiKeys.html) per aggiungere una o più chiavi API direttamente al piano di utilizzo specificato. Il payload della richiesta deve contenere valori di chiavi API, l'identificativo del piano di utilizzo associato, i flag booleani che indicano che le chiavi sono abilitate per il piano di utilizzo e, possibilmente, nomi e descrizioni delle chiavi API. L'esempio che segue della richiesta `apikey:import` aggiunge tre chiavi API (identificate da `key`, `name` e `description`) a un piano di utilizzo (identificato da `usageplanIds`): ``` POST /apikeys?mode=import&format=csv&failonwarnings=fase HTTP/1.1 Host: apigateway.us-east-1.amazonaws.com Content-Type: text/csv Authorization: ... key,name, description, enabled, usageplanIds abcdef1234ghijklmnop8901234567, importedKey_1, firstone, tRuE, n371pt abcdef1234ghijklmnop0123456789, importedKey_2, secondone, TRUE, n371pt abcdef1234ghijklmnop9012345678, importedKey_3, , true, n371pt ``` Di conseguenza, vengono create tre risorse `UsagePlanKey` che vengono aggiunte a `UsagePlan`. Puoi aggiungere chiavi API anche a più di un piano di utilizzo. A questo scopo, modifica ogni valore della colonna `usageplanIds` in una stringa separata da virgole contenente gli identificatori del piano di utilizzo selezionato e racchiusa tra apici (`"n371pt,m282qs"` o `'n371pt,m282qs'`). ------ **Nota** Una chiave API può essere associata a più piani di utilizzo. Un piano di utilizzo può essere associato a più fasi. Tuttavia, una determinata chiave API può essere associata a un solo piano di utilizzo per ogni fase dell'API. # Mantieni un piano di utilizzo per REST APIs in API Gateway La gestione di un piano di utilizzo implica il monitoraggio delle quote utilizzate e rimanenti in un determinato periodo di tempo, se necessario, e l'estensione delle quote rimanenti di una quantità specificata. Le procedure seguenti descrivono come monitorare le quote. ------ #### [ Console di gestione AWS ] **Per monitorare le quote utilizzate e rimanenti** 1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway) 1. Nel riquadro di navigazione principale di Gateway API, scegli **Piani di utilizzo**. 1. Seleziona un piano di utilizzo. 1. Scegli la scheda **Chiavi API associate** per visualizzare il numero di richieste rimanenti per il periodo di tempo per ciascuna chiave. 1. (Facoltativo) Scegli **Esporta dati di utilizzo**, quindi scegli una data in **Da** e una data in **A**. Quindi, scegli **JSON** o **CSV** per il formato dei dati esportati e infine scegli **Esporta**. L'esempio di seguito mostra un file esportato. ``` { "px1KW6...qBazOJH": [ [ 0, 5000 ], [ 0, 5000 ], [ 0, 10 ] ] } ``` I dati di utilizzo nell'esempio mostrano i dati di utilizzo per un client API identificato dalla chiave API (`px1KW6...qBazOJH`) tra il 1 e il 3 agosto 2016. I dati di utilizzo giornalieri mostrano le quote utilizzate e rimanenti. In questo esempio il sottoscrittore non ha ancora usato le quote riservate e l'amministratore o il proprietario dell'API ha ridotto la quota rimanente da 5000 a 10 il terzo giorno. Le procedure seguenti descrivono come modificare le quote. **Per estendere le quote rimanenti** 1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway) 1. Nel riquadro di navigazione principale di Gateway API, scegli **Piani di utilizzo**. 1. Seleziona un piano di utilizzo. 1. Scegli la scheda **Chiavi API associate** per visualizzare il numero di richieste rimanenti per il periodo di tempo per ciascuna chiave. 1. Seleziona una chiave API, quindi scegli **Concedi estensione utilizzo**. 1. Immetti un numero di quote in **Richieste rimanenti**. Puoi aumentare o diminuire le richieste rimanenti per il periodo di validità del tuo piano di utilizzo. 1. Scegli **Aggiorna quota**. ------ #### [ AWS CLI ] I seguenti [update-usage-plan](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-usage-plan.html)esempi aggiungono, rimuovono o modificano le impostazioni di limitazione a livello di metodo in un piano di utilizzo. **Nota** Assicurarsi di modificare `us-east-1` nel valore di regione appropriato per l'API. Per aggiungere o sostituire un limite di tasso per il throttling di una risorsa e un metodo singoli: ``` aws apigateway --region us-east-1 update-usage-plan --usage-plan-id planId --patch-operations op="replace",path="/apiStages/apiId:stage/throttle/resourcePath/httpMethod/rateLimit",value="0.1" ``` Per aggiungere o sostituire un limite di ottimizzazione per il throttling di una risorsa e un metodo singoli: ``` aws apigateway --region us-east-1 update-usage-plan --usage-plan-id planId --patch-operations op="replace",path="/apiStages/apiId:stage/throttle/resourcePath/httpMethod/burstLimit",value="1" ``` Per rimuovere le impostazioni di throttling a livello di metodo per una risorsa e un metodo singoli: ``` aws apigateway --region us-east-1 update-usage-plan --usage-plan-id planId --patch-operations op="remove",path="/apiStages/apiId:stage/throttle/resourcePath/httpMethod",value="" ``` Per rimuovere tutte le impostazioni di throttling a livello di metodo per un'API: ``` aws apigateway --region us-east-1 update-usage-plan --usage-plan-id planId --patch-operations op="remove",path="/apiStages/apiId:stage/throttle ",value="" ``` Di seguito è riportato un esempio utilizzando l'API di esempio Pet Store: ``` aws apigateway --region us-east-1 update-usage-plan --usage-plan-id planId --patch-operations op="replace",path="/apiStages/apiId:stage/throttle",value='"{\"/pets/GET\":{\"rateLimit\":1.0,\"burstLimit\":1},\"//GET\":{\"rateLimit\":1.0,\"burstLimit\":1}}"' ``` ------ #### [ REST API ] Chiama [https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateUsagePlan.html](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateUsagePlan.html) per gestire un piano di utilizzo. ------ # Crea e configura chiavi API e piani di utilizzo con CloudFormation Puoi utilizzarlo CloudFormation per richiedere chiavi API sui metodi API e creare un piano di utilizzo per un'API. Il CloudFormation modello di esempio esegue le seguenti operazioni: + Crea un'API Gateway API con i metodi `GET` e `POST`. + Richiede una chiave API per i metodi `GET` e `POST`. Questa API riceve le chiavi dall'intestazione `X-API-KEY` di ogni richiesta in entrata. + Creazione di una chiave API. + Crea un piano di utilizzo per specificare una quota mensile di 1000 richieste al mese, un limite di velocità di limitazione di 100 richieste al secondo e un limite di limitazione di 200 richieste al secondo. + Specifica un limite di velocità di limitazione a livello di metodo di 50 richieste al secondo e un limite a livello di metodo di 100 richieste al secondo per il metodo `GET`. + Associa le fasi API e le chiavi API al piano di utilizzo. ``` AWSTemplateFormatVersion: 2010-09-09 Parameters: StageName: Type: String Default: v1 Description: Name of API stage. KeyName: Type: String Default: MyKeyName Description: Name of an API key Resources: Api: Type: 'AWS::ApiGateway::RestApi' Properties: Name: keys-api ApiKeySourceType: HEADER PetsResource: Type: 'AWS::ApiGateway::Resource' Properties: RestApiId: !Ref Api ParentId: !GetAtt Api.RootResourceId PathPart: 'pets' PetsMethodGet: Type: 'AWS::ApiGateway::Method' Properties: RestApiId: !Ref Api ResourceId: !Ref PetsResource HttpMethod: GET ApiKeyRequired: true AuthorizationType: NONE Integration: Type: HTTP_PROXY IntegrationHttpMethod: GET Uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets/ PetsMethodPost: Type: 'AWS::ApiGateway::Method' Properties: RestApiId: !Ref Api ResourceId: !Ref PetsResource HttpMethod: POST ApiKeyRequired: true AuthorizationType: NONE Integration: Type: HTTP_PROXY IntegrationHttpMethod: GET Uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets/ ApiDeployment: Type: 'AWS::ApiGateway::Deployment' DependsOn: - PetsMethodGet Properties: RestApiId: !Ref Api StageName: !Sub '${StageName}' UsagePlan: Type: AWS::ApiGateway::UsagePlan DependsOn: - ApiDeployment Properties: Description: Example usage plan with a monthly quota of 1000 calls and method-level throttling for /pets GET ApiStages: - ApiId: !Ref Api Stage: !Sub '${StageName}' Throttle: "/pets/GET": RateLimit: 50.0 BurstLimit: 100 Quota: Limit: 1000 Period: MONTH Throttle: RateLimit: 100.0 BurstLimit: 200 UsagePlanName: "My Usage Plan" ApiKey: Type: AWS::ApiGateway::ApiKey Properties: Description: API Key Name: !Sub '${KeyName}' Enabled: True UsagePlanKey: Type: AWS::ApiGateway::UsagePlanKey Properties: KeyId: !Ref ApiKey KeyType: API_KEY UsagePlanId: !Ref UsagePlan Outputs: ApiRootUrl: Description: Root Url of the API Value: !Sub 'https://${Api}.execute-api.${AWS::Region}.amazonaws.com/${StageName}' ``` # Configurazione di un metodo per utilizzare le chiavi API con una definizione OpenAPI È possibile utilizzare una definizione OpenAPI per richiedere le chiavi API per un metodo. Crea l'oggetto requisito di sicurezza di ogni metodo per richiedere una chiave API che invochi il metodo. Quindi, definisci `api_key` nella definizione di sicurezza. Dopo aver creato l'API, aggiungi la nuova fase API al piano di utilizzo. L'esempio seguente crea un'API e richiede una chiave API per i metodi `POST` e `GET`: ------ #### [ OpenAPI 2.0 ] ``` { "swagger" : "2.0", "info" : { "version" : "2024-03-14T20:20:12Z", "title" : "keys-api" }, "basePath" : "/v1", "schemes" : [ "https" ], "paths" : { "/pets" : { "get" : { "responses" : { }, "security" : [ { "api_key" : [ ] } ], "x-amazon-apigateway-integration" : { "type" : "http_proxy", "httpMethod" : "GET", "uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets/", "passthroughBehavior" : "when_no_match" } }, "post" : { "responses" : { }, "security" : [ { "api_key" : [ ] } ], "x-amazon-apigateway-integration" : { "type" : "http_proxy", "httpMethod" : "GET", "uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets/", "passthroughBehavior" : "when_no_match" } } } }, "securityDefinitions" : { "api_key" : { "type" : "apiKey", "name" : "x-api-key", "in" : "header" } } } ``` ------ #### [ OpenAPI 3.0 ] ``` { "openapi" : "3.0.1", "info" : { "title" : "keys-api", "version" : "2024-03-14T20:20:12Z" }, "servers" : [ { "url" : "{basePath}", "variables" : { "basePath" : { "default" : "v1" } } } ], "paths" : { "/pets" : { "get" : { "security" : [ { "api_key" : [ ] } ], "x-amazon-apigateway-integration" : { "httpMethod" : "GET", "uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets/", "passthroughBehavior" : "when_no_match", "type" : "http_proxy" } }, "post" : { "security" : [ { "api_key" : [ ] } ], "x-amazon-apigateway-integration" : { "httpMethod" : "GET", "uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets/", "passthroughBehavior" : "when_no_match", "type" : "http_proxy" } } } }, "components" : { "securitySchemes" : { "api_key" : { "type" : "apiKey", "name" : "x-api-key", "in" : "header" } } } } ``` ------ # Testa i piani di utilizzo per REST APIs in API Gateway Ad esempio, utilizziamo l' PetStore API, che è stata creata in[Tutorial: creazione di un'API REST mediante l'importazione di un esempio](api-gateway-create-api-from-example.md). Presupponiamo che l'API sia configurata per l'uso della chiave API `Hiorr45VR...c4GJc`. La procedura seguente illustra come testare un piano di utilizzo. **Per testare il piano di utilizzo** + Fai una richiesta `GET` nella risorsa Pets (`/pets`), con i parametri di query `?type=...&page=...` dell'API (ad esempio, `xbvxlpijch`) in un piano di utilizzo: ``` GET /testStage/pets?type=dog&page=1 HTTP/1.1 x-api-key: Hiorr45VR...c4GJc Content-Type: application/x-www-form-urlencoded Host: xbvxlpijch.execute-api.ap-southeast-1.amazonaws.com X-Amz-Date: 20160803T001845Z Authorization: AWS4-HMAC-SHA256 Credential={access_key_ID}/20160803/ap-southeast-1/execute-api/aws4_request, SignedHeaders=content-type;host;x-amz-date;x-api-key, Signature={sigv4_hash} ``` **Nota** Devi inviare questa richiesta al componente `execute-api` di API Gateway e fornire la chiave API necessaria (ad esempio `Hiorr45VR...c4GJc`) nell'intestazione `x-api-key` obbligatoria. Se riesce, la risposta restituisce un codice di stato `200 OK` e un payload contenente i risultati richiesti dal back-end: Se dimentichi di impostare l'intestazione `x-api-key` o se la imposti con una chiave sbagliata, ottieni una risposta `403 Forbidden`. Tuttavia, se non hai configurato il metodo in modo che richieda una chiave API, probabilmente otterrai la risposta `200 OK`, anche se imposti l'intestazione `x-api-key` in modo non corretto e se vengono superati i imiti di throttling e di quota del piano di utilizzo. A volte, quando si verifica un errore interno in cui API Gateway non riesce ad applicare i limiti di throttling o le quote del piano di utilizzo per la richiesta, API Gateway elabora la richiesta senza applicare i limiti di throttling o le quote specificate nel piano i utilizzo. Tuttavia, registra un messaggio di errore `Usage Plan check failed due to an internal error` in CloudWatch. Puoi ignorare questi errori occasionali. # Chiamata di un metodo tramite una chiave API A seconda del tipo di origine della chiave API scelta, usa una delle procedure seguenti per utilizzare chiavi API con origine intestazione o chiavi API restituite dall'autorizzazione nell'invocazione di metodo: **Per utilizzare chiavi API con origine intestazione:** 1. Crea un'API con i metodi API desiderati e quindi implementa l'API in una fase. 1. Crea un nuovo piano di utilizzo o scegline uno esistente. Aggiungi la fase API distribuita al piano di utilizzo. Collega una chiave API al piano di utilizzo o scegli una chiave API esistente nel piano. Prendi nota del valore della chiave API scelta. 1. Configura i metodi API in modo che richiedano una chiave API. 1. Ridistribuisci l'API nella stessa fase. Se distribuisci l'API in una nuova fase, assicurati di aggiornare il piano di utilizzo per collegare la nuova fase API. 1. Chiama l'API utilizzando la chiave API. Il seguente comando curl di esempio invoca il metodo `GET` sulla risorsa `getUsers` della fase `prod` di un'API utilizzando una chiave API. ``` curl -H "X-API-Key: abcd1234" 'https://b123abcde4.execute-api.us-west-2.amazonaws.com/prod/getUsers' ``` Il client può ora chiamare i metodi API fornendo l'intestazione `x-api-key` con la chiave API scelta come valore di intestazione. Di seguito è riportato un esempio di chiamata: **Per utilizzare chiavi API con origine autorizzazione:** 1. Crea un'API con i metodi API desiderati e quindi implementa l'API in una fase. 1. Crea un nuovo piano di utilizzo o scegline uno esistente. Aggiungi la fase API distribuita al piano di utilizzo. Collega una chiave API al piano di utilizzo o scegli una chiave API esistente nel piano. Prendi nota del valore della chiave API scelta. 1. Crea una funzione di autorizzazione Lambda basata su token. Includi `usageIdentifierKey:{api-key}` come proprietà a livello di root della risposta di autorizzazione. Per istruzioni sulla creazione di un sistema di autorizzazione basato su token, consulta [Esempio di funzione del sistema di autorizzazione `TOKEN` Lambda](apigateway-use-lambda-authorizer.md#api-gateway-lambda-authorizer-token-lambda-function-create). 1. Configura i metodi API in modo che richiedano una chiave API e abilita anche l'autorizzazione Lambda per i metodi. 1. Ridistribuisci l'API nella stessa fase. Se distribuisci l'API in una nuova fase, assicurati di aggiornare il piano di utilizzo per collegare la nuova fase API. Il client può ora chiamare i metodi che richiedono la chiave API senza fornire esplicitamente una chiave API. La chiave API restituita dall'autorizzazione viene utilizzata automaticamente.