Esempio 1: sostituire il codice di stato in base al corpo di integrazione Esempio 2: sostituire l’intestazione della richiesta e creare nuove intestazioni

Sostituzione dei parametri della richiesta e della risposta e dei codici di stato per REST API in Gateway API

È possibile utilizzare le trasformazioni dei modelli di mappatura per sostituire qualsiasi tipo di parametro della richiesta, intestazione della risposta o codice di stato della risposta. Per utilizzare il modello di mappatura:

Eseguire mappature di parametri da molti a uno
Sostituire i parametri dopo l'applicazione delle mappature standard di Gateway API
Mappare i parametri in modo condizionale in base al contenuto del corpo o ad altri valori dei parametri
Creare nuovi parametri in modo programmatico
Sostituire i codici di stato restituiti dall'endpoint di integrazione

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, Gateway API restituisce una risposta 5XX. 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. Il modello viene applicato solo dopo che l'intero modello è stato analizzato.

Esempio 1: sostituire il codice di stato in base al corpo di integrazione

L’esempio seguente utilizza l’API di esempio per sostituire il codice di stato in base al corpo della risposta di integrazione.

AWS Management Console

Per sostituire un codice di stato in base al corpo della risposta di integrazione

Accedere alla console API Gateway all'indirizzo https://console.aws.amazon.com/apigateway.
Seleziona Create API (Crea API).
Per API REST, scegliere Crea.
Per Dettagli API, scegliere API di esempio.
Seleziona Create API (Crea API).

Gateway API crea un’API PetStore di esempio. Per recuperare le informazioni su un animale domestico, si utilizza la richiesta di metodo dell’API GET /pets/{petId}, dove {petId} è un parametro di percorso corrispondente al numero ID di un animale domestico.

In questo esempio, si sostituisce il codice di risposta del metodo GET con 400 quando viene rilevata una condizione di errore.
Nella struttura Risorse, scegli il metodo GET in /{petId}.
Innanzitutto, esegui il test dell’attuale implementazione dell’API.

Seleziona la scheda Test. Potrebbe essere necessario scegliere il pulsante freccia destra per visualizzare la scheda.
Per petId immetti -1, quindi seleziona Test.

Il Corpo risposta indica un errore non compreso nell’intervallo:
```
{
  "errors": [
    {
      "key": "GetPetRequest.petId",
      "message": "The value is out of range."
    }
  ]
}
```
Inoltre, l’ultima riga nella sezione Log termina con: Method completed with status: 200.

L’integrazione è stata completata, ma si è verificato un errore. Ora si sostituisce il codice di stato in base alla risposta di integrazione.
Nella scheda Risposta di integrazione scegli Modifica per Predefinito - Risposta.
Scegli Modelli di mappatura.
Scegliere Add mapping template (Aggiungi modello di mappatura).
Per Tipo di contenuto inserisci application/json.
Per Corpo del modello inserisci quanto segue:
```
#set($inputRoot = $input.path('$'))
$input.json("$")
#if($inputRoot.toString().contains("error"))
#set($context.responseOverride.status = 400)
#end
```
Questo modello di mappatura utilizza la variabile $context.responseOverride.status per sostituire il codice di stato con 400 se la risposta di integrazione contiene la stringa error.
Selezionare Salva.
Seleziona la scheda Test.
Per petId immetti -1.
Nei risultati, il Response Body (Corpo della risposta) indica un errore non compreso nell'intervallo:
```
{
  "errors": [
    {
      "key": "GetPetRequest.petId",
      "message": "The value is out of range."
    }
  ]
}
```
Tuttavia, l’ultima riga nella sezione Log termina ora con: Method completed with status: 400.

AWS CloudFormation

In questo esempio, si utilizza la proprietà body per importare un file di definizione OpenAPI in Gateway API.


