Tutorial: creazione di un'API REST con l'integrazione non proxy HTTP - Amazon API Gateway
Creazione di un'API con l'integrazione personalizzata HTTP(Facoltativo) Mappatura dei parametri di richiesta

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Tutorial: creazione di un'API REST con l'integrazione non proxy HTTP

In questo tutorial viene creata un'API da zero utilizzando la console Amazon API Gateway. Puoi pensare alla console come a uno studio di progettazione delle API e utilizzarla per analizzare le caratteristiche delle API, sperimentare i loro comportamenti, crearle e poi distribuirle per fasi.

Creazione di un'API con l'integrazione personalizzata HTTP

Questa sezione illustra per fasi come creare le risorse, esporre i metodi su una risorsa, configurare un metodo per ottenere i comportamenti dell'API desiderati, testar e distribuire le API.

In questa fase si crea un'API vuota. Nelle seguenti fasi crei risorse e metodi per connettere l'API all'endpoint http://petstore-demo-endpoint.execute-api.com/petstore/pets, utilizzando un'integrazione HTTP non proxy.

Per creare un API

  1. Accedere alla console API Gateway all'indirizzo https://console.aws.amazon.com/apigateway.

  2. Se si utilizza API Gateway per la prima volta, verrà visualizzata una pagina che presenta le caratteristiche del servizio. In API REST, scegliere Crea. Quando appare il popup Create Example API (Crea API di esempio), scegliere OK.

    Se non è la prima volta che si utilizza API Gateway, scegliere Create API (Crea API). In API REST, scegliere Crea.

  3. Per API name (Nome API), immettere HTTPNonProxyAPI.

  4. (Facoltativo) In Description (Descrizione), immettere una descrizione.

  5. Lasciare l'opzione Tipo di endpoint API impostata su Regionale.

  6. Seleziona Create API (Crea API).

L'albero Resources (Risorse) mostra la risorsa root (/) senza metodi. In questo esercizio, creeremo l'API con l'integrazione personalizzata HTTP del PetStore sito Web (http://petstore-demo-endpoint.execute-api.com/petstore/pets). A scopo illustrativo, creeremo una /pets risorsa come elemento secondario della radice e su questa risorsa esporremo un metodo GET per consentire a un cliente di recuperare un elenco di articoli Pets disponibili dal sito Web. PetStore

Per creare una risorsa /pets

  1. Seleziona la risorsa /, quindi scegli Crea risorsa.

  2. Mantieni l'opzione Risorsa proxy disattivata.

  3. Mantieni Percorso risorsa impostato su /.

  4. Per Resource Name (Nome risorsa) immetti pets.

  5. Mantieni CORS (Cross Origin Resource Sharing) disattivato.

  6. Scegli Crea risorsa.

In questa fase crei un metodo GET per la risorsa /pets. Il metodo GET è integrato con il sito Web http://petstore-demo-endpoint.execute-api.com/petstore/pets. Altre opzioni per il metodo API sono:

  • POST, usato principalmente per creare risorse figlio.

  • PUT, utilizzato principalmente per aggiornare risorse esistenti (e, sebbene non consigliato, può essere usato per creare risorse figlio).

  • DELETE, utilizzato per eliminare le risorse.

  • PATCH, utilizzato per aggiornare le risorse.

  • HEAD, utilizzato principalmente negli scenari di test. È lo stesso di GET ma non restituisce la rappresentazione della risorsa.

  • OPTIONS, che può essere utilizzato dagli intermediari per ricevere informazioni sulle opzioni di comunicazione disponibili per il servizio di destinazione.

Per HTTP method (Metodo HTTP) della richiesta di integrazione, occorre selezionarne uno supportato dal back-end. Per HTTP o Mock integration, è opportuno che la richiesta di metodo e la richiesta di integrazione utilizzino lo stesso verbo HTTP. Per altri tipi di integrazione, la richiesta di metodo utilizzerà probabilmente un verbo HTTP diverso da quello della richiesta di integrazione. Ad esempio, per chiamare una funzione Lambda, la richiesta di integrazione deve utilizzare POST per invocare la funzione, mentre la richiesta di metodo potrebbe utilizzare qualsiasi verbo HTTP in base alla logica della funzione Lambda.

