Utilizzo di un modello di mappatura per sostituire i parametri di richiesta e risposta e i codici di stato di un'API

I modelli di mappatura dei parametri e dei codici di risposta di API Gateway standard consentono di mappare i parametri one-to-one e mappare una famiglia di codici di stato della risposta di integrazione (abbinati a un'espressione regolare) a un singolo codice di stato della risposta. Le sostituzioni dei modelli di mappatura offrono la flessibilità di eseguire mappature dei parametri, sovrascrivere i many-to-one parametri dopo l'applicazione delle mappature standard dell'API Gateway, mappare in modo condizionale i parametri in base al contenuto del corpo o ad altri valori dei parametri, creare nuovi parametri in modo programmatico all'istante e sovrascrivere i codici di stato restituiti dall'endpoint di integrazione. Qualsiasi tipo di parametro di richiesta, intestazione di risposta o codice di stato della risposta può essere sovrascritto.

Di seguito sono riportati esempi di utilizzo di una sovrascrittura modello di mappatura:

• Per creare una nuova intestazione (o sostituire un'intestazione esistente) come una concatenazione di due parametri

• Per sovrascrivere il codice di risposta in a un codice di esito positivo o di errore in base al contenuto del corpo

• Per rimappare con riserva un parametro in base al suo contenuto o al contenuto di alcuni altri parametri

• Per eseguire iterazioni sul contenuto di un corpo json e rimappare coppie chiave-valore a intestazioni o stringhe di query

Per creare una sovrascrittura modello di mappatura, utilizza una o più delle seguenti variabili$context in un modello di mappatura:

Modello di mappatura corpo della richiesta	Modello di mappatura corpo della risposta
$context.requestOverride.header.header_name	$context.responseOverride.header.header_name
$context.requestOverride.path.path_name	$context.responseOverride.status
$context.requestOverride.querystring.querystring_name

Nota

Le sovrascritture modello di mappatura non possono essere utilizzate con endpoint di integrazione proxy, che sono privi di mappature dati. Per ulteriori informazioni sui tipi di integrazione, consulta Scegliere un tipo di integrazione API Gateway API.

Importante

Le sovrascritture sono finali. Una sovrascrittura può essere applicata a ciascun parametro una sola volta. Se si prova a sovrascrivere lo stesso parametro più volte, si ricevono risposte 5XX da Amazon API Gateway. Se occorre sovrascrivere lo stesso parametro più volte in tutto il modello, ti consigliamo di creare una variabile e applicare la sovrascrittura alla fine del modello. Osserva che il modello viene applicato solo dopo che l'intero modello è stato analizzato. Per informazioni, consulta Tutorial: Sovrascrittura di parametri e intestazioni della richiesta di un'API con la console API Gateway.

Nei seguenti tutorial viene mostrato come creare e sottoporre a test una sovrascrittura di modelli di mappatura nella console API Gateway. Questi PetStore tutorial utilizzano l'API di esempio come punto di partenza. Entrambi i tutorial presuppongono che tu abbia già creato l'API di esempio. PetStore

Tutorial: Sovrascrittura del codice dello stato di risposta di un'API con la console API Gateway

Per recuperare un animale domestico utilizzando l'API di PetStore esempio, si utilizza il metodo API request ofGET /pets/{petId}, dove {petId} è un parametro di percorso che può richiedere un numero in fase di esecuzione.

In questo tutorial, il codice di risposta del metodo GET verrà sovrascritto creando un modello di mappatura che associa $context.responseOverride.status a 400 quando viene rilevata una condizione di errore.

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

2. In API, scegli l' PetStore API, quindi scegli Risorse.

3. Nella struttura Risorse, scegli il metodo GET in /{petId}.

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

5. Per petId immetti -1, quindi seleziona Test.

   Nei risultati, puoi notare due cose:

   Innanzitutto, il corpo della risposta indica un out-of-range errore:

   {
     "errors": [
       {
         "key": "GetPetRequest.petId",
         "message": "The value is out of range."
       }
     ]
   }

   In secondo luogo, l'ultima riga nella casella Log termina con: Method completed with status: 200.

6. Nella scheda Risposta di integrazione scegli Modifica per Predefinito - Risposta.

7. Scegli Modelli di mappatura.

8. Scegliere Add mapping template (Aggiungi modello di mappatura).

9. Per Tipo di contenuto inserisci application/json.

10. Per Corpo del modello inserisci quanto segue:

    #set($inputRoot = $input.path('$'))
    $input.json("$")
    #if($inputRoot.toString().contains("error"))
    #set($context.responseOverride.status = 400)
    #end

11. Selezionare Salva.

12. Seleziona la scheda Test.

13. Per petId immetti -1.

14. Nei risultati, il Response Body indica un out-of-range errore:

    {
      "errors": [
        {
          "key": "GetPetRequest.petId",
          "message": "The value is out of range."
        }
      ]
    }

    Tuttavia, l'ultima riga nella casella Logs (Log) termina ora con: Method completed with status: 400.

Tutorial: Sovrascrittura di parametri e intestazioni della richiesta di un'API con la console API Gateway

In questo tutorial, il codice di intestazione della richiesta del metodo GET verrà sovrascritto creando un modello di mappatura che associa $context.requestOverride.header.header_name a una nuova intestazione che combina due altre intestazioni.

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

2. In API, scegli l' PetStore API.

3. Nella struttura Risorse, scegli il metodo GET in /pet.

4. Nella scheda Richiesta metodo scegli Modifica in Impostazioni della richiesta del metodo.

5. Scegli Intestazioni di richiesta HTTP, quindi seleziona Aggiungi intestazione.

6. Per Nome, immetti header1.

7. Scegli Aggiungi intestazione, quindi crea una seconda intestazione chiamata header2.

8. Selezionare Salva.

9. Nella scheda Richiesta di integrazione seleziona Modifica per Impostazioni della richiesta di integrazione.

10. Per Richiesta corpo passthrough scegli Quando non ci sono modelli definiti (consigliato).

11. Scegli Modelli di mappatura e procedi come indicato di seguito:

    1. Scegliere Add mapping template (Aggiungi modello di mappatura).

    2. Per Tipo di contenuto inserisci application/json.

    3. Per Corpo del modello inserisci quanto segue:

       #set($header1Override = "foo")
       #set($header3Value = "$input.params('header1')$input.params('header2')")
       $input.json("$")
       #set($context.requestOverride.header.header3 = $header3Value)
       #set($context.requestOverride.header.header1 = $header1Override)
       #set($context.requestOverride.header.multivalueheader=[$header1Override, $header3Value])

12. Selezionare Salva.

13. Seleziona la scheda Test.

14. In Headers (Intestazioni) per {pets}, copiare il codice seguente:

    header1:header1Val
    header2:header2Val

15. Scegli Test (Esegui test).

    Nel log è presente una voce che include questo testo:

    Endpoint request headers: {header3=header1Valheader2Val, 
    header2=header2Val, header1=foo, x-amzn-apigateway-api-id=<api-id>,
    Accept=application/json, multivalueheader=foo,header1Valheader2Val}

Esempi: Sovrascrittura di parametri e intestazioni della richiesta di un'API con la CLI di API Gateway

Nell'esempio CLI seguente viene mostrato come utilizzare il comando put-integration per sovrascrivere un codice di risposta:

aws apigateway put-integration --rest-api-id <API_ID> --resource-id <PATH_TO_RESOURCE_ID> --http-method <METHOD> 
            --type <INTEGRATION_TYPE> --request-templates <REQUEST_TEMPLATE_MAP>

dove <REQUEST_TEMPLATE_MAP> è un mappa da tipo di contenuto a una stringa del modello da applicare. La struttura della mappa è la seguente:

Content_type1=template_string,Content_type2=template_string

oppure, nella sintassi JSON:

{"content_type1": "template_string"
...}

Nell'esempio seguente viene mostrato come utilizzare il comando put-integration-response per sovrascrivere il codice di risposta di un'API:

aws apigateway put-integration-response --rest-api-id <API_ID> --resource-id <PATH_TO_RESOURCE_ID> --http-method <METHOD> 
            --status-code <STATUS_CODE> --response-templates <RESPONSE_TEMPLATE_MAP>

dove <RESPONSE_TEMPLATE_MAP> è nello stesso formato di <REQUEST_TEMPLATE_MAP> sopra.

Esempio: sovrascrivi i parametri e le intestazioni di richiesta di un'API utilizzando l'SDK per JavaScript

Nell'esempio seguente viene mostrato come utilizzare il comando put-integration per sovrascrivere un codice di risposta:

Richiesta:

var params = {
  httpMethod: 'STRING_VALUE', /* required */
  resourceId: 'STRING_VALUE', /* required */
  restApiId: 'STRING_VALUE', /* required */
  type: HTTP | AWS | MOCK | HTTP_PROXY | AWS_PROXY, /* required */
  requestTemplates: {
    '<Content_type>': 'TEMPLATE_STRING',
    /* '<String>': ... */
  },
};
apigateway.putIntegration(params, function(err, data) {
  if (err) console.log(err, err.stack); // an error occurred
  else     console.log(data);           // successful response
});

Risposta:

var params = {
  httpMethod: 'STRING_VALUE', /* required */
  resourceId: 'STRING_VALUE', /* required */
  restApiId: 'STRING_VALUE', /* required */
  statusCode: 'STRING_VALUE', /* required */
  responseTemplates: {
    '<Content_type>': 'TEMPLATE_STRING',
    /* '<String>': ... */
  },
};
apigateway.putIntegrationResponse(params, function(err, data) {
  if (err) console.log(err, err.stack); // an error occurred
  else     console.log(data);           // successful response
});