Come posso associare un modello di dati alla mia REST API in Gateway API?

Risoluzione

Per associare un modello di dati a una REST API in Gateway API, completa i seguenti passaggi.

Scrivi lo schema di un modello da associare alla REST API

Nota: i modelli di Gateway API devono utilizzare la bozza dello schema JSON 4. Per informazioni sulla scrittura dello schema di un modello, consulta Modelli di dati per REST API.

Esempio di schema di un modello

Questo esempio di modello utilizza application/json come chiave predefinita per selezionare il modello di mappatura. Lo schema deve rispettare le seguenti condizioni:

• Gli utenti dell'API devono passare i propri valori UserID e Name nel corpo della richiesta.
• I valori UserID e Name devono essere valori di stringa.
• Il valore Age deve essere un valore intero pari o superiore a 18.

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "User",
  "type": "object",
  "properties": {
    "UserID": {
      "type": "string"
    },
    "Name": {
      "type": "string"
    },
    "Age": {
      "description": "Age in years",
      "type": "integer",
      "minimum": 18
    }
  },
  "required": [
    "UserID",
    "Name"
  ]
}

Crea un modello per la REST API

Per creare un modello in Gateway API, consulta Configurazione della convalida di base delle richieste in Gateway API.

Associa il modello al metodo API

Completa i seguenti passaggi:

1. Apri l'API nella console Gateway API.
2. Nel pannello di navigazione, scegli Risorse.
3. Seleziona il metodo API a cui desideri associare il modello.
4. Nel pannello Esecuzione metodo, scegli Richiesta metodo.
5. Per Validatore richiesta, seleziona Convalida corpo. Quindi scegli l'icona del segno di spunta per salvare la selezione.
6. Espandi Corpo della richiesta. Quindi scegli Aggiungi modello.
7. In Tipo di contenuto, inserisci il tipo di contenuto del modello. Ad esempio, inserisci application/json.
8. Per Nome modello, seleziona il modello che hai creato.
9. Scegli l'icona del segno di spunta per salvare le selezioni.

Esegui un test del modello

Completa i seguenti passaggi:

1. Dall'elenco Risorse dell'API, scegli il metodo API a cui hai associato il modello.

2. Nel pannello Esecuzione metodo, scegli ESEGUI TEST.

3. In Corpo della richiesta, inserisci un corpo della richiesta che corrisponda allo schema del modello che hai creato.
   Nota: per eseguire un test dell'esempio di modello application/json, utilizza il seguente esempio di corpo della richiesta:

   { "UserID": "abc123", "Name": "Ana", "Age": 21}

4. Scegli Esegui test.

5. Se la risposta al test ha esito positivo, il corpo della richiesta restituito corrisponde allo schema del modello.

(Facoltativo) Crea un modello di mappatura per il modello

Puoi utilizzare un modello di mappatura per modificare le richieste che vengono inviate al backend integrato dell'API. Per creare un modello di mappatura, completa i seguenti passaggi:

1. Dall'elenco Risorse dell'API, scegli il metodo API a cui hai associato il modello.

2. Nel pannello Esecuzione metodo, scegli Richiesta di integrazione.

3. Espandi Modelli di mappatura.

4. In Richiesta passthrough corpo scegli When there are no templates defined (recommended) (Quando non ci sono modelli definiti (consigliato)).

5. Scegli Aggiungi modello di mappatura.

6. In Content-Type, inserisci il tipo di contenuto del modello. Ad esempio, inserisci application/json.

7. Scegli l'icona del segno di spunta per salvare la selezione.

8. Per Genera modello, seleziona il modello che hai creato. Ad esempio, l'esempio di modello application/json appare come segue:

   #set($inputRoot = $input.path('$')) { "UserID" : "$inputRoot.UserID", "Name" : "$inputRoot.Name", "Age" : $inputRoot.Age }

9. Modifica il modello precedente in modo che contenga i valori che desideri passare al backend integrato dell'API.

10. Scegli Salva.

Distribuisci la REST API per eseguire il commit delle modifiche

Completa i seguenti passaggi:

1. Nel pannello di navigazione, scegli Risorse.
2. Scegli Operazioni. Quindi seleziona Distribuisci l'API.
3. Per Fase della distribuzione, seleziona una fase già esistente o scegli [Nuova fase] per creare una fase.
   Importante: se crei una nuova fase, devi inserire un nome in Nome fase.
4. Scegli Distribuire per ricevere l'URL di invocazione che utilizzi per effettuare richieste all'API distribuita.
5. Copia l'URL di invocazione.

Esegui un test della REST API

Invia una richiesta di test all'API che utilizza il metodo e il tipo di contenuto associati al modello. Una richiesta con esito positivo restituisce un codice di risposta 200 OK. Una richiesta con esito negativo restituisce un codice di stato 400.

Per inviare una richiesta di test, utilizza uno strumento di sviluppo API o un comando curl. Per ulteriori informazioni sulle chiamate REST API in Gateway API, consulta Invocazione di REST API in Gateway API. Per ulteriori informazioni sul comando curl, consulta il sito web curl.

Esempio di comando curl che utilizza la richiesta del metodo POST HTTP ed esegue il test per una risposta 200 OK

Nota: questo esempio di comando invia una richiesta di test all'esempio di modello application/json. Il comando restituisce una risposta 200 OK.

curl -X POST <API URL> -H 'Content-Type: application/json' -d '{ "UserID": "abc123", "Name": "Ana", "Age": 21 }'

(Facoltativo) Esempio di comando curl che utilizza la richiesta del metodo POST HTTP ed esegue il test per un codice di stato 400

Nota: il corpo della richiesta in questo esempio di comando non è valido perché non include l'attributo del modello UserID richiesto. Il comando restituisce un codice di stato 400.

curl -X POST <API URL> -H 'Content-Type: application/json' -d '{ "Name": "Ana", "Age": 21 }'