Per creare un metodo GET nella risorsa /pets

  1. Seleziona la risorsa /pets.

  2. Scegli Crea metodo.

  3. Per Tipo di metodo seleziona GET.

  4. Per Tipo di integrazione seleziona Integrazione HTTP.

  5. Mantieni l'opzione Integrazione proxy HTTP disattivata.

  6. Per Metodo HTTP seleziona GET.

  7. Per URL dell'endpoint immetti http://petstore-demo-endpoint.execute-api.com/petstore/pets.

  8. Per Gestione contenuti seleziona Transito.

  9. Mantieni attivata l'opzione Timeout predefinito.

  10. Scegli Crea metodo.

Il PetStore sito Web consente di recuperare un elenco di Pet elementi in base al tipo di animale domestico (ad esempio «Cane» o «Gatto») in una determinata pagina. Utilizza i parametri della stringa di query type e page per accettare tale input. Pertanto, dobbiamo aggiungere i parametri della stringa di query alla richiesta di metodo e mapparli nelle stringhe di query corrispondenti della richiesta di integrazione.

Per aggiungere parametri della stringa di query al metodo GET

  1. Nella scheda Richiesta metodo, in Impostazioni richiesta metodo, scegli Modifica.

  2. Scegli Parametri della stringa di query URL ed effettua le seguenti operazioni:

    1. Scegliere Add query string (Aggiungi stringa di query).

    2. Per Nome immetti type.

    3. Mantieni Obbligatorio e Caching disattivati.

    Ripeti le fasi precedenti per creare una stringa di query aggiuntiva denominata page.

  3. Selezionare Salva.

Se invii una richiesta, ora il client può fornire un tipo di animale e un numero di pagina come parametri della stringa di query. Questi parametri di input devono essere mappati nei parametri della stringa di query dell'integrazione per inoltrare i valori di input al nostro PetStore sito Web nel backend.

Per mappare i parametri di input alla richiesta di integrazione

  1. Nella scheda Richiesta di integrazione scegli Modifica in Impostazioni della richiesta di integrazione.

  2. Scegli Parametri della stringa di query URL ed effettua le seguenti operazioni:

    1. Scegli Aggiungi parametro della stringa di query.

    2. Per Nome, immetti type.

    3. Per Mappato da immetti method.request.querystring.type.

    4. Mantieni disattivata l'opzione Caching.

    5. Scegli Aggiungi parametro della stringa di query.

    6. Per Nome, immetti page.

    7. Per Mappato da immetti method.request.querystring.page.

    8. Mantieni disattivata l'opzione Caching.

  3. Selezionare Salva.

Per testare l'API

  1. Seleziona la scheda Test. Potrebbe essere necessario scegliere il pulsante freccia destra per visualizzare la scheda.

  2. In Stringhe di query immetti type=Dog&page=2.

  3. Scegli Test (Esegui test).

    Il risultato è simile al seguente:

    Risultato del metodo GET on Pets per la chiamata di test

    Ora che il test è andato a buon fine, puoi distribuire l'API per renderla pubblicamente disponibile.

  4. Seleziona Deploy API (Distribuisci API).

  5. In Fase, seleziona Nuova fase.

  6. In Stage name (Nome fase) immettere Prod.

  7. (Facoltativo) In Description (Descrizione), immettere una descrizione.

  8. Seleziona Deploy (Implementa).

  9. (Facoltativo) In Dettagli fase puoi scegliere l'icona Copia per copiare l'URL di richiamata dell'API in Richiama URL. È possibile usare questo valore con strumenti come Postman e cURL per testare l'API.

Se utilizzi un SDK per creare un client, puoi chiamare i metodi esposti dall'SDK per firmare la richiesta. Per maggiori dettagli sull'implementazione, consulta il kit SDK AWS scelto.

Nota

Se apporti modifiche alla tua API, devi ridistribuirla per fare in modo che le caratteristiche nuove o aggiornate siano disponibili prima di chiamare di nuovo l'URL di richiesta.

(Facoltativo) Mappatura dei parametri di richiesta

Mappatura di parametri di richieste per un'API di API Gateway

Questo tutorial illustra come creare un parametro di percorso {petId} nell'URL della richiesta del metodo dell'API in modo da specificare un ID elemento, mapparlo al parametro di percorso {id} nell'URL della richiesta di integrazione e inviare la richiesta all'endpoint HTTP.