AWSTemplateFormatVersion: 2010-09-09
Resources:
  Api:
    Type: 'AWS::ApiGateway::RestApi'
    Properties:
      Body: 
        openapi: 3.0.1
        info:
          title: PetStore Example 1
          description: Example pet store API.
          version: "2025-01-14T00:13:18Z"
        paths:
          /pets/{petId}:
            get:
              parameters:
                - name: petId
                  in: path
                  required: true
                  schema:
                    type: string
              responses:
                "200":
                  description: 200 response
              x-amazon-apigateway-integration:
                httpMethod: GET
                uri: http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets/{petId}
                responses:
                  default:
                    statusCode: "200"
                    responseTemplates:
                      application/json: |-
                        #set($inputRoot = $input.path('$'))
                        $input.json("$")
                        #if($inputRoot.toString().contains("error"))
                        #set($context.responseOverride.status = 400)
                        #end
                requestParameters:
                  integration.request.path.petId: method.request.path.petId
                passthroughBehavior: when_no_match
                type: http
        components:
          schemas:
            Pet:
              type: object
              properties:
                id:
                  type: integer
                type:
                  type: string
                price:
                  type: number
  ApiGatewayDeployment:
    Type: 'AWS::ApiGateway::Deployment'
    DependsOn: Api 
    Properties: 
      RestApiId: !Ref Api
  ApiGatewayDeployment20250219:
    Type: 'AWS::ApiGateway::Deployment'
    DependsOn: Api 
    Properties: 
      RestApiId: !Ref Api
  Stage:
    Type: 'AWS::ApiGateway::Stage'
    Properties:
       DeploymentId: !Ref ApiGatewayDeployment20250219
       RestApiId: !Ref Api
       StageName: prod

OpenAPI

La seguente definizione OpenAPI crea la risorsa GET pets/{petId} e sostituisce il codice di stato in base al corpo di integrazione.


{
  "openapi" : "3.0.1",
  "info" : {
    "title" : "PetStore Example 1",
    "description" : "Example pet store API.",
    "version" : "2025-01-14T00:13:18Z"
  },
  "paths" : {
    "/pets/{petId}" : {
      "get" : {
        "parameters" : [ {
          "name" : "petId",
          "in" : "path",
          "required" : true,
          "schema" : {
            "type" : "string"
          }
        } ],
        "responses" : {
          "200" : {
            "description" : "200 response"
          }
        },
        "x-amazon-apigateway-integration" : {
          "httpMethod" : "GET",
          "uri" : "http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets/{petId}",
          "responses" : {
            "default" : {
              "statusCode" : "200",
              "responseTemplates" : {
                "application/json" : "#set($inputRoot = $input.path('$'))\n$input.json(\"$\")\n#if($inputRoot.toString().contains(\"error\"))\n#set($context.responseOverride.status = 400)\n#end"
              }
            }
          },
          "requestParameters" : {
            "integration.request.path.petId" : "method.request.path.petId"
          },
          "passthroughBehavior" : "when_no_match",
          "type" : "http"
        }
      }
    }
  },
  "components" : {
    "schemas" : {
      "Pet" : {
        "type" : "object",
        "properties" : {
          "id" : {
            "type" : "integer"
          },
          "type" : {
            "type" : "string"
          },
          "price" : {
            "type" : "number"
          }
        }
      }
    }
  }
}

Esempio 2: sostituire l’intestazione della richiesta e creare nuove intestazioni

L’esempio seguente utilizza l’API di esempio per sostituire l’intestazione della richiesta e creare nuove intestazioni.

AWS Management Console

Per sostituire un’intestazione della richiesta di metodo creando una nuova intestazione

Accedere alla console API Gateway all'indirizzo https://console.aws.amazon.com/apigateway.
Scegli l’API di esempio creata nel tutorial precedente. Il nome dell’API deve essere PetStore.
Nella struttura Risorse, scegli il metodo GET in /pet.
Nella scheda Richiesta metodo scegli Modifica in Impostazioni della richiesta del metodo.
Scegli Intestazioni di richiesta HTTP, quindi seleziona Aggiungi intestazione.
Per Nome, immetti header1.
Scegli Aggiungi intestazione, quindi crea una seconda intestazione chiamata header2.
Selezionare Salva.

