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à. # Sviluppa REST APIs utilizzando OpenAPI in API Gateway Puoi utilizzare API Gateway per importare un'API REST da un file di definizione esterno in API Gateway. Attualmente, API Gateway supporta i file di definizione [v2.0](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md) e [OpenAPI v3.0](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.1.md) con le eccezioni elencate in [Note importanti su Amazon API Gateway per REST APIs](api-gateway-known-issues.md#api-gateway-known-issues-rest-apis). Puoi aggiornare un'API sovrascrivendola con una nuova definizione oppure puoi unire la definizione a quella di un'API esistente. Puoi specificare le opzioni utilizzando un parametro di query `mode` nell'URL di richiesta. Per un tutorial sull'utilizzo della caratteristica Importa API dalla console API Gateway, consulta [Tutorial: creazione di un'API REST mediante l'importazione di un esempio](api-gateway-create-api-from-example.md). **Topics** + [Importazione di un'API ottimizzata per l'edge in API Gateway](import-edge-optimized-api.md) + [Importazione di un'API regionale in Gateway API](import-export-api-endpoints.md) + [Importazione di un file OpenAPI per aggiornare una definizione API esistente](api-gateway-import-api-update.md) + [Impostare la proprietà openAPI `basePath`](api-gateway-import-api-basePath.md) + [AWS variabili per l'importazione OpenAPI](import-api-aws-variables.md) + [Errori e avvisi relativi all'importazione dell'API in Gateway API](api-gateway-import-api-errors-warnings.md) + [Esportazione di un'API REST da API Gateway](api-gateway-export-api.md) # Importazione di un'API ottimizzata per l'edge in API Gateway Puoi importare un file di definizione OpenAPI dell'API per creare una nuova API ottimizzata per gli edge specificando il tipo di endpoint `EDGE` come input aggiuntivo, oltre al file OpenAPI, nell'operazione di importazione. Puoi farlo utilizzando la console API Gateway o un AWS SDK. AWS CLI Per un tutorial sull'utilizzo della caratteristica Importa API dalla console API Gateway, consulta [Tutorial: creazione di un'API REST mediante l'importazione di un esempio](api-gateway-create-api-from-example.md). **Topics** + [Importazione di un'API ottimizzata per l'edge mediante la console API Gateway](#import-edge-optimized-api-with-console) + [Importa un'API ottimizzata per i dispositivi periferici utilizzando AWS CLI](#import-edge-optimized-api-with-awscli) ## Importazione di un'API ottimizzata per l'edge mediante la console API Gateway Per importare un'API ottimizzata per l'edge tramite la console API Gateway, procedi nel seguente modo: 1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway) 1. Seleziona **Create API** (Crea API). 1. In **API REST**, scegliere **Import (Importa)**. 1. Copia una definizione OpenAPI dell'API e incollala nell'editor di codice o seleziona **Scegli il file** per caricare un file OpenAPI da un'unità locale. 1. In **Tipo di endpoint**, scegli **Ottimizzato per gli edge**. 1. Scegli **Crea API** per iniziare a importare le definizioni OpenAPI. ## Importa un'API ottimizzata per i dispositivi periferici utilizzando AWS CLI Il [import-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/import-rest-api.html)comando seguente importa un'API da un file di definizione OpenAPI per creare una nuova API ottimizzata per i bordi: ``` aws apigateway import-rest-api \ --fail-on-warnings \ --body 'file://path/to/API_OpenAPI_template.json' ``` oppure specificando esplicitamente il parametro della stringa di query `endpointConfigurationTypes` come `EDGE`: ``` aws apigateway import-rest-api \ --parameters endpointConfigurationTypes=EDGE \ --fail-on-warnings \ --body 'file://path/to/API_OpenAPI_template.json' ``` # Importazione di un'API regionale in Gateway API Quando importi un'API, puoi scegliere la configurazione dell'endpoint regionale per l'API. Puoi utilizzare la console API Gateway AWS CLI, o un AWS SDK. Quando esporti un'API, la configurazione dell'endpoint dell'API non è inclusa nelle definizioni dell'API esportate. Per un tutorial sull'utilizzo della caratteristica Importa API dalla console API Gateway, consulta [Tutorial: creazione di un'API REST mediante l'importazione di un esempio](api-gateway-create-api-from-example.md). **Topics** + [Importazione di un'API regionale tramite la console API Gateway](#import-regional-api-with-console) + [Importa un'API regionale utilizzando AWS CLI](#import-regional-api-with-awscli) ## Importazione di un'API regionale tramite la console API Gateway Per importare un'API di un endpoint regionale mediante la console API Gateway, procedi come indicato di seguito: 1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway) 1. Seleziona **Create API** (Crea API). 1. In **API REST**, scegliere **Import (Importa)**. 1. Copia una definizione OpenAPI dell'API e incollala nell'editor di codice o seleziona **Scegli il file** per caricare un file OpenAPI da un'unità locale. 1. In **Tipo di endpoint**, scegli**Regionale**. 1. Scegli **Crea API** per iniziare a importare le definizioni OpenAPI. ## Importa un'API regionale utilizzando AWS CLI Il [import-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/import-rest-api.html)comando seguente importa un file di definizione OpenAPI e imposta il tipo di endpoint su Regional: ``` aws apigateway import-rest-api \ --parameters endpointConfigurationTypes=REGIONAL \ --fail-on-warnings \ --body 'file://path/to/API_OpenAPI_template.json' ``` # Importazione di un file OpenAPI per aggiornare una definizione API esistente Puoi importare le definizioni API solo per aggiornare un'API esistente, senza cambiare la configurazione del suo endpoint, le fasi, le variabili di fase o i riferimenti alle chiavi API. L' import-to-updateoperazione può avvenire in due modalità: unione o sovrascrittura. Quando un'API (`A`) viene unita a un'altra (`B`), l'API risultante mantiene le definizioni di entrambe `A` e `B` se le due APIs non condividono definizioni in conflitto. Quando si verificano dei conflitti, le definizioni di metodo dell'API di unione (`A`) sostituisce le definizioni di metodo corrispondenti dell'API unita (`B`). Ad esempio, supponiamo che `B` abbia dichiarato i seguenti metodi per restituire le risposte `200` e `206`: ``` GET /a POST /a ``` e `A` dichiari il metodo seguente per restituire le risposte `200` e `400`: ``` GET /a ``` Quando `A` viene unita a `B`, l'API risultante produrrà i seguenti metodi: ``` GET /a ``` che restituisce le risposte `200` e `400` e ``` POST /a ``` che restituisce le risposte `200` e `206`. Unire un'API è utile quando hai scomposto le definizioni API esterne in molteplici parti più piccole e vuoi applicare le modifiche solo a una parte per volta. Ad esempio, questo può succedere se più team sono responsabili di parti diverse di un'API e hanno modifiche disponibili a tariffe diverse. In questo modo, gli item dell'API esistente che non vengono esplicitamente indicati nella definizione importata saranno tralasciati. Quando un'API (`A`) sovrascrive un'altra API (`B`), l'API risultante prende le definizioni dell'API di sovrascrittura (`A`). Sovrascrivere un'API è utile quando una definizione API esterna ne contiene la definizione completa. In questo modo, gli item dell'API esistente che non vengono esplicitamente indicati nella definizione importata saranno eliminati. Per unire un'API, invia una richiesta `PUT` a `https://apigateway..amazonaws.com/restapis/?mode=merge`. Il valore del parametro percorso `restapi_id` specifica l'API con cui la definizione API fornita si unirà. Il seguente frammento di codice mostra un esempio della richiesta `PUT` di unione di una definizione API OpenAPI in JSON, come payload, con l'API specificata già presente in API Gateway. ``` PUT /restapis/?mode=merge Host:apigateway..amazonaws.com Content-Type: application/json Content-Length: ... An OpenAPI API definition in JSON ``` L'operazione di aggiornamento dell'unione consiste nell'unione di due definizioni API complete. Per una modifica piccola e incrementale, puoi utilizzare l'operazione di [aggiornamento risorsa](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateResource.html). Per sovrascrivere un'API, invia una richiesta `PUT` a `https://apigateway..amazonaws.com/restapis/?mode=overwrite`. Il parametro percorso `restapi_id` specifica l'API che verrà sovrascritta dalle definizioni API fornite. Il seguente frammento di codice mostra un esempio di richiesta di sovrascrittura con il payload di una definizione OpenAPI in formato JSON: ``` PUT /restapis/?mode=overwrite Host:apigateway..amazonaws.com Content-Type: application/json Content-Length: ... An OpenAPI API definition in JSON ``` Se il parametro di query `mode` non viene specificato, si procede con l'unione. **Nota** Le operazioni `PUT` sono idempotenti, ma non atomiche. Ciò significa che se si verifica un errore prima della fine dell'elaborazione, l'API può risultare in uno stato non valido. Tuttavia, ripetendo l'operazione con successo, l'API potrà essere nello stesso stato finale che avrebbe avuto se la prima operazione fosse riuscita. # Impostare la proprietà openAPI `basePath` In [OpenAPI 2.0](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md) è possibile usare la proprietà `basePath` per specificare una o più parti di percorso che precedono ogni percorso definito nella proprietà `paths`. Poiché API Gateway include diversi modi per esprimere il percorso di una risorsa, la caratteristica Importa API offre queste opzioni per interpretare la proprietà `basePath` durante l'importazione: ignore, prepend e split. In [https://swagger.io/docs/specification/api-host-and-base-path/](https://swagger.io/docs/specification/api-host-and-base-path/) `basePath` non è più una proprietà di primo livello. Al contrario, API Gateway usa una [variabile server](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#serverVariableObject) come convenzione. La funzionalità Import API (Importa API) offre le stesse opzioni per interpretare il percorso di base durante l'importazione. Il percorso di base può essere identificato in questo modo: + Se l'API non contiene variabili `basePath`, la funzionalità Import API (Importa API) controlla la stringa `server.url` per verificare se contiene un percorso dopo `"/"`. Se sì, il percorso viene usato come percorso di base. + Se l'API contiene solo una variabile `basePath`, la funzionalità Import API (Importa API) la usa come percorso di base, anche se alla variabile non viene fatto riferimento in `server.url`. + Se l'API contiene più variabili `basePath`, la funzionalità Import API (Importa API) usa solo la prima come percorso di base. ## Ignorare Se nel file OpenAPI il valore di `basePath` è `/a/b/c` e la proprietà `paths` contiene `/e` e `/f`, la richiesta `POST` o `PUT` seguente: ``` POST /restapis?mode=import&basepath=ignore ``` ``` PUT /restapis/api_id?basepath=ignore ``` porterà le seguenti risorse nell'API: + `/` + `/e` + `/f` Il punto è trattare il `basePath` come se non fosse presente e tutte le risorse API dichiarate vengono servite in relazione all'host. Questo può essere utile, ad esempio, quando hai un nome di dominio personalizzato con una mappatura API che non include un *Percorso di base* e un valore della *Fase* che si riferisce alla fase di produzione. **Nota** API Gateway creerà automaticamente una risorsa root, anche se non è stato dichiarato in modo esplicito nel file di definizione. In assenza di specifiche, `basePath` seleziona `ignore` per impostazione predefinita. ## Metti come prefisso Se nel file OpenAPI il valore di `basePath` è `/a/b/c` e la proprietà `paths` contiene `/e` e `/f`, la richiesta `POST` o `PUT` seguente: ``` POST /restapis?mode=import&basepath=prepend ``` ``` PUT /restapis/api_id?basepath=prepend ``` porterà le seguenti risorse nell'API: + `/` + `/a` + `/a/b` + `/a/b/c` + `/a/b/c/e` + `/a/b/c/f` L'effetto è trattare il `basePath` come se specificasse risorse aggiuntive (senza metodo) e aggiungerle al set di risorse dichiarato. Questo può essere utile, ad esempio, quando team diversi sono responsabili di parti diverse di un'API e il `basePath` potrebbe riferirsi al percorso della parte dell'API di ogni team. **Nota** API Gateway creerà automaticamente le risorse intermedie, anche se non sono dichiarate in modo esplicito nella definizione. ## Split Se nel file OpenAPI il valore di `basePath` è `/a/b/c` e la proprietà `paths` contiene `/e` e `/f`, la richiesta `POST` o `PUT` seguente: ``` POST /restapis?mode=import&basepath=split ``` ``` PUT /restapis/api_id?basepath=split ``` porterà le seguenti risorse nell'API: + `/` + `/b` + `/b/c` + `/b/c/e` + `/b/c/f` L'effetto è trattare la parte più alta del percorso, `/a`, come l'inizio del percorso di ogni risorsa e creare risorse aggiuntive (senza metodo) all'interno dell'API stessa. Questo potrebbe, ad esempio, essere utilizzato quando `a` è il nome di una fase che vuoi esporre come parte dell'API. # AWS variabili per l'importazione OpenAPI È possibile utilizzare le seguenti AWS variabili nelle definizioni OpenAPI. API Gateway risolve le variabili quando l'API viene importata. Per specificare una variabile, utilizzare `${variable-name}`. La tabella seguente descrive le AWS variabili disponibili. | Nome della variabile | Description | | --- | --- | | AWS::AccountId | L'ID AWS dell'account che importa l'API. Ad esempio, 123456789012. | | AWS::Partition | La AWS partizione in cui viene importata l'API. Per le AWS regioni standard, la partizione è. aws | | AWS::Region | La AWS regione in cui viene importata l'API. Ad esempio, us-east-2. | ## AWS esempio di variabili L'esempio seguente utilizza AWS le variabili per specificare una AWS Lambda funzione per un'integrazione. ------ #### [ OpenAPI 3.0 ] ``` openapi: "3.0.1" info: title: "tasks-api" version: "v1.0" paths: /: get: summary: List tasks description: Returns a list of tasks responses: 200: description: "OK" content: application/json: schema: type: array items: $ref: "#/components/schemas/Task" 500: description: "Internal Server Error" content: {} x-amazon-apigateway-integration: uri: arn:${AWS::Partition}:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/arn:${AWS::Partition}:lambda:${AWS::Region}:${AWS::AccountId}:function:LambdaFunctionName/invocations responses: default: statusCode: "200" passthroughBehavior: "when_no_match" httpMethod: "POST" contentHandling: "CONVERT_TO_TEXT" type: "aws_proxy" components: schemas: Task: type: object properties: id: type: integer name: type: string description: type: string ``` ------ # Errori e avvisi relativi all'importazione dell'API in Gateway API Quando si importa il file di definizione esterno in Gateway API è possibile che vengano generati avvisi ed errori. Nelle sezioni seguenti vengono descritti gli errori e gli avvisi che possono essere restituiti durante l'importazione. ## Errori durante l'importazione Nel corso dell'importazione, possono essere generati errori per problematiche rilevanti come nel caso di un documento OpenAPI non valido. Gli errori vengono restituiti come eccezioni (ad esempio, `BadRequestException`) in una risposta non andata a buon fine. Quando si verifica un errore, la nuova definizione dell'API viene scartata e all'API esistente non viene apportata alcuna modifica. ## Avvisi durante l'importazione Nel corso dell'importazione, gli avvisi possono essere generati per problematiche minori come nel caso di un riferimento mancante a un modello. In presenza di un avviso, l'operazione proseguirà se l'espressione di query `failonwarnings=false` viene aggiunta all'URL della richiesta. In caso contrario, gli aggiornamenti verranno ripristinati. Per impostazione predefinita, `failonwarnings` è impostato su `false`. In questi casi, gli avvisi vengono restituiti come campo nella [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html)risorsa risultante. In caso contrario, gli avvisi vengono restituiti come messaggio nell'eccezione. # Esportazione di un'API REST da API Gateway Dopo aver creato e configurato un'API REST in API Gateway tramite la console API Gateway o in un altro modo, puoi esportarla in un file OpenAPI usando l'API di esportazione di API Gateway integrata nel servizio di controllo di Amazon API Gateway. Per utilizzare l'API di Gateway Amazon API, è necessario firmare le richieste API. Per ulteriori informazioni sulla firma delle richieste, consulta [Signing AWS API requests](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-signing.html) nella *IAM User Guide*. Puoi scegliere di includere le estensioni di integrazione di API Gateway, nonché le estensioni [Postman](https://www.postman.com), nel file di definizione OpenAPI esportato. **Nota** Quando esporti l'API utilizzando il AWS CLI, assicurati di includere il parametro extensions come mostrato nell'esempio seguente, per assicurarti che l'`x-amazon-apigateway-request-validator`estensione sia inclusa: ``` aws apigateway get-export --parameters extensions='apigateway' --rest-api-id abcdefg123 --stage-name dev --export-type swagger latestswagger2.json ``` Non puoi esportare un'API se i suoi payload non sono di tipo `application/json`. Se ci provi, verrà restituita una risposta di errore che indica che non è stato possibile trovare i modelli di corpo JSON. ## Richiesta di esportazione di un'API REST Con l'API Export, puoi esportare un'API REST esistente inviando una richiesta GET, specificando l' to-be-exportedAPI come parte dei percorsi URL. L'URL della richiesta ha il formato seguente: ------ #### [ OpenAPI 3.0 ] ``` https:///restapis//stages//exports/oas30 ``` ------ #### [ OpenAPI 2.0 ] ``` https:///restapis//stages//exports/swagger ``` ------ Puoi aggiungere la stringa di query `extensions` per specificare se includere le estensioni API Gateway (con il valore `integration`) o le estensioni Postman (con il valore `postman`). Inoltre, puoi impostare l'intestazione `Accept` su `application/json` o `application/yaml` per ricevere l'output della definizione API rispettivamente in formato JSON o YAML. Per ulteriori informazioni sull'invio di richieste GET utilizzando l'API API Gateway Export, vedere [GetExport](https://docs.aws.amazon.com/apigateway/latest/api/API_GetExport.html). **Nota** Se definisci modelli nell'API, questi devono essere per il tipo di contenuto "application/json" perché API Gateway possa esportare il modello. In caso contrario, API Gateway genera un'eccezione con un messaggio di errore che indica che sono stati trovati solo modelli di corpo non JSON. I modelli devono contenere proprietà o essere definiti come un JSONSchema tipo particolare. ## Download della definizione OpenAPI dell'API REST in JSON Per esportare e scaricare un'API REST nelle definizioni OpenAPI in formato JSON: ------ #### [ OpenAPI 3.0 ] ``` GET /restapis//stages//exports/oas30 Host: apigateway..amazonaws.com Accept: application/json ``` ------ #### [ OpenAPI 2.0 ] ``` GET /restapis//stages//exports/swagger Host: apigateway..amazonaws.com Accept: application/json ``` ------ Qui `` può essere, ad esempio, `us-east-1`. Per l'elenco di tutte le Regioni in cui Gateway API è disponibile, consulta [Regions and Endpoints](https://docs.aws.amazon.com/general/latest/gr/rande.html#apigateway_region). ## Download della definizione OpenAPI dell'API REST in YAML Per esportare e scaricare un'API REST nelle definizioni OpenAPI in formato YAML: ------ #### [ OpenAPI 3.0 ] ``` GET /restapis//stages//exports/oas30 Host: apigateway..amazonaws.com Accept: application/yaml ``` ------ #### [ OpenAPI 2.0 ] ``` GET /restapis//stages//exports/swagger Host: apigateway..amazonaws.com Accept: application/yaml ``` ------ ## Download della definizione OpenAPI dell'API REST con estensioni Postman in JSON Per esportare e scaricare un'API REST nelle definizioni OpenAPI con Postman in formato JSON: ------ #### [ OpenAPI 3.0 ] ``` GET /restapis//stages//exports/oas30?extensions=postman Host: apigateway..amazonaws.com Accept: application/json ``` ------ #### [ OpenAPI 2.0 ] ``` GET /restapis//stages//exports/swagger?extensions=postman Host: apigateway..amazonaws.com Accept: application/json ``` ------ ## Download della definizione OpenAPI dell'API REST con l'integrazione di API Gateway in YAML Per esportare e scaricare un'API REST nelle definizioni OpenAPI con l'integrazione di API Gateway in formato YAML: ------ #### [ OpenAPI 3.0 ] ``` GET /restapis//stages//exports/oas30?extensions=integrations Host: apigateway..amazonaws.com Accept: application/yaml ``` ------ #### [ OpenAPI 2.0 ] ``` GET /restapis//stages//exports/swagger?extensions=integrations Host: apigateway..amazonaws.com Accept: application/yaml ``` ------ ## Esportazione di un'API REST tramite la console API Gateway Dopo aver [distribuito l'API REST in una fase](set-up-deployments.md#create-deployment), puoi procedere all'esportazione dell'API nella fase in un file OpenAPI usando la console API Gateway. Nel riquadro **Fasi** della console Gateway API, scegli **Operazioni fase**, **Esporta**. ![\[Esportazione di un'API REST tramite la console API Gateway\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/export-new-console.png) Specifica un valore in **Tipo di specifica API**, **Formato** ed **Estensioni** per scaricare la definizione OpenAPI dell'API.