Nota

Se immetti una lettera maiuscola o minuscola errata, ad esempio una lettera minuscola anziché maiuscola, verranno restituiti errori più avanti nella procedura dettagliata.

Fase 1: Creazione delle risorse

In questa fase crei una risorsa con un parametro di percorso {petId}.

Per creare la risorsa {petId}

  1. Seleziona la risorsa /pets, quindi scegli Crea risorsa.

  2. Mantieni l'opzione Risorsa proxy disattivata.

  3. Per Percorso risorsa seleziona /pets.

  4. Per Resource Name (Nome risorsa) immetti {petId}.

    Utilizza le parentesi graffe ({ }) per racchiudere petId, in modo da visualizzare /pets/{petId}.

  5. Mantieni CORS (Cross Origin Resource Sharing) disattivato.

  6. Scegli Crea risorsa.

Fase 2: Creazione e test dei metodi

In questa fase crei un metodo GET con un parametro di percorso {petId}.

Per configurare il metodo GET

  1. Seleziona la risorsa /{petId}, quindi scegli Crea metodo.

  2. Per Tipo di metodo seleziona GET.

  3. Per Tipo di integrazione seleziona Integrazione HTTP.

  4. Mantieni l'opzione Integrazione proxy HTTP disattivata.

  5. Per Metodo HTTP seleziona GET.

  6. Per URL dell'endpoint immetti http://petstore-demo-endpoint.execute-api.com/petstore/pets/{id}.

  7. Per Gestione contenuti seleziona Transito.

  8. Mantieni attivata l'opzione Timeout predefinito.

  9. Scegli Crea metodo.

A questo punto mappa il parametro di percorso {petId} al parametro di percorso {id} nell'endpoint HTTP.

Per mappare il parametro di percorso {petId}

  1. Nella scheda Richiesta di integrazione scegli Modifica in Impostazioni della richiesta di integrazione.

  2. Scegli Parametri di percorso URL.

  3. Gateway API crea un parametro di percorso per la richiesta di integrazione denominata petId. Questo non vale per il back-end. L'endpoint HTTP utilizza {id} come parametro di percorso. Rinomina petId in id.

    In questo modo, verrà mappato il parametro di percorso petId della richiesta del metodo al parametro di percorso id della richiesta di integrazione.

  4. Selezionare Salva.

Quindi testa il metodo.

Test del metodo 

  1. Seleziona la scheda Test. Potrebbe essere necessario scegliere il pulsante freccia destra per visualizzare la scheda.

  2. In Percorso immetti 4 per petId.

  3. Scegli Test (Esegui test).

    Se il test ha esito positivo, in Corpo della risposta viene visualizzato quanto segue:

    {
  "id": 4,
  "type": "bird",
  "price": 999.99
}

Fase 3: Distribuzione dell'API

In questa fase, viene distribuita l'API per poter iniziare a richiamarla esternamente alla console API Gateway.

Per distribuire l'API

  1. Seleziona Deploy API (Distribuisci API).

  2. Per Fase seleziona Produzione.

  3. (Facoltativo) In Description (Descrizione), immettere una descrizione.

  4. Selezionare Deploy (Distribuisci).

Fase 4: Test dell'API

In questa fase verrà chiusa la console API Gateway e utilizzata l'API per accedere all'endpoint HTTP.

  1. Nel pannello di navigazione principale scegli Fase.

  2. In Dettagli fase, scegli l'icona Copia per copiare l'URL di richiamo dell'API.

    Dovrebbe essere simile a quanto segue:

    https://my-api-id.execute-api.region-id.amazonaws.com/prod

  3. Inserisci questo URL nella casella dell'indirizzo di una nuova scheda del browser e aggiungi /pets/4 all'URL prima di inviare la richiesta.

  4. Il browser restituirà quanto segue:

    {
  "id": 4,
  "type": "bird",
  "price": 999.99
}

Passaggi successivi

Puoi personalizzare ulteriormente la tua API attivando la convalida delle richieste, trasformando i dati o creando risposte del gateway personalizzate.

Per scoprire altri modi per personalizzare l'API, consulta i seguenti tutorial: