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à.
# Distribuisci il tuo REST APIs ai clienti in API Gateway
Questa sezione fornisce dettagli sulla distribuzione del tuo API Gateway APIs ai tuoi clienti. La distribuzione dell'API include la generazione SDKs per i clienti di applicazioni da scaricare e integrare con le loro applicazioni client, la documentazione dell'API in modo che i clienti sappiano come richiamarla dalle loro applicazioni client e la messa a disposizione dell'API come parte delle offerte di prodotti.
**Topics**
+ [Piani di utilizzo e chiavi API per REST APIs in API Gateway](api-gateway-api-usage-plans.md)
+ [Documentazione per REST APIs in API Gateway](api-gateway-documenting-api.md)
+ [Genera SDKs per REST APIs in API Gateway](how-to-generate-sdk.md)
+ [Vendi il tuo API Gateway APIs tramite Marketplace AWS](sell-api-as-saas-on-aws-marketplace.md)
# 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.
# Documentazione per REST APIs in API Gateway
Per aiutare i clienti a comprendere e utilizzare la tua API, è fondamentale documentarla. Per aiutarti a documentare l'API, API Gateway ti consente di aggiungere e aggiornare il contenuto della guida per le singole entità API come parte integrante del processo di sviluppo dell'API. API Gateway memorizza il contenuto di origine e ti consente di archiviare diverse versioni della documentazione. Puoi associare una versione della documentazione a una fase API, esportare uno snapshot di documentazione specifico della fase in un file OpenAPI esterno e distribuire il file come pubblicazione della documentazione.
Per documentare la tua API, puoi chiamare l'[API REST di API Gateway](https://docs.aws.amazon.com/apigateway/latest/api/), utilizzare una delle [AWS SDKs](https://aws.amazon.com/developer/tools/), utilizzare [AWS CLI](https://docs.aws.amazon.com/cli/latest/reference/apigateway/)for API Gateway o utilizzare la console API Gateway. Inoltre, puoi importare o esportare le parti della documentazione definite in un file OpenAPI esterno.
Per condividere la documentazione API con gli sviluppatori, puoi utilizzare un portale per sviluppatori. Per un esempio, consulta [Integrazione ReadMe con API Gateway per mantenere aggiornato il tuo Developer Hub o [Come semplificare lo sviluppo di API su Amazon API Gateway Using SmartBear SwaggerHub](https://aws.amazon.com/blogs/apn/how-to-streamline-api-development-on-amazon-api-gateway-using-smartbear-swaggerhub/)](https://aws.amazon.com/blogs/apn/integrating-readme-with-amazon-api-gateway-to-keep-your-developer-hub-up-to-date/) sul blog AWS Partner Network (APN).
**Topics**
+ [Rappresentazione della documentazione dell'API in API Gateway](api-gateway-documenting-api-content-representation.md)
+ [Documentare un'API utilizzando la console API Gateway](api-gateway-documenting-api-quick-start-with-console.md)
+ [Pubblicare la documentazione dell'API utilizzando la console API Gateway](apigateway-documenting-api-with-console.md)
+ [Documentare un'API utilizzando l'API REST di API Gateway](api-gateway-documenting-api-quick-start-with-restapi.md)
+ [Pubblicare la documentazione dell'API utilizzando l'API REST di API Gateway](api-gateway-documenting-api-quick-start-publishing.md)
+ [Importare la documentazione dell'API](api-gateway-documenting-api-quick-start-import-export.md)
+ [Controllo dell'accesso alla documentazione dell'API in Gateway API](api-gateway-documenting-api-content-provision-and-consumption.md)
# Rappresentazione della documentazione dell'API in API Gateway
La documentazione dell'API in API Gateway è costituita da singole parti associate a specifiche entità API che includono API, risorsa, metodo, richiesta, risposta parametri del messaggio (ad esempio, percorso, query, intestazione), nonché autorizzazioni e modelli.
In API Gateway, una parte della documentazione è rappresentata da una [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)risorsa. L'intera documentazione dell'API è rappresentata dalla [DocumentationParts](https://docs.aws.amazon.com/apigateway/latest/api/API_GetDocumentationParts.html)raccolta.
La documentazione di un'API implica la creazione di istanze di `DocumentationPart`, aggiungendole alla raccolta `DocumentationParts` e mantenendo le versioni delle parti della documentazione man mano che l'API evolve.
**Topics**
+ [Parti della documentazione](#api-gateway-documenting-api-content-representation-documentation-parts)
+ [Versioni della documentazione](#api-gateway-documenting-api-content-representation-documentation-versions)
## Parti della documentazione
Una [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)risorsa è un oggetto JSON che memorizza il contenuto della documentazione applicabile a una singola entità API. Sono inclusi contenuti UTF-8 e tutte le principali lingue di localizzazione per la documentazione. Il campo `properties` contiene il contenuto della documentazione sotto forma di mappa di coppie chiave-valore. La proprietà `location` identifica l'entità API associata.
La forma della mappa di contenuti è determinata da te, lo sviluppatore dell'API. Il valore di una coppia chiave-valore può essere una stringa, un numero, un booleano, un oggetto o una matrice. La forma dell'oggetto `location` dipende dal tipo di entità di destinazione.
La risorsa `DocumentationPart` supporta l'ereditarietà del contenuto: il contenuto della documentazione di un'entità API è applicabile agli elementi figlio dell'entità API. Per ulteriori informazioni sulla definizione di entità figlio ed ereditarietà del contenuto, consulta [Ereditare il contenuto da un'entità API di più specifiche generali](#api-gateway-documenting-api-content-inheritance).
### Posizione di una parte della documentazione
La proprietà [location](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html#location) di un'[DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)istanza identifica un'entità API a cui si applica il contenuto associato. L'entità API può essere una risorsa API REST di API Gateway, ad esempio [Resource [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html)](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html), [Method [MethodResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html)](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html), [Authorizer](https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html) o [Model](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html). L'entità può anche essere un parametro di messaggio, ad esempio un parametro di percorso URL, un parametro di stringa di query, un parametro di intestazione di richiesta o risposta, un corpo di richiesta o risposta o un codice di stato di risposta.
Per specificare un'entità API, impostare l'attributo [type](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html#type) dell'oggetto `location` su uno dei seguenti valori `API`, `AUTHORIZER`, `MODEL`, `RESOURCE`, `METHOD`, `PATH_PARAMETER`, `QUERY_PARAMETER`, `REQUEST_HEADER`, `REQUEST_BODY`, `RESPONSE`, `RESPONSE_HEADER` o `RESPONSE_BODY`.
A seconda dell'attributo `type` di un'entità API, è possibile specificare altri attributi `location`, tra cui [method](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html#method), [name](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html#name), [path](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html#path) e [statusCode](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html#statusCode). Non tutti questi attributi sono validi per una determinata entità API. Ad esempio, `type`, `path`, `name` e `statusCode` sono attributi validi dell'entità `RESPONSE`, solo `type` e `path` sono attributi di posizione validi dell'entità `RESOURCE`. Non è corretto includere un campo non valido nell'attributo `location` di `DocumentationPart` per una determinata entità API.
Non tutti i campi `location` validi sono obbligatori. Ad esempio, `type` è il campo `location` valido e obbligatorio di tutte le entità API. Tuttavia, `method`, `path` e `statusCode` sono attributi validi ma non obbligatori per l'entità `RESPONSE`. Se non è specificato esplicitamente, un campo `location` valido assume il valore predefinito. Il valore predefinito di `path` è `/`, vale a dire la risorsa radice di un'API. Il valore predefinito di `method` o `statusCode` è `*`, ossia qualsiasi valore di metodo o codice di stato, rispettivamente.
### Contenuto di una parte della documentazione
Il valore di `properties` è codificato come stringa JSON. Il valore `properties` contiene tutte le informazioni che hai scelto per soddisfare i tuoi requisiti di documentazione. Ad esempio, la seguente è una mappa di contenuti valida:
```
{
"info": {
"description": "My first API with Amazon API Gateway."
},
"x-custom-info" : "My custom info, recognized by OpenAPI.",
"my-info" : "My custom info not recognized by OpenAPI."
}
```
Anche se API Gateway accetta qualsiasi stringa JSON valida come mappa di contenuti, gli attributi del contenuto sono trattati come due categorie: quelli che possono e quelli che non possono essere riconosciuti da OpenAPI. Nell'esempio precedente, `info`, `description` e `x-custom-info` sono riconosciuti da OpenAPI come oggetto, proprietà o estensione OpenAPI standard. Di contro, `my-info` non è conforme alle specifiche OpenAPI. API Gateway propaga gli attributi di contenuto conformi a OpenAPI nelle definizioni di entità API delle istanze di `DocumentationPart` associate. API Gateway non propaga gli attributi di contenuto non conformi nelle definizioni di entità API.
Per un altro esempio, ecco un `DocumentationPart` mirato per un'entità `Resource`:
```
{
"location" : {
"type" : "RESOURCE",
"path": "/pets"
},
"properties" : {
"summary" : "The /pets resource represents a collection of pets in PetStore.",
"description": "... a child resource under the root...",
}
}
```
Qui, `type` e `path` sono entrambi campi validi per l'identificazione della destinazione del tipo `RESOURCE`. Per la risorsa radice (`/`), puoi omettere il campo `path`.
```
{
"location" : {
"type" : "RESOURCE"
},
"properties" : {
"description" : "The root resource with the default path specification."
}
}
```
È equivalente alla seguente istanza di `DocumentationPart`:
```
{
"location" : {
"type" : "RESOURCE",
"path": "/"
},
"properties" : {
"description" : "The root resource with an explicit path specification"
}
}
```
### Ereditare il contenuto da un'entità API di specifiche più generali
Il valore predefinito di un campo `location` facoltativo fornisce una descrizione di modello di un'entità API. Usando il valore predefinito dell'oggetto `location`, puoi aggiungere una descrizione generale nella mappa di `properties` a un'istanza di `DocumentationPart` con questo tipo di modello `location`. API Gateway estrae gli attributi della documentazione OpenAPI applicabili da `DocumentationPart` dell'entità API generica e li inserisce in un'entità API specifica con i campi `location` corrispondenti al modello `location` generale o corrispondenti al valore esatto, a meno che l'entità specifica non disponga già di un'istanza `DocumentationPart` associata. Questo comportamento è anche noto come ereditarietà del contenuto da un'entità API con specifiche più generali.
L'ereditarietà del contenuto non si applica a determinati tipi di entità API. Per informazioni dettagliate, consulta la tabella seguente.
Quando un'entità API corrisponde a più di un modello di posizione di `DocumentationPart`, l'entità erediterà la parte della documentazione con i campi di posizione con la precedenza e le specificità più elevate. L'ordine di precedenza è `path` > `statusCode`. Per la corrispondenza con il campo `path`, API Gateway sceglie l'entità con il valore del percorso più specifico. La seguente tabella mostra questo comportamento con alcuni esempi.
| Caso | `path` | `statusCode` | `name` | Remarks |
| --- | --- | --- | --- | --- |
| 1 | /pets | \$1 | id | La documentazione associata a questo modello di posizione verrà ereditata dalle entità che corrispondono al modello di posizione. |
| 2 | /pets | 200 | id | La documentazione associata a questo modello di posizione verrà ereditata dalle entità che corrispondono al modello di posizione in caso di corrispondenza con il caso 1 e il caso 2, in quanto il caso 2 è più specifico del caso 1. |
| 3 | /pets/petId | \$1 | id | La documentazione associata a questo modello di posizione verrà ereditata dalle entità che corrispondono al modello di posizione quando i casi 1, 2 e 3 sono corrispondenti, poiché il caso 3 ha una precedenza maggiore rispetto al caso 2 ed è più specifico del caso 1. |
Ecco un altro esempio per contrapporre un'istanza di `DocumentationPart` più generica con una più specifica. Il seguente messaggio di errore generale `"Invalid request error"` è inserito nelle definizioni di OpenAPI delle risposte dell'errore `400`, se non sostituite.
```
{
"location" : {
"type" : "RESPONSE",
"statusCode": "400"
},
"properties" : {
"description" : "Invalid request error."
}"
}
```
Con la seguente sostituzione, l'errore `400` che risponde ai metodi della risorsa `/pets` ha la descrizione `"Invalid petId specified"`.
```
{
"location" : {
"type" : "RESPONSE",
"path": "/pets",
"statusCode": "400"
},
"properties" : "{
"description" : "Invalid petId specified."
}"
}
```
### Campi di posizione di valid `DocumentationPart`
La tabella seguente mostra i campi validi e obbligatori, nonché i valori predefiniti applicabili di una [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)risorsa associata a un determinato tipo di entità API.
| Entità API | Campi di posizione validi | Campi di posizione obbligatori | Valori dei campi predefiniti | Contenuto ereditabile |
| --- | --- | --- | --- | --- |
| [API](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html) | {
"location": {
"type": "API"
},
...
} | type | N/A | No |
| [Risorsa](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) | {
"location": {
"type": "RESOURCE",
"path": "resource_path"
},
...
} | type | Il valore predefinito di path è /. | No |
| [Metodo](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html) | {
"location": {
"type": "METHOD",
"path": "resource_path",
"method": "http_verb"
},
...
} | type | I valori predefiniti di path e method sono / e \$1, rispettivamente. | Sì, con corrispondenza di path per il prefisso e corrispondenza di method per qualsiasi valore. |
| Parametro di query | {
"location": {
"type": "QUERY_PARAMETER",
"path": "resource_path",
"method": "HTTP_verb",
"name": "query_parameter_name"
},
...
} | type | I valori predefiniti di path e method sono / e \$1, rispettivamente. | Sì, con corrispondenza di path per il prefisso e corrispondenza di method per i valori esatti. |
| Corpo di richiesta | {
"location": {
"type": "REQUEST_BODY",
"path": "resource_path",
"method": "http_verb"
},
...
} | type | I valori predefiniti di path e method sono / e \$1, rispettivamente. | Sì, con corrispondenza di path per il prefisso e corrispondenza di method per i valori esatti. |
| Parametro di intestazione di richiesta | {
"location": {
"type": "REQUEST_HEADER",
"path": "resource_path",
"method": "HTTP_verb",
"name": "header_name"
},
...
} | type, name | I valori predefiniti di path e method sono / e \$1, rispettivamente. | Sì, con corrispondenza di path per il prefisso e corrispondenza di method per i valori esatti. |
| Parametro di percorso richiesta | {
"location": {
"type": "PATH_PARAMETER",
"path": "resource/{path_parameter_name}",
"method": "HTTP_verb",
"name": "path_parameter_name"
},
...
} | type, name | I valori predefiniti di path e method sono / e \$1, rispettivamente. | Sì, con corrispondenza di path per il prefisso e corrispondenza di method per i valori esatti. |
| Risposta | {
"location": {
"type": "RESPONSE",
"path": "resource_path",
"method": "http_verb",
"statusCode": "status_code"
},
...
} | type | I valori predefiniti di path, method e statusCode sono /, \$1 e \$1, rispettivamente. | Sì, con corrispondenza di path per il prefisso e corrispondenza di method e statusCode per i valori esatti. |
| Intestazione della risposta | {
"location": {
"type": "RESPONSE_HEADER",
"path": "resource_path",
"method": "http_verb",
"statusCode": "status_code",
"name": "header_name"
},
...
} | type, name | I valori predefiniti di path, method e statusCode sono /, \$1 e \$1, rispettivamente. | Sì, con corrispondenza di path per il prefisso e corrispondenza di method e statusCode per i valori esatti. |
| Corpo di risposta | {
"location": {
"type": "RESPONSE_BODY",
"path": "resource_path",
"method": "http_verb",
"statusCode": "status_code"
},
...
} | type | I valori predefiniti di path, method e statusCode sono /, \$1 e \$1, rispettivamente. | Sì, con corrispondenza di path per il prefisso e corrispondenza di method e statusCode per i valori esatti. |
| [Authorizer](https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html) | {
"location": {
"type": "AUTHORIZER",
"name": "authorizer_name"
},
...
} | type | N/A | No |
| [Modello](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html) | {
"location": {
"type": "MODEL",
"name": "model_name"
},
...
} | type | N/A | No |
## Versioni della documentazione
Una versione della documentazione è un'istantanea della [DocumentationParts](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)raccolta di un'API ed è contrassegnata con un identificatore di versione. La pubblicazione della documentazione di un'API implica la creazione di una versione della documentazione, l'associazione con una fase API e l'esportazione della versione specifica della fase della documentazione dell'API in un file OpenAPI esterno. In API Gateway, un'istantanea della documentazione è rappresentata come una [DocumentationVersion](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html)risorsa.
Quando aggiorni un'API, crei nuove versioni dell'API. In API Gateway, gestisci tutte le versioni della documentazione utilizzando la [DocumentationVersions](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html)raccolta.
# Documentare un'API utilizzando la console API Gateway
In questa sezione, viene descritto come creare e gestire la parti della documentazione di un'API tramite la console API Gateway.
Un prerequisito per la creazione e la modifica della documentazione di un'API è che l'API deve essere già stata creata. In questa sezione, utilizziamo l'[PetStore](http://petstore-demo-endpoint.execute-api.com/petstore/pets)API come esempio. Per creare un'API utilizzando la console API Gateway, seguire le istruzioni in [Tutorial: creazione di un'API REST mediante l'importazione di un esempio](api-gateway-create-api-from-example.md).
**Topics**
+ [Documentare l'entità `API`](#api-gateway-document-api-add-document-part-for-api-entity-with-console)
+ [Documentare un'entità `RESOURCE`](#api-gateway-document-api-add-document-part-for-resource-entity-with-console)
+ [Documentare un'entità `METHOD`](#api-gateway-document-api-add-document-part-for-method-entity-with-console)
+ [Documentare un'entità `QUERY_PARAMETER`](#api-gateway-document-api-add-document-part-for-request-query-entity-with-console)
+ [Documentare un'entità `PATH_PARAMETER`](#api-gateway-document-api-add-document-part-for-path-parameter-entity-with-console)
+ [Documentare un'entità `REQUEST_HEADER`](#api-gateway-document-api-add-document-part-for-request-header-entity-with-console)
+ [Documentare un'entità `REQUEST_BODY`](#api-gateway-document-api-add-document-part-for-request-body-entity-with-console)
+ [Documentare un'entità `RESPONSE`](#api-gateway-document-api-add-document-part-for-response-with-console)
+ [Documentare un'entità `RESPONSE_HEADER`](#api-gateway-document-api-add-document-part-for-response-header-entity-with-console)
+ [Documentare un'entità `RESPONSE_BODY`](#api-gateway-document-api-add-document-part-for-response-body-entity-with-console)
+ [Documentare un'entità `MODEL`](#api-gateway-document-api-add-document-part-for-model-entity-with-console)
+ [Documentare un'entità `AUTHORIZER`](#api-gateway-document-api-add-document-part-for-authorizer-entity-with-console)
## Documentare l'entità `API`
Per aggiungere una nuova parte della documentazione per l'entità `API`, procedi come segue:
1. Nel riquadro di navigazione principale scegli **Documentazione**, quindi seleziona **Crea parte della documentazione**.
1. Per **Tipo di documentazione** seleziona **API**.
Se una parte della documentazione non è stata creata per l'`API`, viene visualizzato l'editor della mappa di `properties` della parte della documentazione. Inserisci la seguente mappa di `properties` nell'editor di testo.
```
{
"info": {
"description": "Your first API Gateway API.",
"contact": {
"name": "John Doe",
"email": "john.doe@api.com"
}
}
}
```
**Nota**
Non è necessario codificare la mappa `properties` in una stringa JSON. La console API Gateway trasforma in stringa l'oggetto JSON per tuo conto.
1. Scegli **Crea parte della documentazione**.
Per aggiungere una nuova parte della documentazione per l'entità `API` nel riquadro **Risorse**, procedi come segue:
1. Nel riquadro di navigazione principale scegli **Risorse**.
1. Scegli il menu **Operazioni API**, quindi seleziona **Aggiorna documentazione dell'API**.
![\[Modificare la documentazione per l'entità API nella console API Gateway\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/document-api-entity-using-new-console.png)
Per modificare una parte della documentazione esistente, procedi come segue:
1. Nel riquadro **Documentazione** scegli la scheda **Risorse e metodi**.
1. Seleziona il nome dell'API, quindi nella scheda dell'API scegli **Modifica**.
## Documentare un'entità `RESOURCE`
Per aggiungere una nuova parte della documentazione per un'entità `RESOURCE`, procedi come segue:
1. Nel riquadro di navigazione principale scegli **Documentazione**, quindi seleziona **Crea parte della documentazione**.
1. Per **Tipo di documentazione** seleziona **Risorsa**.
1. Per **Percorso** inserisci un percorso.
1. Immetti una descrizione nell'editor di testo, ad esempio:
```
{
"description": "The PetStore's root resource."
}
```
1. Scegli **Crea parte della documentazione**. È possibile creare la documentazione per una risorsa non elencata.
1. Se necessario, ripeti queste fasi per aggiungere o modificare un'altra parte della documentazione.
Per aggiungere una nuova parte della documentazione per un'entità `RESOURCE` nel riquadro **Risorse**, procedi come segue:
1. Nel riquadro di navigazione principale scegli **Risorse**.
1. Scegli la risorsa, quindi seleziona **Aggiorna documentazione**.
![\[Modifica della documentazione per l'entità risorsa nella console Gateway API\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/document-resource-entity-using-new-console.png)
Per modificare una parte della documentazione esistente, procedi come segue:
1. Nel riquadro **Documentazione** scegli la scheda **Risorse e metodi**.
1. Seleziona la risorsa contenente la parte della documentazione, quindi scegli **Modifica**.
## Documentare un'entità `METHOD`
Per aggiungere una nuova parte della documentazione per un'entità `METHOD`, procedi come segue:
1. Nel riquadro di navigazione principale scegli **Documentazione**, quindi seleziona **Crea parte della documentazione**.
1. Per **Tipo di documentazione** seleziona **Metodo**.
1. Per **Percorso** inserisci un percorso.
1. Per **Metodo** seleziona un verbo HTTP.
1. Immetti una descrizione nell'editor di testo, ad esempio:
```
{
"tags" : [ "pets" ],
"summary" : "List all pets"
}
```
1. Scegli **Crea parte della documentazione**. È possibile creare la documentazione per un metodo non elencato.
1. Se necessario, ripeti queste fasi per aggiungere o modificare un'altra parte della documentazione.
Per aggiungere una nuova parte della documentazione per un'entità `METHOD` nel riquadro **Risorse**, procedi come segue:
1. Nel riquadro di navigazione principale scegli **Risorse**.
1. Scegli il metodo, quindi seleziona **Aggiorna documentazione**.
![\[Modifica della documentazione per l'entità metodo nella console Gateway API\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/document-method-entity-using-new-console.png)
Per modificare una parte della documentazione esistente, procedi come segue:
1. Nel riquadro **Documentazione** scegli la scheda **Risorse e metodi**.
1. È possibile selezionare il metodo o la risorsa contenente il metodo, quindi utilizzare la barra di ricerca per trovare e scegliere la parte della documentazione.
1. Scegli **Modifica**.
## Documentare un'entità `QUERY_PARAMETER`
Per aggiungere una nuova parte della documentazione per un'entità `QUERY_PARAMETER`, procedi come segue:
1. Nel riquadro di navigazione principale scegli **Documentazione**, quindi seleziona **Crea parte della documentazione**.
1. Per **Tipo di documentazione** seleziona **Parametro di query**.
1. Per **Percorso** inserisci un percorso.
1. Per **Metodo** seleziona un verbo HTTP.
1. In **Nome**, immetti un nome.
1. Immetti una descrizione nell'editor di testo.
1. Scegli **Crea parte della documentazione**. È possibile creare la documentazione per un parametro di query non elencato.
1. Se necessario, ripeti queste fasi per aggiungere o modificare un'altra parte della documentazione.
Per modificare una parte della documentazione esistente, procedi come segue:
1. Nel riquadro **Documentazione** scegli la scheda **Risorse e metodi**.
1. È possibile selezionare il parametro di query o la risorsa contenente il parametro di query, quindi utilizzare la barra di ricerca per trovare e scegliere la parte della documentazione.
1. Scegli **Modifica**.
## Documentare un'entità `PATH_PARAMETER`
Per aggiungere una nuova parte della documentazione per un'entità `PATH_PARAMETER`, procedi come segue:
1. Nel riquadro di navigazione principale scegli **Documentazione**, quindi seleziona **Crea parte della documentazione**.
1. Per **Tipo di documentazione** seleziona **Parametro di percorso**.
1. Per **Percorso** inserisci un percorso.
1. Per **Metodo** seleziona un verbo HTTP.
1. In **Nome**, immetti un nome.
1. Immetti una descrizione nell'editor di testo.
1. Scegli **Crea parte della documentazione**. È possibile creare la documentazione per un parametro di percorso non elencato.
1. Se necessario, ripeti queste fasi per aggiungere o modificare un'altra parte della documentazione.
Per modificare una parte della documentazione esistente, procedi come segue:
1. Nel riquadro **Documentazione** scegli la scheda **Risorse e metodi**.
1. È possibile selezionare il parametro di percorso o la risorsa contenente il parametro di percorso, quindi utilizzare la barra di ricerca per trovare e scegliere la parte della documentazione.
1. Scegli **Modifica**.
## Documentare un'entità `REQUEST_HEADER`
Per aggiungere una nuova parte della documentazione per un'entità `REQUEST_HEADER`, procedi come segue:
1. Nel riquadro di navigazione principale scegli **Documentazione**, quindi seleziona **Crea parte della documentazione**.
1. Per **Tipo di documentazione** seleziona **Intestazione della richiesta**.
1. Per **Percorso** inserisci il percorso dell'intestazione della richiesta.
1. Per **Metodo** seleziona un verbo HTTP.
1. In **Nome**, immetti un nome.
1. Immetti una descrizione nell'editor di testo.
1. Scegli **Crea parte della documentazione**. È possibile creare la documentazione per un'intestazione della richiesta non elencata.
1. Se necessario, ripeti queste fasi per aggiungere o modificare un'altra parte della documentazione.
Per modificare una parte della documentazione esistente, procedi come segue:
1. Nel riquadro **Documentazione** scegli la scheda **Risorse e metodi**.
1. È possibile selezionare l'intestazione della richiesta o la risorsa contenente l'intestazione della richiesta, quindi utilizzare la barra di ricerca per trovare e scegliere la parte della documentazione.
1. Scegli **Modifica**.
## Documentare un'entità `REQUEST_BODY`
Per aggiungere una nuova parte della documentazione per un'entità `REQUEST_BODY`, procedi come segue:
1. Nel riquadro di navigazione principale scegli **Documentazione**, quindi seleziona **Crea parte della documentazione**.
1. Per **Tipo di documentazione** seleziona **Corpo della richiesta**.
1. Per **Percorso** inserisci il percorso del corpo della richiesta.
1. Per **Metodo** seleziona un verbo HTTP.
1. Immetti una descrizione nell'editor di testo.
1. Scegli **Crea parte della documentazione**. È possibile creare la documentazione per un corpo della richiesta non elencato.
1. Se necessario, ripeti queste fasi per aggiungere o modificare un'altra parte della documentazione.
Per modificare una parte della documentazione esistente, procedi come segue:
1. Nel riquadro **Documentazione** scegli la scheda **Risorse e metodi**.
1. È possibile selezionare il corpo della richiesta o la risorsa contenente il corpo della richiesta, quindi utilizzare la barra di ricerca per trovare e scegliere la parte della documentazione.
1. Scegli **Modifica**.
## Documentare un'entità `RESPONSE`
Per aggiungere una nuova parte della documentazione per un'entità `RESPONSE`, procedi come segue:
1. Nel riquadro di navigazione principale scegli **Documentazione**, quindi seleziona **Crea parte della documentazione**.
1. Per **Tipo di documentazione** seleziona **Risposta (codice di stato)**.
1. Per **Percorso** inserisci un percorso per la risposta.
1. Per **Metodo** seleziona un verbo HTTP.
1. Per **Codice di stato** inserisci un codice di stato HTTP.
1. Immetti una descrizione nell'editor di testo.
1. Scegli **Crea parte della documentazione**. È possibile creare la documentazione per un codice di stato della risposta non elencato.
1. Se necessario, ripeti queste fasi per aggiungere o modificare un'altra parte della documentazione.
Per modificare una parte della documentazione esistente, procedi come segue:
1. Nel riquadro **Documentazione** scegli la scheda **Risorse e metodi**.
1. È possibile selezionare il codice di stato della risposta o la risorsa contenente il codice di stato della risposta, quindi utilizzare la barra di ricerca per trovare e scegliere la parte della documentazione.
1. Scegli **Modifica**.
## Documentare un'entità `RESPONSE_HEADER`
Per aggiungere una nuova parte della documentazione per un'entità `RESPONSE_HEADER`, procedi come segue:
1. Nel riquadro di navigazione principale scegli **Documentazione**, quindi seleziona **Crea parte della documentazione**.
1. Per **Tipo di documentazione** seleziona **Intestazione della risposta**.
1. Per **Percorso** inserisci un percorso per l'intestazione della risposta.
1. Per **Metodo** seleziona un verbo HTTP.
1. Per **Codice di stato** inserisci un codice di stato HTTP.
1. Immetti una descrizione nell'editor di testo.
1. Scegli **Crea parte della documentazione**. È possibile creare la documentazione per un'intestazione della risposta non elencata.
1. Se necessario, ripeti queste fasi per aggiungere o modificare un'altra parte della documentazione.
Per modificare una parte della documentazione esistente, procedi come segue:
1. Nel riquadro **Documentazione** scegli la scheda **Risorse e metodi**.
1. È possibile selezionare l'intestazione della risposta o la risorsa contenente l'intestazione della risposta, quindi utilizzare la barra di ricerca per trovare e scegliere la parte della documentazione.
1. Scegli **Modifica**.
## Documentare un'entità `RESPONSE_BODY`
Per aggiungere una nuova parte della documentazione per un'entità `RESPONSE_BODY`, procedi come segue:
1. Nel riquadro di navigazione principale scegli **Documentazione**, quindi seleziona **Crea parte della documentazione**.
1. Per **Tipo di documentazione** seleziona **Corpo della risposta**.
1. Per **Percorso** inserisci un percorso per il corpo della risposta.
1. Per **Metodo** seleziona un verbo HTTP.
1. Per **Codice di stato** inserisci un codice di stato HTTP.
1. Immetti una descrizione nell'editor di testo.
1. Scegli **Crea parte della documentazione**. È possibile creare la documentazione per un corpo della risposta non elencato.
1. Se necessario, ripeti queste fasi per aggiungere o modificare un'altra parte della documentazione.
Per modificare una parte della documentazione esistente, procedi come segue:
1. Nel riquadro **Documentazione** scegli la scheda **Risorse e metodi**.
1. È possibile selezionare il corpo della risposta o la risorsa contenente il corpo della risposta, quindi utilizzare la barra di ricerca per trovare e scegliere la parte della documentazione.
1. Scegli **Modifica**.
## Documentare un'entità `MODEL`
La documentazione di un'entità `MODEL` comporta la creazione e la gestione delle istanze di `DocumentPart` per il modello e gli elementi `properties` del modello. Ad esempio, per il modello `Error` fornito con ogni API per impostazione predefinita ha la seguente definizione dello schema:
```
{
"$schema" : "http://json-schema.org/draft-04/schema#",
"title" : "Error Schema",
"type" : "object",
"properties" : {
"message" : { "type" : "string" }
}
}
```
e richiede due istanze di `DocumentationPart`, una per `Model` e l'altra per la relativa proprietà `message`:
```
{
"location": {
"type": "MODEL",
"name": "Error"
},
"properties": {
"title": "Error Schema",
"description": "A description of the Error model"
}
}
```
e
```
{
"location": {
"type": "MODEL",
"name": "Error.message"
},
"properties": {
"description": "An error message."
}
}
```
Quando l'API viene esportata, le proprietà di `DocumentationPart` sostituiscono i valori dello schema originale.
Per aggiungere una nuova parte della documentazione per un'entità `MODEL`, procedi come segue:
1. Nel riquadro di navigazione principale scegli **Documentazione**, quindi seleziona **Crea parte della documentazione**.
1. Per **Tipo di documentazione** seleziona **Modello**.
1. Per **Nome** inserisci un nome per il processo.
1. Immetti una descrizione nell'editor di testo.
1. Scegli **Crea parte della documentazione**. È possibile creare la documentazione per modelli non elencati.
1. Se necessario, ripeti queste fasi per aggiungere o modificare una parte della documentazione per altri modelli.
Per aggiungere una nuova parte della documentazione per un'entità `MODEL` nel riquadro **Modelli**, procedi come segue:
1. Nel riquadro di navigazione principale seleziona **Modelli**.
1. Scegli il modello, quindi seleziona **Aggiorna documentazione**.
![\[Modifica della documentazione per l'entità modello nella console Gateway API\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/document-model-entity-using-new-console.png)
Per modificare una parte della documentazione esistente, procedi come segue:
1. Nel riquadro **Documentazione** scegli la scheda **Modelli**.
1. Utilizza la barra di ricerca o seleziona il modello, quindi scegli **Modifica**.
## Documentare un'entità `AUTHORIZER`
Per aggiungere una nuova parte della documentazione per un'entità `AUTHORIZER`, procedi come segue:
1. Nel riquadro di navigazione principale scegli **Documentazione**, quindi seleziona **Crea parte della documentazione**.
1. Per **Tipo di documentazione** seleziona **Sistema di autorizzazione**.
1. Per **Nome** immetti il nome del sistema di autorizzazione.
1. Immetti una descrizione nell'editor di testo. Specifica un valore per il campo `location` valido per il sistema di autorizzazione.
1. Scegli **Crea parte della documentazione**. È possibile creare la documentazione per sistemi di autorizzazione non elencati.
1. Se necessario, ripeti queste fasi per aggiungere o modificare una parte della documentazione per altre autorizzazioni.
Per modificare una parte della documentazione esistente, procedi come segue:
1. Nel riquadro **Documentazione** scegli la scheda **Sistemi di autorizzazione**.
1. Utilizza la barra di ricerca o seleziona il sistema di autorizzazione, quindi scegli **Modifica**.
# Pubblicare la documentazione dell'API utilizzando la console API Gateway
La procedura seguente mostra come pubblicare una versione della documentazione.
**Per pubblicare una versione della documentazione utilizzando la console API Gateway**
1. Nel riquadro di navigazione principale scegli **Documentazione**.
1. Seleziona **Pubblica documentazione**.
1. Configura la pubblicazione:
1. In **Fase**, seleziona una fase.
1. Per **Versione** inserisci un identificatore di versione, ad esempio `1.0.0`.
1. (Facoltativo) In **Descrizione**, immetti una descrizione.
1. Seleziona **Publish** (Pubblica).
Ora puoi procedere con il download della documentazione pubblicata esportando la documentazione in un file OpenAPI esterno. Per ulteriori informazioni, consulta [Esportazione di un'API REST da API Gateway](api-gateway-export-api.md).
# Documentare un'API utilizzando l'API REST di API Gateway
In questa sezione viene descritto come creare e gestire la parti della documentazione di un'API tramite l'API REST di API Gateway.
Un prerequisito per la creazione e la modifica della documentazione di un'API è aver già creato l'API. In questa sezione, utilizziamo l'[PetStore](http://petstore-demo-endpoint.execute-api.com/petstore/pets)API come esempio. Per creare un'API utilizzando la console API Gateway, seguire le istruzioni in [Tutorial: creazione di un'API REST mediante l'importazione di un esempio](api-gateway-create-api-from-example.md).
**Topics**
+ [Documentare l'entità `API`](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-api)
+ [Documentare un'entità `RESOURCE`](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-resource)
+ [Documentare un'entità `METHOD`](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-method)
+ [Documentare un'entità `QUERY_PARAMETER`](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-query-parameter)
+ [Documentare un'entità `PATH_PARAMETER`](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-path-parameter)
+ [Documentare un'entità `REQUEST_BODY`](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-request-body)
+ [Documentare un'entità `REQUEST_HEADER`](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-request-header)
+ [Documentare un'entità `RESPONSE`](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-response)
+ [Documentare un'entità `RESPONSE_HEADER`](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-response-header)
+ [Documentare un'entità `AUTHORIZER`](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-authorizer)
+ [Documentare un'entità `MODEL`](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-model)
+ [Aggiornare le parti della documentazione](#api-gateway-documenting-api-quick-start-with-restapi-update-content)
+ [Elencare le parti della documentazione](#api-gateway-documenting-api-quick-start-with-restapi-list-parts)
## Documentare l'entità `API`
Per aggiungere la documentazione per un'[API](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html), aggiungi una [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)risorsa per l'entità API:
```
POST /restapis/restapi_id/documentation/parts HTTP/1.1
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
{
"location" : {
"type" : "API"
},
"properties": "{\n\t\"info\": {\n\t\t\"description\" : \"Your first API with Amazon API Gateway.\"\n\t}\n}"
}
```
Se con esito positivo, l'operazione restituisce una risposta `201 Created` contenente la nuova istanza `DocumentationPart` creata nel payload. Ad esempio:
```
{
...
"id": "s2e5xf",
"location": {
"path": null,
"method": null,
"name": null,
"statusCode": null,
"type": "API"
},
"properties": "{\n\t\"info\": {\n\t\t\"description\" : \"Your first API with Amazon API Gateway.\"\n\t}\n}"
}
```
Se la documentazione è già stata aggiunta, viene restituita una risposta `409 Conflict` contenente il messaggio di errore `Documentation part already exists for the specified location: type 'API'."`. In questo caso è necessario eseguire l'operazione [documentationpart:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateDocumentationPart.html).
```
PATCH /restapis/4wk1k4onj3/documentation/parts/part_id HTTP/1.1
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
{
"patchOperations" : [ {
"op" : "replace",
"path" : "/properties",
"value" : "{\n\t\"info\": {\n\t\t\"description\" : \"Your first API with Amazon API Gateway.\"\n\t}\n}"
} ]
}
```
La risposta con esito positivo restituisce un codice di stato `200 OK` con un payload che include l'istanza `DocumentationPart` aggiornata nel payload.
## Documentare un'entità `RESOURCE`
Per aggiungere la documentazione per la risorsa principale di un'API, aggiungi una [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)risorsa destinata alla risorsa di [risorsa](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) corrispondente:
```
POST /restapis/restapi_id/documentation/parts HTTP/1.1
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
{
"location" : {
"type" : "RESOURCE",
},
"properties" : "{\n\t\"description\" : \"The PetStore root resource.\"\n}"
}
```
Se con esito positivo, l'operazione restituisce una risposta `201 Created` contenente la nuova istanza `DocumentationPart` creata nel payload. Ad esempio:
```
{
"_links": {
"curies": {
"href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html",
"name": "documentationpart",
"templated": true
},
"self": {
"href": "/restapis/4wk1k4onj3/documentation/parts/p76vqo"
},
"documentationpart:delete": {
"href": "/restapis/4wk1k4onj3/documentation/parts/p76vqo"
},
"documentationpart:update": {
"href": "/restapis/4wk1k4onj3/documentation/parts/p76vqo"
}
},
"id": "p76vqo",
"location": {
"path": "/",
"method": null,
"name": null,
"statusCode": null,
"type": "RESOURCE"
},
"properties": "{\n\t\"description\" : \"The PetStore root resource.\"\n}"
}
```
Quando il percorso della risorsa non è specificato, si presume che la risorsa sia la risorsa radice. Puoi aggiungere `"path": "/"` a `properties` per rendere esplicita la specifica.
Per creare la documentazione per una risorsa figlia di un'API, aggiungi una [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)risorsa destinata alla risorsa [Resource](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) corrispondente:
```
POST /restapis/restapi_id/documentation/parts HTTP/1.1
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
{
"location" : {
"type" : "RESOURCE",
"path" : "/pets"
},
"properties": "{\n\t\"description\" : \"A child resource under the root of PetStore.\"\n}"
}
```
Se con esito positivo, l'operazione restituisce una risposta `201 Created` contenente la nuova istanza `DocumentationPart` creata nel payload. Esempio:
```
{
"_links": {
"curies": {
"href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html",
"name": "documentationpart",
"templated": true
},
"self": {
"href": "/restapis/4wk1k4onj3/documentation/parts/qcht86"
},
"documentationpart:delete": {
"href": "/restapis/4wk1k4onj3/documentation/parts/qcht86"
},
"documentationpart:update": {
"href": "/restapis/4wk1k4onj3/documentation/parts/qcht86"
}
},
"id": "qcht86",
"location": {
"path": "/pets",
"method": null,
"name": null,
"statusCode": null,
"type": "RESOURCE"
},
"properties": "{\n\t\"description\" : \"A child resource under the root of PetStore.\"\n}"
}
```
Per aggiungere la documentazione per una risorsa secondaria specificata da un parametro path, aggiungi una [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)risorsa destinata alla [risorsa Resource](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html):
```
POST /restapis/restapi_id/documentation/parts HTTP/1.1
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
{
"location" : {
"type" : "RESOURCE",
"path" : "/pets/{petId}"
},
"properties": "{\n\t\"description\" : \"A child resource specified by the petId path parameter.\"\n}"
}
```
Se con esito positivo, l'operazione restituisce una risposta `201 Created` contenente la nuova istanza `DocumentationPart` creata nel payload. Esempio:
```
{
"_links": {
"curies": {
"href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html",
"name": "documentationpart",
"templated": true
},
"self": {
"href": "/restapis/4wk1k4onj3/documentation/parts/k6fpwb"
},
"documentationpart:delete": {
"href": "/restapis/4wk1k4onj3/documentation/parts/k6fpwb"
},
"documentationpart:update": {
"href": "/restapis/4wk1k4onj3/documentation/parts/k6fpwb"
}
},
"id": "k6fpwb",
"location": {
"path": "/pets/{petId}",
"method": null,
"name": null,
"statusCode": null,
"type": "RESOURCE"
},
"properties": "{\n\t\"description\" : \"A child resource specified by the petId path parameter.\"\n}"
}
```
**Nota**
L'[DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)istanza di un'`RESOURCE`entità non può essere ereditata da nessuna delle sue risorse secondarie.
## Documentare un'entità `METHOD`
Per aggiungere la documentazione per un metodo di un'API, aggiungi una [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)risorsa destinata alla risorsa [Method](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html) corrispondente:
```
POST /restapis/restapi_id/documentation/parts HTTP/1.1
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
{
"location" : {
"type" : "METHOD",
"path" : "/pets",
"method" : "GET"
},
"properties": "{\n\t\"summary\" : \"List all pets.\"\n}"
}
```
Se con esito positivo, l'operazione restituisce una risposta `201 Created` contenente la nuova istanza `DocumentationPart` creata nel payload. Ad esempio:
```
{
"_links": {
"curies": {
"href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html",
"name": "documentationpart",
"templated": true
},
"self": {
"href": "/restapis/4wk1k4onj3/documentation/parts/o64jbj"
},
"documentationpart:delete": {
"href": "/restapis/4wk1k4onj3/documentation/parts/o64jbj"
},
"documentationpart:update": {
"href": "/restapis/4wk1k4onj3/documentation/parts/o64jbj"
}
},
"id": "o64jbj",
"location": {
"path": "/pets",
"method": "GET",
"name": null,
"statusCode": null,
"type": "METHOD"
},
"properties": "{\n\t\"summary\" : \"List all pets.\"\n}"
}
```
Se con esito positivo, l'operazione restituisce una risposta `201 Created` contenente la nuova istanza `DocumentationPart` creata nel payload. Ad esempio:
```
{
"_links": {
"curies": {
"href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html",
"name": "documentationpart",
"templated": true
},
"self": {
"href": "/restapis/4wk1k4onj3/documentation/parts/o64jbj"
},
"documentationpart:delete": {
"href": "/restapis/4wk1k4onj3/documentation/parts/o64jbj"
},
"documentationpart:update": {
"href": "/restapis/4wk1k4onj3/documentation/parts/o64jbj"
}
},
"id": "o64jbj",
"location": {
"path": "/pets",
"method": "GET",
"name": null,
"statusCode": null,
"type": "METHOD"
},
"properties": "{\n\t\"summary\" : \"List all pets.\"\n}"
}
```
Se il campo `location.method` non è specificato nella richiesta precedente, si presume che sia il metodo `ANY` rappresentato da un carattere jolly `*`.
Per aggiornare il contenuto della documentazione di un'entità `METHOD`, chiamare l'operazione [documentationpart:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateDocumentationPart.html), fornendo una nuova mappa di `properties`:
```
PATCH /restapis/4wk1k4onj3/documentation/parts/part_id HTTP/1.1
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
{
"patchOperations" : [ {
"op" : "replace",
"path" : "/properties",
"value" : "{\n\t\"tags\" : [ \"pets\" ], \n\t\"summary\" : \"List all pets.\"\n}"
} ]
}
```
La risposta con esito positivo restituisce un codice di stato `200 OK` con un payload che include l'istanza `DocumentationPart` aggiornata nel payload. Ad esempio:
```
{
"_links": {
"curies": {
"href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html",
"name": "documentationpart",
"templated": true
},
"self": {
"href": "/restapis/4wk1k4onj3/documentation/parts/o64jbj"
},
"documentationpart:delete": {
"href": "/restapis/4wk1k4onj3/documentation/parts/o64jbj"
},
"documentationpart:update": {
"href": "/restapis/4wk1k4onj3/documentation/parts/o64jbj"
}
},
"id": "o64jbj",
"location": {
"path": "/pets",
"method": "GET",
"name": null,
"statusCode": null,
"type": "METHOD"
},
"properties": "{\n\t\"tags\" : [ \"pets\" ], \n\t\"summary\" : \"List all pets.\"\n}"
}
```
## Documentare un'entità `QUERY_PARAMETER`
Per aggiungere la documentazione per un parametro di query di richiesta, aggiungete una [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)risorsa mirata al `QUERY_PARAMETER` tipo, con i campi validi di `path` and`name`.
```
POST /restapis/restapi_id/documentation/parts HTTP/1.1
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
{
"location" : {
"type" : "QUERY_PARAMETER",
"path" : "/pets",
"method" : "GET",
"name" : "page"
},
"properties": "{\n\t\"description\" : \"Page number of results to return.\"\n}"
}
```
Se con esito positivo, l'operazione restituisce una risposta `201 Created` contenente la nuova istanza `DocumentationPart` creata nel payload. Ad esempio:
```
{
"_links": {
"curies": {
"href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html",
"name": "documentationpart",
"templated": true
},
"self": {
"href": "/restapis/4wk1k4onj3/documentation/parts/h9ht5w"
},
"documentationpart:delete": {
"href": "/restapis/4wk1k4onj3/documentation/parts/h9ht5w"
},
"documentationpart:update": {
"href": "/restapis/4wk1k4onj3/documentation/parts/h9ht5w"
}
},
"id": "h9ht5w",
"location": {
"path": "/pets",
"method": "GET",
"name": "page",
"statusCode": null,
"type": "QUERY_PARAMETER"
},
"properties": "{\n\t\"description\" : \"Page number of results to return.\"\n}"
}
```
La mappa di `properties` della parte della documentazione di un'entità `QUERY_PARAMETER` può essere ereditata da uno delle relative entità figlio `QUERY_PARAMETER`. Ad esempio se aggiungi una risorsa `treats` dopo `/pets/{petId}`, abiliti il metodo `GET` su `/pets/{petId}/treats` ed esponi il parametro di query `page`, questo parametro di query figlio eredita la mappa di `DocumentationPart` di `properties` dal parametro di query con nome simile del metodo `GET /pets`, a meno che non aggiungi esplicitamente una risorsa `DocumentationPart` al parametro di query `page` del metodo `GET /pets/{petId}/treats`.
## Documentare un'entità `PATH_PARAMETER`
Per aggiungere la documentazione per un parametro di percorso, aggiungi una [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)risorsa per l'`PATH_PARAMETER`entità.
```
POST /restapis/restapi_id/documentation/parts HTTP/1.1
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
{
"location" : {
"type" : "PATH_PARAMETER",
"path" : "/pets/{petId}",
"method" : "*",
"name" : "petId"
},
"properties": "{\n\t\"description\" : \"The id of the pet to retrieve.\"\n}"
}
```
Se con esito positivo, l'operazione restituisce una risposta `201 Created` contenente la nuova istanza `DocumentationPart` creata nel payload. Ad esempio:
```
{
"_links": {
"curies": {
"href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html",
"name": "documentationpart",
"templated": true
},
"self": {
"href": "/restapis/4wk1k4onj3/documentation/parts/ckpgog"
},
"documentationpart:delete": {
"href": "/restapis/4wk1k4onj3/documentation/parts/ckpgog"
},
"documentationpart:update": {
"href": "/restapis/4wk1k4onj3/documentation/parts/ckpgog"
}
},
"id": "ckpgog",
"location": {
"path": "/pets/{petId}",
"method": "*",
"name": "petId",
"statusCode": null,
"type": "PATH_PARAMETER"
},
"properties": "{\n \"description\" : \"The id of the pet to retrieve\"\n}"
}
```
## Documentare un'entità `REQUEST_BODY`
Per aggiungere documentazione per un corpo della richiesta, aggiungi una [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)risorsa per il corpo della richiesta.
```
POST /restapis/restapi_id/documentation/parts HTTP/1.1
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
{
"location" : {
"type" : "REQUEST_BODY",
"path" : "/pets",
"method" : "POST"
},
"properties": "{\n\t\"description\" : \"A Pet object to be added to PetStore.\"\n}"
}
```
Se con esito positivo, l'operazione restituisce una risposta `201 Created` contenente la nuova istanza `DocumentationPart` creata nel payload. Ad esempio:
```
{
"_links": {
"curies": {
"href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html",
"name": "documentationpart",
"templated": true
},
"self": {
"href": "/restapis/4wk1k4onj3/documentation/parts/kgmfr1"
},
"documentationpart:delete": {
"href": "/restapis/4wk1k4onj3/documentation/parts/kgmfr1"
},
"documentationpart:update": {
"href": "/restapis/4wk1k4onj3/documentation/parts/kgmfr1"
}
},
"id": "kgmfr1",
"location": {
"path": "/pets",
"method": "POST",
"name": null,
"statusCode": null,
"type": "REQUEST_BODY"
},
"properties": "{\n\t\"description\" : \"A Pet object to be added to PetStore.\"\n}"
}
```
## Documentare un'entità `REQUEST_HEADER`
Per aggiungere documentazione per l'intestazione di una richiesta, aggiungi una [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)risorsa per l'intestazione della richiesta.
```
POST /restapis/restapi_id/documentation/parts HTTP/1.1
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
{
"location" : {
"type" : "REQUEST_HEADER",
"path" : "/pets",
"method" : "GET",
"name" : "x-my-token"
},
"properties": "{\n\t\"description\" : \"A custom token used to authorization the method invocation.\"\n}"
}
```
Se con esito positivo, l'operazione restituisce una risposta `201 Created` contenente la nuova istanza `DocumentationPart` creata nel payload. Ad esempio:
```
{
"_links": {
"curies": {
"href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html",
"name": "documentationpart",
"templated": true
},
"self": {
"href": "/restapis/4wk1k4onj3/documentation/parts/h0m3uf"
},
"documentationpart:delete": {
"href": "/restapis/4wk1k4onj3/documentation/parts/h0m3uf"
},
"documentationpart:update": {
"href": "/restapis/4wk1k4onj3/documentation/parts/h0m3uf"
}
},
"id": "h0m3uf",
"location": {
"path": "/pets",
"method": "GET",
"name": "x-my-token",
"statusCode": null,
"type": "REQUEST_HEADER"
},
"properties": "{\n\t\"description\" : \"A custom token used to authorization the method invocation.\"\n}"
}
```
## Documentare un'entità `RESPONSE`
Per aggiungere la documentazione per una risposta a un codice di stato, aggiungi una [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)risorsa destinata alla risorsa corrispondente [MethodResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html).
```
POST /restapis/restapi_id/documentation/parts HTTP/1.1
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
{
"location": {
"path": "/",
"method": "*",
"name": null,
"statusCode": "200",
"type": "RESPONSE"
},
"properties": "{\n \"description\" : \"Successful operation.\"\n}"
}
```
Se con esito positivo, l'operazione restituisce una risposta `201 Created` contenente la nuova istanza `DocumentationPart` creata nel payload. Ad esempio:
```
{
"_links": {
"self": {
"href": "/restapis/4wk1k4onj3/documentation/parts/lattew"
},
"documentationpart:delete": {
"href": "/restapis/4wk1k4onj3/documentation/parts/lattew"
},
"documentationpart:update": {
"href": "/restapis/4wk1k4onj3/documentation/parts/lattew"
}
},
"id": "lattew",
"location": {
"path": "/",
"method": "*",
"name": null,
"statusCode": "200",
"type": "RESPONSE"
},
"properties": "{\n \"description\" : \"Successful operation.\"\n}"
}
```
## Documentare un'entità `RESPONSE_HEADER`
Per aggiungere la documentazione per un'intestazione di risposta, aggiungi una [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)risorsa per l'intestazione della risposta.
```
POST /restapis/restapi_id/documentation/parts HTTP/1.1
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
"location": {
"path": "/",
"method": "GET",
"name": "Content-Type",
"statusCode": "200",
"type": "RESPONSE_HEADER"
},
"properties": "{\n \"description\" : \"Media type of request\"\n}"
```
Se con esito positivo, l'operazione restituisce una risposta `201 Created` contenente la nuova istanza `DocumentationPart` creata nel payload. Ad esempio:
```
{
"_links": {
"curies": {
"href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html",
"name": "documentationpart",
"templated": true
},
"self": {
"href": "/restapis/4wk1k4onj3/documentation/parts/fev7j7"
},
"documentationpart:delete": {
"href": "/restapis/4wk1k4onj3/documentation/parts/fev7j7"
},
"documentationpart:update": {
"href": "/restapis/4wk1k4onj3/documentation/parts/fev7j7"
}
},
"id": "fev7j7",
"location": {
"path": "/",
"method": "GET",
"name": "Content-Type",
"statusCode": "200",
"type": "RESPONSE_HEADER"
},
"properties": "{\n \"description\" : \"Media type of request\"\n}"
}
```
La documentazione di questa intestazione di risposta `Content-Type` è la documentazione predefinita per le intestazioni `Content-Type` di qualsiasi risposta dell'API.
## Documentare un'entità `AUTHORIZER`
Per aggiungere documentazione per un autorizzatore API, aggiungi una [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)risorsa destinata all'autorizzatore specificato.
```
POST /restapis/restapi_id/documentation/parts HTTP/1.1
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
{
"location" : {
"type" : "AUTHORIZER",
"name" : "myAuthorizer"
},
"properties": "{\n\t\"description\" : \"Authorizes invocations of configured methods.\"\n}"
}
```
Se con esito positivo, l'operazione restituisce una risposta `201 Created` contenente la nuova istanza `DocumentationPart` creata nel payload. Esempio:
```
{
"_links": {
"curies": {
"href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html",
"name": "documentationpart",
"templated": true
},
"self": {
"href": "/restapis/4wk1k4onj3/documentation/parts/pw3qw3"
},
"documentationpart:delete": {
"href": "/restapis/4wk1k4onj3/documentation/parts/pw3qw3"
},
"documentationpart:update": {
"href": "/restapis/4wk1k4onj3/documentation/parts/pw3qw3"
}
},
"id": "pw3qw3",
"location": {
"path": null,
"method": null,
"name": "myAuthorizer",
"statusCode": null,
"type": "AUTHORIZER"
},
"properties": "{\n\t\"description\" : \"Authorizes invocations of configured methods.\"\n}"
}
```
**Nota**
L'[DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)istanza di un'`AUTHORIZER`entità non può essere ereditata da nessuna delle sue risorse secondarie.
## Documentare un'entità `MODEL`
La documentazione di un'entità `MODEL` comporta la creazione e la gestione delle istanze di `DocumentPart` per il modello e gli elementi `properties` del modello. Ad esempio, per il modello `Error` fornito con ogni API per impostazione predefinita ha la seguente definizione dello schema:
```
{
"$schema" : "http://json-schema.org/draft-04/schema#",
"title" : "Error Schema",
"type" : "object",
"properties" : {
"message" : { "type" : "string" }
}
}
```
e richiede due istanze di `DocumentationPart`, una per `Model` e l'altra per la relativa proprietà `message`:
```
{
"location": {
"type": "MODEL",
"name": "Error"
},
"properties": {
"title": "Error Schema",
"description": "A description of the Error model"
}
}
```
e
```
{
"location": {
"type": "MODEL",
"name": "Error.message"
},
"properties": {
"description": "An error message."
}
}
```
Quando l'API viene esportata, le proprietà di `DocumentationPart` sostituiscono i valori dello schema originale.
Per aggiungere documentazione per un modello API, aggiungi una [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)risorsa destinata al modello specificato.
```
POST /restapis/restapi_id/documentation/parts HTTP/1.1
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
{
"location" : {
"type" : "MODEL",
"name" : "Pet"
},
"properties": "{\n\t\"description\" : \"Data structure of a Pet object.\"\n}"
}
```
Se con esito positivo, l'operazione restituisce una risposta `201 Created` contenente la nuova istanza `DocumentationPart` creata nel payload. Esempio:
```
{
"_links": {
"curies": {
"href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html",
"name": "documentationpart",
"templated": true
},
"self": {
"href": "/restapis/4wk1k4onj3/documentation/parts/lkn4uq"
},
"documentationpart:delete": {
"href": "/restapis/4wk1k4onj3/documentation/parts/lkn4uq"
},
"documentationpart:update": {
"href": "/restapis/4wk1k4onj3/documentation/parts/lkn4uq"
}
},
"id": "lkn4uq",
"location": {
"path": null,
"method": null,
"name": "Pet",
"statusCode": null,
"type": "MODEL"
},
"properties": "{\n\t\"description\" : \"Data structure of a Pet object.\"\n}"
}
```
Ripetete lo stesso passaggio per creare un' DocumentationPart istanza per una qualsiasi delle proprietà del modello.
**Nota**
L'[DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)istanza di un'`MODEL`entità non può essere ereditata da nessuna delle sue risorse secondarie.
## Aggiornare le parti della documentazione
Per aggiornare le parti della documentazione di qualsiasi tipo di entità API, invia una richiesta PATCH su un'[DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)istanza di un identificatore di parte specificato per sostituire la `properties` mappa esistente con una nuova.
```
PATCH /restapis/4wk1k4onj3/documentation/parts/part_id HTTP/1.1
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
{
"patchOperations" : [ {
"op" : "replace",
"path" : "RESOURCE_PATH",
"value" : "NEW_properties_VALUE_AS_JSON_STRING"
} ]
}
```
La risposta con esito positivo restituisce un codice di stato `200 OK` con un payload che include l'istanza `DocumentationPart` aggiornata nel payload.
Puoi aggiornare più parti della documentazione in una singola richiesta `PATCH`.
## Elencare le parti della documentazione
Per elencare le parti della documentazione di qualsiasi tipo di entità API, invia una richiesta GET su una [DocumentationParts](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)raccolta.
```
GET /restapis/restapi_id/documentation/parts HTTP/1.1
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
```
La risposta con esito positivo restituisce un codice di stato `200 OK` con un payload che include le istanze `DocumentationPart` disponibili nel payload.
# Pubblicare la documentazione dell'API utilizzando l'API REST di API Gateway
Per pubblicare la documentazione per un'API, crea, aggiorna o ottieni uno snapshot della documentazione, quindi associa lo snapshot della documentazione a una fase dell'API. Quando crei uno snapshot della documentazione, puoi anche contemporaneamente associarlo a una fase dell'API.
**Topics**
+ [Creare uno snapshot della documentazione e associarlo a una fase dell'API](#api-gateway-documenting-api-publishing-create-documentation-version-with-stage)
+ [Creare uno snapshot della documentazione](#api-gateway-documenting-api-publishing-create-documentation-version)
+ [Aggiornare uno snapshot della documentazione](#api-gateway-documenting-api-publishing-update-documentation-version)
+ [Ottenere uno snapshot della documentazione](#api-gateway-documenting-api-publishing-get-documentation-version)
+ [Associare uno snapshot della documentazione a una fase dell'API](#api-gateway-documenting-api-publishing-stage-association)
+ [Scaricare uno snapshot della documentazione associato a una fase](#api-gateway-documenting-api-publishing-export-documentation-version)
## Creare uno snapshot della documentazione e associarlo a una fase dell'API
Per creare uno snapshot delle parti della documentazione di un'API e associarlo contemporaneamente a una fase dell'API, invia la seguente richiesta `POST`:
```
POST /restapis/restapi_id/documentation/versions HTTP/1.1
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
{
"documentationVersion" : "1.0.0",
"stageName": "prod",
"description" : "My API Documentation v1.0.0"
}
```
Se con esito positivo, l'operazione restituisce una risposta `200 OK` contenente la nuova istanza `DocumentationVersion` creata come payload.
In alternativa, è possibile creare uno snapshot della documentazione senza associarlo prima a una fase dell'API e quindi chiamare [restapi:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateRestApi.html) per associare lo snapshot a una fase dell'API specificata. Puoi inoltre aggiornare o interrogare uno snapshot della documentazione esistente e quindi aggiornare la relativa associazione della fase. Le fasi vengono illustrate nelle prossime quattro sezioni.
## Creare uno snapshot della documentazione
Per creare un'istantanea delle parti della documentazione di un'API, crea una nuova [DocumentationVersion](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html)risorsa e aggiungila alla [DocumentationVersions](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html)raccolta dell'API:
```
POST /restapis/restapi_id/documentation/versions HTTP/1.1
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
{
"documentationVersion" : "1.0.0",
"description" : "My API Documentation v1.0.0"
}
```
Se con esito positivo, l'operazione restituisce una risposta `200 OK` contenente la nuova istanza `DocumentationVersion` creata come payload.
## Aggiornare uno snapshot della documentazione
È possibile aggiornare un'istantanea della documentazione solo modificando la `description` proprietà della risorsa corrispondente. [DocumentationVersion](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html) L'esempio seguente mostra come aggiornare la descrizione dello snapshot della documentazione come identificata dal relativo identificatore di versione, `version`, ad esempio `1.0.0`.
```
PATCH /restapis/restapi_id/documentation/versions/version HTTP/1.1
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
{
"patchOperations": [{
"op": "replace",
"path": "/description",
"value": "My API for testing purposes."
}]
}
```
Se con esito positivo, l'operazione restituisce una risposta `200 OK` contenente l'istanza `DocumentationVersion` aggiornata come payload.
## Ottenere uno snapshot della documentazione
Per ottenere un'istantanea della documentazione, invia una `GET` richiesta relativa alla risorsa specificata. [DocumentationVersion](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html) L'esempio seguente mostra come ottenere uno snapshot della documentazione di un dato identificatore di versione, 1.0.0.
```
GET /restapis//documentation/versions/1.0.0 HTTP/1.1
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
```
## Associare uno snapshot della documentazione a una fase dell'API
Per pubblicare la documentazione dell'API, associa uno snapshot della documentazione a una fase dell'API. Devi aver già creato la fase dell'API prima di associare la versione della documentazione alla fase.
Per associare uno snapshot della documentazione a una fase dell'API utilizzando l'[API REST di API Gateway](https://docs.aws.amazon.com/apigateway/latest/api/), esegui l'operazione [stage:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateStage.html) per impostare a versione della documentazione desiderata sulla proprietà `stage.documentationVersion`:
```
PATCH /restapis/RESTAPI_ID/stages/STAGE_NAME
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
{
"patchOperations": [{
"op": "replace",
"path": "/documentationVersion",
"value": "VERSION_IDENTIFIER"
}]
}
```
## Scaricare uno snapshot della documentazione associato a una fase
Dopo aver associato una versione delle parti della documentazione a uno stage, è possibile esportare le parti della documentazione insieme alle definizioni delle entità API, in un file esterno, utilizzando la console API Gateway, l'API REST API Gateway, una delle sue SDKs, o il AWS CLI for API Gateway. Il processo è uguale a quello utilizzato per esportare l'API. Il formato del file esportato può essere JSON o YAML.
Utilizzando l'API REST di API Gateway, puoi anche impostare esplicitamente il parametro di query `extension=documentation,integrations,authorizers` per includere le parti della documentazione dell'API, le integrazioni API e le autorizzazioni in un'esportazione API. Per impostazione predefinita, le parti della documentazione sono incluse, ma le integrazioni e le autorizzazioni sono escluse quando si esporta un'API. L'output predefinito di un'esportazione API è adatto per la distribuzione della documentazione.
Per esportare la documentazione dell'API in un file OpenAPI JSON esterno usando l'API REST di API Gateway, inviare la seguente richiesta `GET`:
```
GET /restapis/restapi_id/stages/stage_name/exports/swagger?extensions=documentation HTTP/1.1
Accept: application/json
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
```
Qui, l'oggetto `x-amazon-apigateway-documentation` contiene le parti della documentazione e la definizione dell'entità API contiene le proprietà della documentazione supportate da OpenAPI. L'output non include dettagli sull'integrazione o sulle autorizzazioni Lambda (note in precedenza come autorizzazioni ad hoc). Per includere entrambi i dettagli, imposta `extensions=integrations,authorizers,documentation`. Per includere i dettagli delle integrazioni ma non delle autorizzazioni, imposta `extensions=integrations,documentation`.
Imposta l'intestazione `Accept:application/json` nella richiesta per inserire l'output del risultato in un file JSON. Per produrre l'output YAML, imposta l'intestazione della richiesta su `Accept:application/yaml`.
Ad esempio, esamineremo un'API che espone un semplice metodo `GET` sulla risorsa radice (`/`). Questa API ha quattro entità API definite in un file di definizione OpenAPI, uno per ciascuno dei tipi `API`, `MODEL`, `METHOD` e `RESPONSE`. Una parte della documentazione è stata aggiunta a ciascuna delle entità `API`, `METHOD` e `RESPONSE`. Chiamando il precedente comando di esportazione della documentazione, otteniamo il seguente output, con le parti della documentazione elencate nell'oggetto `x-amazon-apigateway-documentation` come estensione di un file OpenAPI standard.
------
#### [ OpenAPI 3.0 ]
```
{
"openapi": "3.0.0",
"info": {
"description": "API info description",
"version": "2016-11-22T22:39:14Z",
"title": "doc",
"x-bar": "API info x-bar"
},
"paths": {
"/": {
"get": {
"description": "Method description.",
"responses": {
"200": {
"description": "200 response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Empty"
}
}
}
}
},
"x-example": "x- Method example"
},
"x-bar": "resource x-bar"
}
},
"x-amazon-apigateway-documentation": {
"version": "1.0.0",
"createdDate": "2016-11-22T22:41:40Z",
"documentationParts": [
{
"location": {
"type": "API"
},
"properties": {
"description": "API description",
"foo": "API foo",
"x-bar": "API x-bar",
"info": {
"description": "API info description",
"version": "API info version",
"foo": "API info foo",
"x-bar": "API info x-bar"
}
}
},
{
"location": {
"type": "METHOD",
"method": "GET"
},
"properties": {
"description": "Method description.",
"x-example": "x- Method example",
"foo": "Method foo",
"info": {
"version": "method info version",
"description": "method info description",
"foo": "method info foo"
}
}
},
{
"location": {
"type": "RESOURCE"
},
"properties": {
"description": "resource description",
"foo": "resource foo",
"x-bar": "resource x-bar",
"info": {
"description": "resource info description",
"version": "resource info version",
"foo": "resource info foo",
"x-bar": "resource info x-bar"
}
}
}
]
},
"x-bar": "API x-bar",
"servers": [
{
"url": "https://rznaap68yi.execute-api.ap-southeast-1.amazonaws.com/{basePath}",
"variables": {
"basePath": {
"default": "/test"
}
}
}
],
"components": {
"schemas": {
"Empty": {
"type": "object",
"title": "Empty Schema"
}
}
}
}
```
------
#### [ OpenAPI 2.0 ]
```
{
"swagger" : "2.0",
"info" : {
"description" : "API info description",
"version" : "2016-11-22T22:39:14Z",
"title" : "doc",
"x-bar" : "API info x-bar"
},
"host" : "rznaap68yi.execute-api.ap-southeast-1.amazonaws.com",
"basePath" : "/test",
"schemes" : [ "https" ],
"paths" : {
"/" : {
"get" : {
"description" : "Method description.",
"produces" : [ "application/json" ],
"responses" : {
"200" : {
"description" : "200 response",
"schema" : {
"$ref" : "#/definitions/Empty"
}
}
},
"x-example" : "x- Method example"
},
"x-bar" : "resource x-bar"
}
},
"definitions" : {
"Empty" : {
"type" : "object",
"title" : "Empty Schema"
}
},
"x-amazon-apigateway-documentation" : {
"version" : "1.0.0",
"createdDate" : "2016-11-22T22:41:40Z",
"documentationParts" : [ {
"location" : {
"type" : "API"
},
"properties" : {
"description" : "API description",
"foo" : "API foo",
"x-bar" : "API x-bar",
"info" : {
"description" : "API info description",
"version" : "API info version",
"foo" : "API info foo",
"x-bar" : "API info x-bar"
}
}
}, {
"location" : {
"type" : "METHOD",
"method" : "GET"
},
"properties" : {
"description" : "Method description.",
"x-example" : "x- Method example",
"foo" : "Method foo",
"info" : {
"version" : "method info version",
"description" : "method info description",
"foo" : "method info foo"
}
}
}, {
"location" : {
"type" : "RESOURCE"
},
"properties" : {
"description" : "resource description",
"foo" : "resource foo",
"x-bar" : "resource x-bar",
"info" : {
"description" : "resource info description",
"version" : "resource info version",
"foo" : "resource info foo",
"x-bar" : "resource info x-bar"
}
}
} ]
},
"x-bar" : "API x-bar"
}
```
------
Per un attributo conforme a OpenAPI definito nella mappa di `properties` di una parte della documentazione, API Gateway inserisce l'attributo nella definizione dell'entità API associata. Un attributo di `x-something` è un'estensione OpenAPI standard. Questa estensione viene propagata nella definizione dell'entità API. Ad esempio, consulta l'attributo `x-example` per il metodo `GET`. Un attributo come `foo` non fa parte delle specifiche OpenAPI e non viene inserito nelle definizioni delle entità API associate.
Se uno strumento di rendering della documentazione (ad esempio [OpenAPI UI](https://swagger.io/tools/swagger-ui/)) analizza le definizioni dell'entità API per estrarre gli attributi della documentazione, qualsiasi attributo `properties` non conforme a OpenAPI di un'istanza di `DocumentationPart` non è disponibile per lo strumento. Tuttavia, se uno strumento di rendering della documentazione analizza l'oggetto `x-amazon-apigateway-documentation` per ottenere i contenuti o se lo strumento chiama [restapi:documentation-parts](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) e [documenationpart:by-id](https://docs.aws.amazon.com/apigateway/latest/api/API_GetDocumentationPart.html) per recuperare le parti della documentazione da API Gateway, tutti gli attributi della documentazione sono disponibili per la visualizzazione con lo strumento.
Per esportare la documentazione con definizioni di entità API contenenti i dettagli delle integrazioni in un file OpenAPI JSON, inviare la seguente richiesta `GET`:
```
GET /restapis/restapi_id/stages/stage_name/exports/swagger?extensions=integrations,documentation HTTP/1.1
Accept: application/json
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
```
Per esportare la documentazione con definizioni di entità API contenenti dettagli delle integrazioni e delle autorizzazioni in un file OpenAPI YAML, inviare la seguente richiesta `GET`:
```
GET /restapis/restapi_id/stages/stage_name/exports/swagger?extensions=integrations,authorizers,documentation HTTP/1.1
Accept: application/yaml
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
```
Per usare la console API Gateway per esportare e scaricare la documentazione pubblicata di un'API, segui le istruzioni in [Esportazione di un'API REST tramite la console API Gateway](api-gateway-export-api.md#api-gateway-export-api-from-console).
# Importare la documentazione dell'API
Come con l'importazione delle definizioni di entità API, puoi importare le parti della documentazione da un file OpenAPI esterno in un'API di API Gateway. Specificate le parti della to-be-imported documentazione all'interno dell'[x-amazon-apigateway-documentation oggetto](api-gateway-swagger-extensions-documentation.md)estensione in un file di definizione OpenAPI valido. L'importazione della documentazione non modifica le definizioni delle entità API esistenti.
Esiste la possibilità di unire le parti della documentazione appena specificate in parti della documentazione esistenti in API Gateway o per sovrascrivere le parti della documentazione esistenti. Nella modalità `MERGE`, una nuova parte della documentazione definita nel file OpenAPI viene aggiunta alla raccolta `DocumentationParts` dell'API. Se un elemento `DocumentationPart` importato esiste già, un attributo importato sostituisce quello esistente se i due sono diversi. Altri attributi della documentazione esistenti rimangono inalterati. Nella modalità `OVERWRITE`, l'intera raccolta `DocumentationParts` viene sostituita in base al file di definizione OpenAPI importato.
## Importazione delle parti della documentazione tramite l'API REST di API Gateway
Per importare la documentazione dell'API usando l'API REST di API Gateway, esegui l'operazione [documentationpart:import](https://docs.aws.amazon.com/apigateway/latest/api/API_ImportDocumentationParts.html). L'esempio seguente mostra come sovrascrivere parti della documentazione esistenti di un'API con un singolo metodo `GET / `, restituendo una risposta `200 OK` per l'esito positivo.
------
#### [ OpenAPI 3.0 ]
```
PUT /restapis//documentation/parts&mode=overwrite&failonwarnings=true
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
{
"openapi": "3.0.0",
"info": {
"description": "description",
"version": "1",
"title": "doc"
},
"paths": {
"/": {
"get": {
"description": "Method description.",
"responses": {
"200": {
"description": "200 response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Empty"
}
}
}
}
}
}
}
},
"x-amazon-apigateway-documentation": {
"version": "1.0.3",
"documentationParts": [
{
"location": {
"type": "API"
},
"properties": {
"description": "API description",
"info": {
"description": "API info description 4",
"version": "API info version 3"
}
}
},
{
"location": {
"type": "METHOD",
"method": "GET"
},
"properties": {
"description": "Method description."
}
},
{
"location": {
"type": "MODEL",
"name": "Empty"
},
"properties": {
"title": "Empty Schema"
}
},
{
"location": {
"type": "RESPONSE",
"method": "GET",
"statusCode": "200"
},
"properties": {
"description": "200 response"
}
}
]
},
"servers": [
{
"url": "/"
}
],
"components": {
"schemas": {
"Empty": {
"type": "object",
"title": "Empty Schema"
}
}
}
}
```
------
#### [ OpenAPI 2.0 ]
```
PUT /restapis//documentation/parts&mode=overwrite&failonwarnings=true
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
{
"swagger": "2.0",
"info": {
"description": "description",
"version": "1",
"title": "doc"
},
"host": "",
"basePath": "/",
"schemes": [
"https"
],
"paths": {
"/": {
"get": {
"description": "Method description.",
"produces": [
"application/json"
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Empty"
}
}
}
}
}
},
"definitions": {
"Empty": {
"type": "object",
"title": "Empty Schema"
}
},
"x-amazon-apigateway-documentation": {
"version": "1.0.3",
"documentationParts": [
{
"location": {
"type": "API"
},
"properties": {
"description": "API description",
"info": {
"description": "API info description 4",
"version": "API info version 3"
}
}
},
{
"location": {
"type": "METHOD",
"method": "GET"
},
"properties": {
"description": "Method description."
}
},
{
"location": {
"type": "MODEL",
"name": "Empty"
},
"properties": {
"title": "Empty Schema"
}
},
{
"location": {
"type": "RESPONSE",
"method": "GET",
"statusCode": "200"
},
"properties": {
"description": "200 response"
}
}
]
}
}
```
------
In caso di esito positivo, questa richiesta restituisce una risposta 200 OK contenente l'elemento `DocumentationPartId` importato nel payload.
```
{
"ids": [
"kg3mth",
"796rtf",
"zhek4p",
"5ukm9s"
]
}
```
Inoltre, è possibile anche invocare [restapi:import](https://docs.aws.amazon.com/apigateway/latest/api/API_ImportRestApi.html) o [restapi:put](https://docs.aws.amazon.com/apigateway/latest/api/API_PutRestApi.html), fornendo le parti della documentazione nell'oggetto `x-amazon-apigateway-documentation` come parte del file OpenAPI di input della definizione dell'API. Per escludere le parti della documentazione dall'importazione dell'API, imposta `ignore=documentation` nei parametri di query della richiesta.
## Importazione di parti di documentazione tramite la console API Gateway
Le seguenti istruzioni descrivono come importare le parti della documentazione.
**Per utilizzare la console per importare le parti della documentazione di un'API da un file esterno**
1. Nel riquadro di navigazione principale scegli **Documentazione**.
1. Scegli **Importa**.
1. Se è disponibile la documentazione esistente, seleziona **Sovrascrivi** o **Unisci** per la nuova documentazione.
1. Seleziona **Scegli il file** per caricare un file da un'unità oppure immettere il contenuto di un file nella vista del file. Per un esempio, consulta il payload della richiesta di esempio in [Importazione delle parti della documentazione tramite l'API REST di API Gateway](#api-gateway-importing-api-with-swagger-file-using-rest-api).
1. Scegli in che modo gestire gli avvisi durante l'importazione. Seleziona **Avvisi di errore** o **Ignora avvisi**. Per ulteriori informazioni, consulta [Errori e avvisi relativi all'importazione dell'API in Gateway API](api-gateway-import-api-errors-warnings.md).
1. Scegli **Importa**.
# Controllo dell'accesso alla documentazione dell'API in Gateway API
Se hai un team dedicato alla documentazione per scrivere e modificare la documentazione dell'API, puoi configurare autorizzazioni di accesso separate per i tuoi sviluppatori (per lo sviluppo dell'API) e per i tuoi scrittori o editori (per lo sviluppo del contenuto). Questo è particolarmente appropriato quando un fornitore di terze parti è coinvolto nella creazione della documentazione.
Per concedere al tuo team di documentazione l'accesso per creare, aggiornare e pubblicare la documentazione dell'API, puoi assegnare al team di documentazione un ruolo IAM con la seguente politica IAM, dove si *account\$1id* trova l'ID AWS account del tuo team di documentazione.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "StmtDocPartsAddEditViewDelete",
"Effect": "Allow",
"Action": [
"apigateway:GET",
"apigateway:PUT",
"apigateway:POST",
"apigateway:PATCH",
"apigateway:DELETE"
],
"Resource": [
"arn:aws:apigateway:us-east-1:111111111111:/restapis/*/documentation/*"
]
}
]
}
```
------
Per informazioni sull'impostazione delle autorizzazioni per accedere alle risorse di API Gateway, consultare [Come funziona Amazon API Gateway con IAM](security_iam_service-with-iam.md).
# Genera SDKs per REST APIs in API Gateway
Per chiamare la tua API REST in un modo specifico per la piattaforma o la lingua, devi generare l'SDK specifico della piattaforma o della lingua dell'API. Si genera l'SDK dopo aver creato, testato e implementato l'API in una fase. Attualmente, API Gateway supporta la generazione di un SDK per un'API in Java, Java per Android JavaScript, Objective-C o Swift per iOS e Ruby.
In questa sezione viene descritto come generare un SDK di un'API di API Gateway. Dimostra inoltre come utilizzare l'SDK generato in un'app Java, un'app Java per Android, Objective-C e Swift per app iOS e un'app. JavaScript
Per facilitare la discussione, usiamo questa [API](simple-calc-lambda-api.md) di API Gateway, che espone questa funzione Lambda [calcolatore semplice](simple-calc-nodejs-lambda-function.md).
Prima di procedere, crea o importa l'API e distribuiscila almeno una volta in API Gateway. Per istruzioni, consulta [Implementazione di REST API in Gateway API](how-to-deploy-api.md).
**Topics**
+ [Funzione Lambda del calcolatore semplice](simple-calc-nodejs-lambda-function.md)
+ [API calcolatore semplice in API Gateway](simple-calc-lambda-api.md)
+ [Definizione OpenAPI dell'API del calcolatore semplice](simple-calc-lambda-api-swagger-definition.md)
+ [Generazione dell'SDK Java di un'API in Gateway API](generate-java-sdk-of-an-api.md)
+ [Generazione dell'SDK Android di un'API in Gateway API](generate-android-sdk-of-an-api.md)
+ [Generazione dell'SDK iOS di un'API in Gateway API](generate-ios-sdk-of-an-api.md)
+ [Genera l' JavaScript SDK di un'API REST in API Gateway](generate-javascript-sdk-of-an-api.md)
+ [Generazione dell'SDK Ruby di un'API in Gateway API](generate-ruby-sdk-of-an-api.md)
+ [Generazione SDKs per un'API utilizzando AWS CLI i comandi in API Gateway](how-to-generate-sdk-cli.md)
# Funzione Lambda del calcolatore semplice
A scopi illustrativi, verrà utilizzata una funzione Lambda in Node.js che esegue le operazioni binarie di addizione, sottrazione, moltiplicazione e divisione.
**Topics**
+ [Formato di input della funzione Lambda del calcolatore semplice](#simple-calc-lambda-function-input-format)
+ [Formato di output della funzione Lambda del calcolatore semplice](#simple-calc-lambda-function-output-format)
+ [Implementazione della funzione Lambda del calcolatore semplice](#simple-calc-lambda-function-implementation)
## Formato di input della funzione Lambda del calcolatore semplice
Questa funzione riceve un input nel formato seguente:
```
{ "a": "Number", "b": "Number", "op": "string"}
```
dove `op` può essere un valore `(+, -, *, /, add, sub, mul, div)` qualsiasi.
## Formato di output della funzione Lambda del calcolatore semplice
Quando un'operazione ha esito positivo, restituisce il risultato nel formato seguente:
```
{ "a": "Number", "b": "Number", "op": "string", "c": "Number"}
```
dove `c` contiene il risultato del calcolo.
## Implementazione della funzione Lambda del calcolatore semplice
L'implementazione della funzione Lambda è la seguente:
```
export const handler = async function (event, context) {
console.log("Received event:", JSON.stringify(event));
if (
event.a === undefined ||
event.b === undefined ||
event.op === undefined
) {
return "400 Invalid Input";
}
const res = {};
res.a = Number(event.a);
res.b = Number(event.b);
res.op = event.op;
if (isNaN(event.a) || isNaN(event.b)) {
return "400 Invalid Operand";
}
switch (event.op) {
case "+":
case "add":
res.c = res.a + res.b;
break;
case "-":
case "sub":
res.c = res.a - res.b;
break;
case "*":
case "mul":
res.c = res.a * res.b;
break;
case "/":
case "div":
if (res.b == 0) {
return "400 Divide by Zero";
} else {
res.c = res.a / res.b;
}
break;
default:
return "400 Invalid Operator";
}
return res;
};
```
# API calcolatore semplice in API Gateway
L'API calcolatore semplice espone tre metodi (GET, POST, GET) per richiamare la [Funzione Lambda del calcolatore semplice](simple-calc-nodejs-lambda-function.md). Di seguito è illustrata una rappresentazione grafica di quest'API:
![\[API calcolatore semplice per l'SDK generato\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/simple-calc-api-console-hierarchy-new-console.png)
Questi tre metodi mostrano modi diversi per fornire l'input per la funzione Lambda di back-end per eseguire la stessa operazione:
+ Il metodo `GET /?a=...&b=...&op=...` usa i parametri di query per specificare l'input.
+ Il metodo `POST /` usa un payload JSON `{"a":"Number", "b":"Number", "op":"string"}` per specificare l'input.
+ Il metodo `GET /{a}/{b}/{op}` usa i parametri di percorso per specificare l'input.
Se non è definito, API Gateway genera il nome del metodo SDK corrispondente combinando le parti relative al metodo HTTP e al percorso. La parte del percorso root (`/`) è detta `Api Root`. Ad esempio, il nome del metodo SDK Java predefinito per il metodo API `GET /?a=...&b=...&op=...` è `getABOp`, il nome del metodo SDK predefinito per `POST /` è `postApiRoot` e il nome del metodo SDK predefinito per `GET /{a}/{b}/{op}` è `getABOp`. L'individuo SDKs può personalizzare la convenzione. Consulta la documentazione dell'origine dell'SDK generato per informazioni sui nomi di metodi SDK specifici.
È possibile e consigliabile sostituire i nomi dei metodi SDK predefiniti specificando la proprietà [operationName](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html#operationName) in ogni metodo API. Questa operazione viene eseguita durante la [creazione del metodo API](https://docs.aws.amazon.com/apigateway/latest/api/API_PutMethod.html) o l'[aggiornamento del metodo API](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateMethod.html) con l'API REST di API Gateway. Nella definizione Swagger dell'API è possibile impostare `operationId` per ottenere lo stesso risultato.
Prima di illustrare come invocare questi metodi usando un SDK generato da API Gateway per questa API, esaminiamo brevemente come eseguire la configurazione. Per istruzioni dettagliate, consulta [Sviluppa REST APIs in API Gateway](rest-api-develop.md). Se non hai mai usato API Gateway, consulta prima [Scegli un tutorial di integrazione AWS Lambda](getting-started-with-lambda-integration.md).
## Creazione di modelli per l'input e l'output
Per specificare un input fortemente tipizzato nell'SDK, creiamo un modello `Input` per l'API. Per descrivere il tipo di dati del corpo della risposta, creiamo un modello `Output` e un modello `Result`.
**Per creare i modelli per l'input, l'output e il risultato**
1. Nel riquadro di navigazione principale seleziona **Modelli**.
1. Scegli **Crea modello**.
1. In **Nome**, inserisci **input**.
1. Per **Tipo di contenuto** inserisci **application/json**.
Se non viene trovato alcun tipo di contenuto corrispondente, la convalida della richiesta non viene eseguita. Per utilizzare lo stesso modello indipendentemente dal tipo di contenuti, inserisci **\$1default**.
1. Per **Schema modello** immetti il seguente modello:
```
{
"$schema" : "$schema": "http://json-schema.org/draft-04/schema#",
"type":"object",
"properties":{
"a":{"type":"number"},
"b":{"type":"number"},
"op":{"type":"string"}
},
"title":"Input"
}
```
1. Scegli **Crea modello**.
1. Ripeti le seguenti fasi per creare un modello `Output` e un modello `Result`.
Per il modello `Output` immetti in **Schema modello** quanto segue:
```
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"c": {"type":"number"}
},
"title": "Output"
}
```
Per il modello `Result` immetti in **Schema modello** quanto segue. Sostituisci l'ID API `abc123` con il tuo ID API.
```
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type":"object",
"properties":{
"input":{
"$ref":"https://apigateway.amazonaws.com/restapis/abc123/models/Input"
},
"output":{
"$ref":"https://apigateway.amazonaws.com/restapis/abc123/models/Output"
}
},
"title":"Result"
}
```
## Configurazione dei parametri di query del metodo GET /
Per il metodo `GET /?a=..&b=..&op=..`, i parametri di query sono dichiarati in **Method Request (Richiesta metodo)**:
**Per configurare i parametri della stringa di query GET/URL**
1. Nella sezione **Richiesta metodo** scegli **Modifica** per il metodo `GET` sulla risorsa root (`/`).
1. Scegli **Parametri della stringa di query URL** ed effettua le seguenti operazioni:
1. Scegliere **Add query string (Aggiungi stringa di query)**.
1. In **Nome**, inserisci **a**.
1. Mantieni **Obbligatorio** e **Caching** disattivati.
1. Mantieni disattivata l'opzione **Caching**.
Ripeti le stesse fasi e crea una stringa di query denominata **b** e una stringa di query denominata **op**.
1. Scegli **Save** (Salva).
## Configurazione del modello di dati per il payload come input nel back-end
Per il metodo `POST /`, creiamo il modello `Input` e lo aggiungiamo alla richiesta del metodo per definire la forma dei dati di input.
**Per configurare il modello di dati per il payload come input nel back-end**
1. Nella sezione **Richiesta metodo** scegli **Modifica** per il metodo `POST` sulla risorsa root (`/`).
1. Scegli **Corpo della richiesta**.
1. Scegliere **Add model (Aggiungi modello)**.
1. Per **Tipo di contenuto** inserisci **application/json**.
1. Per **Modello** seleziona **Input**.
1. Scegli **Save** (Salva).
Con questo modello, i clienti dell'API possono chiamare l'SDK per specificare l'input creando un'istanza di un oggetto `Input`. Senza questo modello, i clienti dovrebbero creare un oggetto dizionario per rappresentare l'input JSON per la funzione Lambda.
## Configurazione del modello di dati per l'output del risultato dal back-end
Per tutti e tre i metodi, creiamo il modello `Result` e lo aggiungiamo in `Method Response` per il metodo per definire la forma dell'output restituito dalla funzione Lambda.
**Per configurare il modello di dati per l'output del risultato dal back-end**
1. Seleziona la risorsa **/\$1a\$1/\$1b\$1/\$1op\$1**, quindi scegli il metodo **GET**.
1. Nella scheda **Risposta metodo** scegli **Modifica** in **Risposta 200**.
1. In **Corpo della risposta** scegli **Aggiungi modello**.
1. Per **Tipo di contenuto** inserisci **application/json**.
1. Per **Modello** seleziona **Risultato**.
1. Scegli **Save** (Salva).
Con questo modello, i clienti dell'API possono analizzare un output con esito positivo leggendo le proprietà di un oggetto `Result`. Senza questo modello, i clienti dovrebbero creare un oggetto dizionario per rappresentare l'output JSON.
# Definizione OpenAPI dell'API del calcolatore semplice
Di seguito è riportata una definizione OpenAPI dell'API del calcolatore semplice. Puoi importarla nel tuo account. Tuttavia, dopo l'importazione, dovrai reimpostare le autorizzazioni basate su risorse per la [funzione Lambda](simple-calc-nodejs-lambda-function.md). A questo scopo, riseleziona la funzione Lambda creata nel tuo account da **Integration Request (Richiesta di integrazione)** nella console API Gateway. La console API Gateway reimposterà le autorizzazioni richieste. In alternativa, puoi utilizzare AWS Command Line Interface per il comando Lambda [add-permission](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html).
------
#### [ OpenAPI 2.0 ]
```
{
"swagger": "2.0",
"info": {
"version": "2016-09-29T20:27:30Z",
"title": "SimpleCalc"
},
"host": "t6dve4zn25.execute-api.us-west-2.amazonaws.com",
"basePath": "/demo",
"schemes": [
"https"
],
"paths": {
"/": {
"get": {
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"parameters": [
{
"name": "op",
"in": "query",
"required": false,
"type": "string"
},
{
"name": "a",
"in": "query",
"required": false,
"type": "string"
},
{
"name": "b",
"in": "query",
"required": false,
"type": "string"
}
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Result"
}
}
},
"x-amazon-apigateway-integration": {
"requestTemplates": {
"application/json": "#set($inputRoot = $input.path('$'))\n{\n \"a\" : $input.params('a'),\n \"b\" : $input.params('b'),\n \"op\" : \"$input.params('op')\"\n}"
},
"uri": "arn:aws:apigateway:us-west-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-west-2:123456789012:function:Calc/invocations",
"passthroughBehavior": "when_no_templates",
"httpMethod": "POST",
"responses": {
"default": {
"statusCode": "200",
"responseTemplates": {
"application/json": "#set($inputRoot = $input.path('$'))\n{\n \"input\" : {\n \"a\" : $inputRoot.a,\n \"b\" : $inputRoot.b,\n \"op\" : \"$inputRoot.op\"\n },\n \"output\" : {\n \"c\" : $inputRoot.c\n }\n}"
}
}
},
"type": "aws"
}
},
"post": {
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"parameters": [
{
"in": "body",
"name": "Input",
"required": true,
"schema": {
"$ref": "#/definitions/Input"
}
}
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Result"
}
}
},
"x-amazon-apigateway-integration": {
"uri": "arn:aws:apigateway:us-west-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-west-2:123456789012:function:Calc/invocations",
"passthroughBehavior": "when_no_match",
"httpMethod": "POST",
"responses": {
"default": {
"statusCode": "200",
"responseTemplates": {
"application/json": "#set($inputRoot = $input.path('$'))\n{\n \"input\" : {\n \"a\" : $inputRoot.a,\n \"b\" : $inputRoot.b,\n \"op\" : \"$inputRoot.op\"\n },\n \"output\" : {\n \"c\" : $inputRoot.c\n }\n}"
}
}
},
"type": "aws"
}
}
},
"/{a}": {
"x-amazon-apigateway-any-method": {
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"parameters": [
{
"name": "a",
"in": "path",
"required": true,
"type": "string"
}
],
"responses": {
"404": {
"description": "404 response"
}
},
"x-amazon-apigateway-integration": {
"requestTemplates": {
"application/json": "{\"statusCode\": 200}"
},
"passthroughBehavior": "when_no_match",
"responses": {
"default": {
"statusCode": "404",
"responseTemplates": {
"application/json": "{ \"Message\" : \"Can't $context.httpMethod $context.resourcePath\" }"
}
}
},
"type": "mock"
}
}
},
"/{a}/{b}": {
"x-amazon-apigateway-any-method": {
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"parameters": [
{
"name": "a",
"in": "path",
"required": true,
"type": "string"
},
{
"name": "b",
"in": "path",
"required": true,
"type": "string"
}
],
"responses": {
"404": {
"description": "404 response"
}
},
"x-amazon-apigateway-integration": {
"requestTemplates": {
"application/json": "{\"statusCode\": 200}"
},
"passthroughBehavior": "when_no_match",
"responses": {
"default": {
"statusCode": "404",
"responseTemplates": {
"application/json": "{ \"Message\" : \"Can't $context.httpMethod $context.resourcePath\" }"
}
}
},
"type": "mock"
}
}
},
"/{a}/{b}/{op}": {
"get": {
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"parameters": [
{
"name": "a",
"in": "path",
"required": true,
"type": "string"
},
{
"name": "b",
"in": "path",
"required": true,
"type": "string"
},
{
"name": "op",
"in": "path",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Result"
}
}
},
"x-amazon-apigateway-integration": {
"requestTemplates": {
"application/json": "#set($inputRoot = $input.path('$'))\n{\n \"a\" : $input.params('a'),\n \"b\" : $input.params('b'),\n \"op\" : \"$input.params('op')\"\n}"
},
"uri": "arn:aws:apigateway:us-west-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-west-2:123456789012:function:Calc/invocations",
"passthroughBehavior": "when_no_templates",
"httpMethod": "POST",
"responses": {
"default": {
"statusCode": "200",
"responseTemplates": {
"application/json": "#set($inputRoot = $input.path('$'))\n{\n \"input\" : {\n \"a\" : $inputRoot.a,\n \"b\" : $inputRoot.b,\n \"op\" : \"$inputRoot.op\"\n },\n \"output\" : {\n \"c\" : $inputRoot.c\n }\n}"
}
}
},
"type": "aws"
}
}
}
},
"definitions": {
"Input": {
"type": "object",
"properties": {
"a": {
"type": "number"
},
"b": {
"type": "number"
},
"op": {
"type": "string"
}
},
"title": "Input"
},
"Output": {
"type": "object",
"properties": {
"c": {
"type": "number"
}
},
"title": "Output"
},
"Result": {
"type": "object",
"properties": {
"input": {
"$ref": "#/definitions/Input"
},
"output": {
"$ref": "#/definitions/Output"
}
},
"title": "Result"
}
}
}
```
------
#### [ OpenAPI 3.0 ]
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "SimpleCalc",
"version" : "2016-09-29T20:27:30Z"
},
"servers" : [ {
"url" : "https://t6dve4zn25.execute-api.us-west-2.amazonaws.com/{basePath}",
"variables" : {
"basePath" : {
"default" : "demo"
}
}
} ],
"paths" : {
"/{a}/{b}" : {
"x-amazon-apigateway-any-method" : {
"parameters" : [ {
"name" : "a",
"in" : "path",
"required" : true,
"schema" : {
"type" : "string"
}
}, {
"name" : "b",
"in" : "path",
"required" : true,
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"404" : {
"description" : "404 response",
"content" : { }
}
},
"x-amazon-apigateway-integration" : {
"type" : "mock",
"responses" : {
"default" : {
"statusCode" : "404",
"responseTemplates" : {
"application/json" : "{ \"Message\" : \"Can't $context.httpMethod $context.resourcePath\" }"
}
}
},
"requestTemplates" : {
"application/json" : "{\"statusCode\": 200}"
},
"passthroughBehavior" : "when_no_match"
}
}
},
"/{a}/{b}/{op}" : {
"get" : {
"parameters" : [ {
"name" : "a",
"in" : "path",
"required" : true,
"schema" : {
"type" : "string"
}
}, {
"name" : "b",
"in" : "path",
"required" : true,
"schema" : {
"type" : "string"
}
}, {
"name" : "op",
"in" : "path",
"required" : true,
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"200" : {
"description" : "200 response",
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/Result"
}
}
}
}
},
"x-amazon-apigateway-integration" : {
"type" : "aws",
"httpMethod" : "POST",
"uri" : "arn:aws:apigateway:us-west-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-west-2:111122223333:function:Calc/invocations",
"responses" : {
"default" : {
"statusCode" : "200",
"responseTemplates" : {
"application/json" : "#set($inputRoot = $input.path('$'))\n{\n \"input\" : {\n \"a\" : $inputRoot.a,\n \"b\" : $inputRoot.b,\n \"op\" : \"$inputRoot.op\"\n },\n \"output\" : {\n \"c\" : $inputRoot.c\n }\n}"
}
}
},
"requestTemplates" : {
"application/json" : "#set($inputRoot = $input.path('$'))\n{\n \"a\" : $input.params('a'),\n \"b\" : $input.params('b'),\n \"op\" : \"$input.params('op')\"\n}"
},
"passthroughBehavior" : "when_no_templates"
}
}
},
"/" : {
"get" : {
"parameters" : [ {
"name" : "op",
"in" : "query",
"schema" : {
"type" : "string"
}
}, {
"name" : "a",
"in" : "query",
"schema" : {
"type" : "string"
}
}, {
"name" : "b",
"in" : "query",
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"200" : {
"description" : "200 response",
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/Result"
}
}
}
}
},
"x-amazon-apigateway-integration" : {
"type" : "aws",
"httpMethod" : "POST",
"uri" : "arn:aws:apigateway:us-west-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-west-2:111122223333:function:Calc/invocations",
"responses" : {
"default" : {
"statusCode" : "200",
"responseTemplates" : {
"application/json" : "#set($inputRoot = $input.path('$'))\n{\n \"input\" : {\n \"a\" : $inputRoot.a,\n \"b\" : $inputRoot.b,\n \"op\" : \"$inputRoot.op\"\n },\n \"output\" : {\n \"c\" : $inputRoot.c\n }\n}"
}
}
},
"requestTemplates" : {
"application/json" : "#set($inputRoot = $input.path('$'))\n{\n \"a\" : $input.params('a'),\n \"b\" : $input.params('b'),\n \"op\" : \"$input.params('op')\"\n}"
},
"passthroughBehavior" : "when_no_templates"
}
},
"post" : {
"requestBody" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/Input"
}
}
},
"required" : true
},
"responses" : {
"200" : {
"description" : "200 response",
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/Result"
}
}
}
}
},
"x-amazon-apigateway-integration" : {
"type" : "aws",
"httpMethod" : "POST",
"uri" : "arn:aws:apigateway:us-west-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-west-2:111122223333:function:Calc/invocations",
"responses" : {
"default" : {
"statusCode" : "200",
"responseTemplates" : {
"application/json" : "#set($inputRoot = $input.path('$'))\n{\n \"input\" : {\n \"a\" : $inputRoot.a,\n \"b\" : $inputRoot.b,\n \"op\" : \"$inputRoot.op\"\n },\n \"output\" : {\n \"c\" : $inputRoot.c\n }\n}"
}
}
},
"passthroughBehavior" : "when_no_match"
}
}
},
"/{a}" : {
"x-amazon-apigateway-any-method" : {
"parameters" : [ {
"name" : "a",
"in" : "path",
"required" : true,
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"404" : {
"description" : "404 response",
"content" : { }
}
},
"x-amazon-apigateway-integration" : {
"type" : "mock",
"responses" : {
"default" : {
"statusCode" : "404",
"responseTemplates" : {
"application/json" : "{ \"Message\" : \"Can't $context.httpMethod $context.resourcePath\" }"
}
}
},
"requestTemplates" : {
"application/json" : "{\"statusCode\": 200}"
},
"passthroughBehavior" : "when_no_match"
}
}
}
},
"components" : {
"schemas" : {
"Input" : {
"title" : "Input",
"type" : "object",
"properties" : {
"a" : {
"type" : "number"
},
"b" : {
"type" : "number"
},
"op" : {
"type" : "string"
}
}
},
"Output" : {
"title" : "Output",
"type" : "object",
"properties" : {
"c" : {
"type" : "number"
}
}
},
"Result" : {
"title" : "Result",
"type" : "object",
"properties" : {
"input" : {
"$ref" : "#/components/schemas/Input"
},
"output" : {
"$ref" : "#/components/schemas/Output"
}
}
}
}
}
}
```
------
# Generazione dell'SDK Java di un'API in Gateway API
La procedura seguente mostra come generare l'SDK Java di un'API in Gateway API.
**Per generare l'SDK Java di un'API di API Gateway**
1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Scegliere un'API REST.
1. Scegliere **Stages (Fasi)**.
1. Nel riquadro **Fasi**, seleziona il nome della fase.
1. Apri il menu **Azioni fase**, quindi scegli **Genera SDK**.
1. In **Piattaforma**, scegli la piattaforma **Java** ed effettua le seguenti operazioni:
1. In **Service Name (Nome servizio)** specificare il nome dell'SDK. Ad esempio, **SimpleCalcSdk**. Questo diventa il nome della classe del client SDK. Il nome corrisponde al tag `` in `` nel file pom.xml presente nella cartella di progetto dell'SDK. Non includere i trattini.
1. In **Java Package Name (Nome pacchetto Java)** specificare il nome di un pacchetto per l'SDK. Ad esempio, **examples.aws.apig.simpleCalc.sdk**. Questo nome di pacchetto viene utilizzato come namespace della libreria dell'SDK. Non includere i trattini.
1. In **Java Build System (Sistema di compilazione Java)** immettere **maven** o **gradle** per specificare il sistema di compilazione.
1. In **Java Group Id (ID gruppo Java)**, immettere l'identificatore di un gruppo per il progetto SDK. Ad esempio, immetti **my-apig-api-examples**. L'identificatore corrisponde al tag `` di `` nel file `pom.xml` presente nella cartella di progetto dell'SDK.
1. In **Java Artifact Id (ID artefatto Java)**, immettere l'identificatore di un artefatto per il progetto SDK. Ad esempio, immetti **simple-calc-sdk**. L'identificatore corrisponde al tag `` di `` nel file `pom.xml` presente nella cartella di progetto dell'SDK.
1. In **Java Artifact Version (Versione artefatto Java)**, immettere la stringa identificatore della versione. Ad esempio, **1.0.0**. L'identificatore della versione corrisponde al tag `` di `` nel file `pom.xml` presente nella cartella di progetto dell'SDK.
1. In **Source Code License Text (Testo della licenza del codice sorgente)**, immettere il testo della licenza del codice sorgente, se disponibile.
1. Seleziona **Generate SDK (Genera SDK)** e segui le istruzioni sullo schermo per scaricare l'SDK generato da API Gateway.
Segui le istruzioni nell'articolo [Utilizzo di un SDK Java generato da API Gateway per un'API REST](how-to-call-apigateway-generated-java-sdk.md) per usare l'SDK generato.
Ogni volta che aggiorni un'API, devi ridistribuire l'API e rigenerare l'SDK per includere gli aggiornamenti.
# Generazione dell'SDK Android di un'API in Gateway API
La procedura seguente mostra come generare l'SDK Android di un'API in Gateway API.
**Per generare l'SDK Android di un'API in API Gateway**
1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Scegliere un'API REST.
1. Scegliere **Stages (Fasi)**.
1. Nel riquadro **Fasi**, seleziona il nome della fase.
1. Apri il menu **Azioni fase**, quindi scegli **Genera SDK**.
1. In **Piattaforma**, scegli la piattaforma Android ed effettua le seguenti operazioni:
1. In **Group ID (ID gruppo)**, immettere l'identificatore univoco per il progetto corrispondente che viene usato nel file `pom.xml`, ad esempio **com.mycompany**.
1. In **Invoker package (Pacchetto di invoker)**, immettere lo spazio dei nomi per le classi client generate, ad esempio **com.mycompany.clientsdk**.
1. In **Artifact ID (ID artefatto)**, immettere il nome del file .jar compilato senza la versione che viene usato nel file `pom.xml`, ad esempio **aws-apigateway-api-sdk**.
1. In **Artifact version (Versione artefatto)**, immettere il numero di versione dell'artefatto per il cliente generato che Viene utilizzato nel `pom.xml` file e dovrebbe seguire un. *major* *minor*. *patch*modello (ad esempio,**1.0.0**).
1. Seleziona **Generate SDK (Genera SDK)** e segui le istruzioni sullo schermo per scaricare l'SDK generato da API Gateway.
Segui le istruzioni nell'articolo [Utilizzo di un SDK Android generato da API Gateway per un'API REST](how-to-generate-sdk-android.md) per usare l'SDK generato.
Ogni volta che aggiorni un'API, devi ridistribuire l'API e rigenerare l'SDK per includere gli aggiornamenti.
# Generazione dell'SDK iOS di un'API in Gateway API
La procedura seguente mostra come generare l'SDK iOS di un'API in Gateway API.
**Per generare l'SDK iOS di un'API in API Gateway**
1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Scegliere un'API REST.
1. Scegliere **Stages (Fasi)**.
1. Nel riquadro **Fasi**, seleziona il nome della fase.
1. Apri il menu **Azioni fase**, quindi scegli **Genera SDK**.
1. In **Piattaforma**, scegli la piattaforma **iOS (Objective-C) o iOS (Swift)** ed effettua le seguenti operazioni:
1. Digitare un prefisso univoco nella casella **Prefix (Prefisso)**.
L'effetto del prefisso è il seguente: se si assegna, ad esempio, **SIMPLE\$1CALC** come prefisso per l'SDK all'[SimpleCalc](simple-calc-lambda-api.md)API con, e `result` modelli`input`, `output` l'SDK generato conterrà la `SIMPLE_CALCSimpleCalcClient` classe che incapsula l'API, incluso il metodo richieste/risposte. Inoltre, l'SDK generato conterrà le classi `SIMPLE_CALCinput`, `SIMPLE_CALCoutput` e `SIMPLE_CALCresult` per rappresentare l'input, l'output e i risultati, rispettivamente, per l'input di richiesta e l'output di risposta. Per ulteriori informazioni, consulta [Uso dell'SDK iOS generato da API Gateway per un'API REST in Objective-C o Swift](how-to-generate-sdk-ios.md).
1. Seleziona **Generate SDK (Genera SDK)** e segui le istruzioni sullo schermo per scaricare l'SDK generato da API Gateway.
Segui le istruzioni nell'articolo [Uso dell'SDK iOS generato da API Gateway per un'API REST in Objective-C o Swift](how-to-generate-sdk-ios.md) per usare l'SDK generato.
Ogni volta che aggiorni un'API, devi ridistribuire l'API e rigenerare l'SDK per includere gli aggiornamenti.
# Genera l' JavaScript SDK di un'API REST in API Gateway
La procedura seguente mostra come generare l' JaveScript SDK di un'API in API Gateway.
**Per generare l' JavaScript SDK di un'API in API Gateway**
1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Scegliere un'API REST.
1. Scegliere **Stages (Fasi)**.
1. Nel riquadro **Fasi**, seleziona il nome della fase.
1. Apri il menu **Azioni fase**, quindi scegli **Genera SDK**.
1. Per **Piattaforma, scegli la piattaforma**. **JavaScript**
1. Seleziona **Generate SDK (Genera SDK)** e segui le istruzioni sullo schermo per scaricare l'SDK generato da API Gateway.
Segui le istruzioni nell'articolo [Usa un JavaScript SDK generato da API Gateway per un'API REST](how-to-generate-sdk-javascript.md) per usare l'SDK generato.
Ogni volta che aggiorni un'API, devi ridistribuire l'API e rigenerare l'SDK per includere gli aggiornamenti.
# Generazione dell'SDK Ruby di un'API in Gateway API
La procedura seguente mostra come generare l'SDK Ruby di un'API in Gateway API.
**Per generare l'SDK Ruby di un'API in API Gateway**
1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Scegliere un'API REST.
1. Scegliere **Stages (Fasi)**.
1. Nel riquadro **Fasi**, seleziona il nome della fase.
1. Apri il menu **Azioni fase**, quindi scegli **Genera SDK**.
1. In **Piattaforma**, scegli la piattaforma **Ruby** ed effettua le seguenti operazioni:
1. In **Service Name (Nome servizio)** specificare il nome dell'SDK. Ad esempio, **SimpleCalc**. Questo nome viene utilizzato come namespace Ruby Gem dell'API. Deve essere composto solo da lettere, (`a-zA-Z`), senza caratteri speciali o numeri.
1. In **Ruby Gem Name (Nome Ruby Gem)** specificare il nome Ruby Gem per contenere il codice sorgente dell'SDK generato per l'API. Per impostazione predefinita, è il nome del servizio in minuscolo più il suffisso `-sdk`, ad esempio **simplecalc-sdk**.
1. In **Ruby Gem Version (Versione Ruby Gem)** specificare il numero di versione del Ruby Gem generato. Per impostazione predefinita, è impostato su `1.0.0`.
1. Seleziona **Generate SDK (Genera SDK)** e segui le istruzioni sullo schermo per scaricare l'SDK generato da API Gateway.
Segui le istruzioni nell'articolo [Utilizzo di un SDK Ruby generato da API Gateway per un'API REST](how-to-call-sdk-ruby.md) per usare l'SDK generato.
Ogni volta che aggiorni un'API, devi ridistribuire l'API e rigenerare l'SDK per includere gli aggiornamenti.
# Generazione SDKs per un'API utilizzando AWS CLI i comandi in API Gateway
Puoi usarlo AWS CLI per generare e scaricare un SDK di un'API per una piattaforma supportata chiamando il comando [get-sdk](https://docs.aws.amazon.com/cli/latest/reference/apigateway/get-sdk.html). Di seguito è riportata la dimostrazione per alcune delle piattaforme supportate.
**Topics**
+ [Genera e scarica l'SDK Java per Android utilizzando il AWS CLI](#how-to-generate-sdk-cli-android)
+ [Genera e scarica l' JavaScript SDK utilizzando il AWS CLI](#how-to-generate-sdk-cli-js)
+ [Genera e scarica l'SDK di Ruby usando AWS CLI](#how-to-generate-sdk-cli-ruby)
## Genera e scarica l'SDK Java per Android utilizzando il AWS CLI
Per generare e scaricare un SDK Java per Android generato da API Gateway di un'API (`udpuvvzbkc`) in una specifica fase (`test`), invoca il comando seguente:
```
aws apigateway get-sdk \
--rest-api-id udpuvvzbkc \
--stage-name test \
--sdk-type android \
--parameters groupId='com.mycompany',\
invokerPackage='com.mycompany.myApiSdk',\
artifactId='myApiSdk',\
artifactVersion='0.0.1' \
~/apps/myApi/myApi-android-sdk.zip
```
L'ultimo input di `~/apps/myApi/myApi-android-sdk.zip` è il percorso del file SDK scaricato denominato `myApi-android-sdk.zip`.
## Genera e scarica l' JavaScript SDK utilizzando il AWS CLI
Per generare e scaricare un JavaScript SDK generato da API Gateway di un'API (`udpuvvzbkc`) in una determinata fase (`test`), chiamate il comando come segue:
```
aws apigateway get-sdk \
--rest-api-id udpuvvzbkc \
--stage-name test \
--sdk-type javascript \
~/apps/myApi/myApi-js-sdk.zip
```
L'ultimo input di `~/apps/myApi/myApi-js-sdk.zip` è il percorso del file SDK scaricato denominato `myApi-js-sdk.zip`.
## Genera e scarica l'SDK di Ruby usando AWS CLI
Per generare e scaricare un SDK Ruby di un'API (`udpuvvzbkc`) in una specifica fase (`test`), chiama il comando come segue:
```
aws apigateway get-sdk \
--rest-api-id udpuvvzbkc \
--stage-name test \
--sdk-type ruby \
--parameters service.name=myApiRubySdk,ruby.gem-name=myApi,ruby.gem-version=0.01 \
~/apps/myApi/myApi-ruby-sdk.zip
```
L'ultimo input di `~/apps/myApi/myApi-ruby-sdk.zip` è il percorso del file SDK scaricato denominato `myApi-ruby-sdk.zip`.
Successivamente, mostreremo come utilizzare l'SDK generato per chiamare l'API sottostante. Per ulteriori informazioni, consulta [Invocazione di REST API in Gateway API](how-to-call-api.md).
# Vendi il tuo API Gateway APIs tramite Marketplace AWS
Dopo aver creato, testato e distribuito il tuo APIs, puoi inserirlo in un [piano di utilizzo](api-gateway-api-usage-plans.md) API Gateway e venderlo come prodotto Software as a Service (SaaS). Marketplace AWS Gli acquirenti di API che si abbonano alla tua offerta di prodotti vengono fatturati Marketplace AWS in base al numero di richieste effettuate al piano di utilizzo.
Per vendere APIs il tuo prodotto Marketplace AWS, devi configurare il canale di vendita per l'integrazione Marketplace AWS con API Gateway. In generale, ciò comporta l'offerta del prodotto Marketplace AWS, l'impostazione di un ruolo IAM con politiche appropriate per consentire ad API Gateway di inviare metriche di utilizzo a Marketplace AWS, l'associazione di un Marketplace AWS prodotto a un piano di utilizzo API Gateway e l'associazione di un Marketplace AWS acquirente a una chiave API Gateway. I dettagli vengono approfonditi nelle sezioni seguenti.
Per ulteriori informazioni sulla vendita della tua API come prodotto SaaS Marketplace AWS, consulta la Guida per l'[Marketplace AWS utente](https://docs.aws.amazon.com/marketplace/latest/userguide/).
**Topics**
+ [Inizializza l' Marketplace AWS integrazione con API Gateway](#sell-api-as-saas-on-aws-marketplace-initial-setup)
+ [Gestione della sottoscrizione del cliente ai piani di utilizzo](#sell-api-as-saas-on-aws-marketplace-subscription-unsubscription)
## Inizializza l' Marketplace AWS integrazione con API Gateway
Le seguenti attività riguardano l'inizializzazione unica dell' Marketplace AWS integrazione con API Gateway, che consente di vendere il prodotto APIs come SaaS.
### Pubblica un prodotto su Marketplace AWS
Per inserire il tuo piano di utilizzo come prodotto SaaS, invia un modulo di caricamento prodotto tramite [Marketplace AWS](https://aws.amazon.com/marketplace/partners/management-tour). Il prodotto deve contenere una dimensione denominata `apigateway` del tipo `requests`. Questa dimensione definisce price-per-request e viene utilizzata da API Gateway per misurare le richieste al tuo APIs.
### Creazione del ruolo di misurazione
Crea un ruolo IAM denominato `ApiGatewayMarketplaceMeteringRole` con le seguenti policy di esecuzione e policy di attendibilità. Questo ruolo consente ad API Gateway di inviare metriche di utilizzo Marketplace AWS a tuo nome.
#### Policy di esecuzione del ruolo di misurazione
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": [
"aws-marketplace:BatchMeterUsage",
"aws-marketplace:ResolveCustomer"
],
"Resource": "*",
"Effect": "Allow"
}
]
}
```
------
#### Policy di relazione di fiducia del ruolo di misurazione
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "apigateway.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
```
------
### Associa il piano di utilizzo al prodotto Marketplace AWS
Quando offri un prodotto su Marketplace AWS, ricevi un codice Marketplace AWS prodotto. Per integrare API Gateway con Marketplace AWS, associa il tuo piano di utilizzo al codice Marketplace AWS del prodotto. Puoi abilitare l'associazione impostando il [https://docs.aws.amazon.com/apigateway/latest/api/API_UsagePlan.html#productCode](https://docs.aws.amazon.com/apigateway/latest/api/API_UsagePlan.html#productCode)campo `UsagePlan` dell'API Gateway sul codice del Marketplace AWS prodotto, utilizzando la console API Gateway, l'API REST API Gateway, l'API AWS CLI for API Gateway o l' AWS SDK per API Gateway. Nell'esempio di codice seguente viene utilizzata l'API REST dell'API Gateway:
```
PATCH /usageplans/USAGE_PLAN_ID
Host: apigateway.region.amazonaws.com
Authorization: ...
{
"patchOperations" : [{
"path" : "/productCode",
"value" : "MARKETPLACE_PRODUCT_CODE",
"op" : "replace"
}]
}
```
## Gestione della sottoscrizione del cliente ai piani di utilizzo
Le seguenti attività sono gestite dall'applicazione del portale sviluppatore.
Quando un cliente si abbona al tuo prodotto tramite Marketplace AWS, Marketplace AWS inoltra una `POST` richiesta all'URL degli abbonamenti SaaS che hai registrato al momento dell'offerta del prodotto. Marketplace AWS La richiesta `POST` presenta un parametro `x-amzn-marketplace-token` contenente le informazioni sull'acquirente. Segui le istruzioni riportate in [Onboarding dei clienti SaaS](https://docs.aws.amazon.com/marketplace/latest/userguide/saas-product-customer-setup.html#in-your-application) per gestire questo reindirizzamento nell'applicazione del portale per gli sviluppatori.
In risposta alla richiesta di iscrizione di un cliente, Marketplace AWS invia una `subscribe-success` notifica a un argomento di Amazon SNS a cui puoi abbonarti. (Consulta [Onboarding dei clienti SaaS](https://docs.aws.amazon.com/marketplace/latest/userguide/saas-product-customer-setup.html#in-your-application)). Per accettare la richiesta di abbonamento del cliente, gestisci la `subscribe-success` notifica creando o recuperando una chiave API Gateway per il cliente, associando la chiave API Marketplace AWS-provisioned `customerId` del cliente alle chiavi API e quindi aggiungendo la chiave API al tuo piano di utilizzo.
Una volta completata la richiesta di abbonamento del cliente, l'applicazione del portale per sviluppatori deve presentare al cliente la chiave API associata e informare il cliente che la chiave API deve essere inclusa nell'intestazione delle richieste inviate a. `x-api-key` APIs
Quando un cliente annulla un abbonamento a un piano di utilizzo, Marketplace AWS invia una `unsubscribe-success` notifica all'argomento SNS. Per portare a termine il processo di cancellazione di un cliente, devi gestire la notifica `unsubscribe-success` eliminando le chiavi API del cliente dal piano di utilizzo.
### Per autorizzare un cliente ad accedere a un piano di utilizzo
Per autorizzare un cliente ad accedere al tuo piano di utilizzo, usa l'API di API Gateway per recuperare o creare una chiave API per il cliente e aggiungerla al piano di utilizzo.
L'esempio seguente mostra come chiamare l'API REST di API Gateway per creare una nuova chiave API con un Marketplace AWS `customerId` valore specifico (*MARKETPLACE\$1CUSTOMER\$1ID*).
```
POST apikeys HTTP/1.1
Host: apigateway.region.amazonaws.com
Authorization: ...
{
"name" : "my_api_key",
"description" : "My API key",
"enabled" : "false",
"stageKeys" : [ {
"restApiId" : "uycll6xg9a",
"stageName" : "prod"
} ],
"customerId" : "MARKETPLACE_CUSTOMER_ID"
}
```
L'esempio seguente mostra come ottenere una chiave API con un Marketplace AWS `customerId` valore specifico (*MARKETPLACE\$1CUSTOMER\$1ID*).
```
GET apikeys?customerId=MARKETPLACE_CUSTOMER_ID HTTP/1.1
Host: apigateway.region.amazonaws.com
Authorization: ...
```
Per aggiungere una chiave API a un piano di utilizzo, crea un [https://docs.aws.amazon.com/apigateway/latest/api/API_UsagePlanKey.html](https://docs.aws.amazon.com/apigateway/latest/api/API_UsagePlanKey.html) con la chiave API per il relativo piano di utilizzo. Il seguente esempio mostra come ottenere tale risultato utilizzando l'API REST di API Gateway, dove `n371pt` è l'ID del piano di utilizzo e `q5ugs7qjjh` è un esempio di `keyId` API restituito dagli esempi precedenti.
```
POST /usageplans/n371pt/keys HTTP/1.1
Host: apigateway.region.amazonaws.com
Authorization: ...
{
"keyId": "q5ugs7qjjh",
"keyType": "API_KEY"
}
```
### Per associare un cliente a una chiave API
È necessario aggiornare il `customerId` campo [https://docs.aws.amazon.com/apigateway/latest/api/API_ApiKey.html](https://docs.aws.amazon.com/apigateway/latest/api/API_ApiKey.html)'s con l'ID Marketplace AWS cliente del cliente. In questo modo, la chiave API viene associata al cliente Marketplace AWS , attivando così misurazione e fatturazione per l'acquirente. Il seguente esempio di codice invoca l'API REST API Gateway per ottenere tale risultato.
```
PATCH /apikeys/q5ugs7qjjh
Host: apigateway.region.amazonaws.com
Authorization: ...
{
"patchOperations" : [{
"path" : "/customerId",
"value" : "MARKETPLACE_CUSTOMER_ID",
"op" : "replace"
}]
}
```