Ora, si combinano queste intestazioni in un unico valore di intestazione utilizzando un modello di mappatura.
Nella scheda Richiesta di integrazione seleziona Modifica per Impostazioni della richiesta di integrazione.
Per Richiesta corpo passthrough scegli Quando non ci sono modelli definiti (consigliato).
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 = "pets")
#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])
```
  Questo modello di mappatura sostituisce header1 con la stringa pets e crea un’intestazione con più valori chiamata $header3Value che combina header1 e header2.
Selezionare Salva.
Seleziona la scheda Test.
In Intestazioni, copiare il codice seguente:
```
header1:header1Val
header2:header2Val
```

Scegli Test (Esegui test).

Nella sezione Log è presente una voce che include questo testo:


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

AWS CloudFormation

In questo esempio, si utilizza la proprietà body per importare un file di definizione OpenAPI in Gateway API.


AWSTemplateFormatVersion: 2010-09-09
Resources:
  Api:
    Type: 'AWS::ApiGateway::RestApi'
    Properties:
      Body: 
        openapi: 3.0.1
        info:
          title: PetStore Example 2
          description: Example pet store API.
          version: "2025-01-14T00:36:18Z"
        paths:
          /pets:
            get:
              parameters:
                - name: header2
                  in: header
                  schema:
                    type: string
                - name: page
                  in: query
                  schema:
                    type: string
                - name: type
                  in: query
                  schema:
                    type: string
                - name: header1
                  in: header
                  schema:
                    type: string
              responses:
                "200":
                  description: 200 response
              x-amazon-apigateway-integration:
                httpMethod: GET
                uri: http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets
                responses:
                  default:
                    statusCode: "200"
                requestParameters:
                  integration.request.header.header1: method.request.header.header1
                  integration.request.header.header2: method.request.header.header2
                  integration.request.querystring.page: method.request.querystring.page
                  integration.request.querystring.type: method.request.querystring.type
                requestTemplates:
                  application/json: |-
                    #set($header1Override = "pets")
                    #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])
                passthroughBehavior: when_no_match
                type: http
        components:
          schemas:
            Pet:
              type: object
              properties:
                id:
                  type: integer
                type:
                  type: string
                price:
                  type: number
  ApiGatewayDeployment:
    Type: 'AWS::ApiGateway::Deployment'
    DependsOn: Api 
    Properties: 
      RestApiId: !Ref Api
  ApiGatewayDeployment20250219:
    Type: 'AWS::ApiGateway::Deployment'
    DependsOn: Api 
    Properties: 
      RestApiId: !Ref Api
  Stage:
    Type: 'AWS::ApiGateway::Stage'
    Properties:
       DeploymentId: !Ref ApiGatewayDeployment20250219
       RestApiId: !Ref Api
       StageName: prod

OpenAPI

La seguente definizione OpenAPI crea la risorsa GET pets, sostituisce l’intestazione della richiesta e crea nuove intestazioni.


{
  "openapi" : "3.0.1",
  "info" : {
    "title" : "PetStore Example 2",
    "description" : "Example pet store API.",
    "version" : "2025-01-14T00:36:18Z"
  },
  "paths" : {
    "/pets" : {
      "get" : {
        "parameters" : [ {
          "name" : "header2",
          "in" : "header",
          "schema" : {
            "type" : "string"
          }
        }, {
          "name" : "page",
          "in" : "query",
          "schema" : {
            "type" : "string"
          }
        }, {
          "name" : "type",
          "in" : "query",
          "schema" : {
            "type" : "string"
          }
        }, {
          "name" : "header1",
          "in" : "header",
          "schema" : {
            "type" : "string"
          }
        } ],
        "responses" : {
          "200" : {
            "description" : "200 response"
          }
        },
        "x-amazon-apigateway-integration" : {
          "httpMethod" : "GET",
          "uri" : "http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets",
          "responses" : {
            "default" : {
              "statusCode" : "200"
            }
          },
          "requestParameters" : {
            "integration.request.header.header1" : "method.request.header.header1",
            "integration.request.header.header2" : "method.request.header.header2",
            "integration.request.querystring.page" : "method.request.querystring.page",
            "integration.request.querystring.type" : "method.request.querystring.type"
          },
          "requestTemplates" : {
            "application/json" : "#set($header1Override = \"pets\")\n#set($header3Value = \"$input.params('header1')$input.params('header2')\")\n$input.json(\"$\")\n#set($context.requestOverride.header.header3 = $header3Value)\n#set($context.requestOverride.header.header1 = $header1Override)\n#set($context.requestOverride.header.multivalueheader=[$header1Override, $header3Value])"
          },
          "passthroughBehavior" : "when_no_match",
          "type" : "http"
        }
      }
    }
  }
}

Per utilizzare la sostituzione di un modello di mappatura, si aggiunge una o più delle seguenti variabili $context. Per l’elenco delle variabili $context, consultare Variabili di contesto per le trasformazioni dei dati.

Avvertimento JavaScript è disabilitato o non è disponibile nel tuo browser.

Per usare la documentazione AWS, JavaScript deve essere abilitato. Consulta le pagine della guida del browser per le istruzioni.

Convenzioni dei documenti

Esempio aggiuntivo di modello di mappatura

Tutorial: modificare la richiesta e la risposta di integrazione per le integrazioni ai servizi AWS