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

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
  1. Accedere alla console API Gateway all'indirizzo https://console.aws.amazon.com/apigateway.

  2. Seleziona Create API (Crea API).

  3. Per API REST, scegliere Crea.

  4. Per Dettagli API, scegliere API di esempio.

  5. 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.

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

  7. 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.

  8. 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.

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

  10. Scegli Modelli di mappatura.

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

  12. Per Tipo di contenuto inserisci application/json.

  13. 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.

  14. Selezionare Salva.

  15. Seleziona la scheda Test.

  16. Per petId immetti -1.

  17. 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
  1. Accedere alla console API Gateway all'indirizzo https://console.aws.amazon.com/apigateway.

  2. Scegli l’API di esempio creata nel tutorial precedente. Il nome dell’API deve essere PetStore.

  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.

    Ora, si combinano queste intestazioni in un unico valore di intestazione utilizzando un modello di mappatura.

  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 = "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.

  12. Selezionare Salva.

  13. Seleziona la scheda Test.

  14. In Intestazioni, copiare il codice seguente:

    header1:header1Val header2:header2Val
  15. 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.