$contextVariablen für Datenmodelle, Autorisierer, Zuordnungsvorlagen und CloudWatch Zugriffsprotokollierung Beispiel für $context-Variablenvorlage $context-Variablen nur für Zugriffsprotokollierung $input-Variablen Beispiele für $input-Variablenvorlage $stageVariables $util-Variablen

APIVorlage für die Gateway-Zuordnung und Referenz für die Zugriffsprotokollierung

Dieser Abschnitt enthält Referenzinformationen für die Variablen und Funktionen, die Amazon API Gateway für die Verwendung mit Datenmodellen, Autorisierern, Zuordnungsvorlagen und CloudWatch Zugriffsprotokollierung definiert. Detaillierte Informationen zur Verwendung dieser Variablen und Funktionen finden Sie unter Zuordnungsvorlagen für REST APIs. Weitere Informationen zur Velocity Template Language (VTL) finden Sie in der VTL Referenz.

Themen

$contextVariablen für Datenmodelle, Autorisierer, Zuordnungsvorlagen und CloudWatch Zugriffsprotokollierung
Beispiel für $context-Variablenvorlage
$context-Variablen nur für Zugriffsprotokollierung
$input-Variablen
Beispiele für $input-Variablenvorlage
$stageVariables
$util-Variablen

Anmerkung

Weitere Informationen zu $method- und $integration-Variablen finden Sie unter Referenz zur Zuordnung von Amazon API API Gateway-Anforderungs- und Antwortdaten.

`$context`Variablen für Datenmodelle, Autorisierer, Zuordnungsvorlagen und CloudWatch Zugriffsprotokollierung

Die folgenden $context Variablen können in Datenmodellen, Autorisierern, Zuordnungsvorlagen und der Zugriffsprotokollierung verwendet werden. CloudWatch APIGateway fügt möglicherweise zusätzliche Kontextvariablen hinzu.

Informationen zu $context Variablen, die nur für die CloudWatch Zugriffsprotokollierung verwendet werden können, finden Sie unter$context-Variablen nur für Zugriffsprotokollierung.

Parameter	Beschreibung
`$context.accountId`	Die AWS Konto-ID des API Besitzers.
`$context.apiId`	Die Kennung, die API Gateway Ihrem API zuweist.
`$context.authorizer.claims.property`	Eine Eigenschaft der Claims, die aus dem Amazon Cognito-Benutzerpool zurückgegeben werden, nachdem der Methodenaufrufer erfolgreich authentifiziert wurde. Weitere Informationen finden Sie unter Steuern Sie den Zugriff auf REST-APIs mithilfe von Amazon Cognito Cognito-Benutzerpools als Autorisierer. Anmerkung Bei einem Aufruf von `$context.authorizer.claims` wird null (0) zurückgegeben.
`$context.authorizer.principalId`	Die Hauptbenutzeridentifikation, die dem vom Client gesendeten und von einem API Gateway-Lambda-Autorisierer (früher als benutzerdefinierter Autorisierer bezeichnet) zurückgegebenen Token zugeordnet ist. Weitere Informationen finden Sie unter Verwenden Sie API Gateway Lambda-Autorisierer.
`$context.authorizer.property`	Der stringifizierte Wert des angegebenen Schlüssel-Wert-Paares der `context` Map, der von einer API Gateway-Lambda-Autorisierungsfunktion zurückgegeben wurde. Angenommen, der Genehmiger gibt folgende `context`-Zuweisung zurück: `"context" : { "key": "value", "numKey": 1, "boolKey": true }` Beim Aufrufen wird die `"value"` Zeichenfolge `$context.authorizer.key` zurückgegeben, beim Aufrufen wird die Zeichenfolge `$context.authorizer.numKey` zurückgegeben, und beim Aufrufen wird die `"1"` Zeichenfolge zurückgegeben. `$context.authorizer.boolKey` `"true"` Wählen Sie in der &Snowconsole; Ihren Auftrag aus der Tabelle. `property`, das einzige unterstützte Sonderzeichen ist der `(_)` Unterstrich. Weitere Informationen finden Sie unter Verwenden Sie API Gateway Lambda-Autorisierer.
`$context.awsEndpointRequestId`	Die Anforderungs-ID des AWS Endpunkts.
`$context.deploymentId`	Die ID der API Bereitstellung.
`$context.domainName`	Der vollständige Domänenname, der zum Aufrufen von verwendet wurde. API Dieser Wert sollte mit dem für den eingehenden `Host`-Header übereinstimmen.
`$context.domainPrefix`	Das erste Label der `$context.domainName`.
`$context.error.message`	Eine Zeichenfolge, die eine API Gateway-Fehlermeldung enthält. Diese Variable kann nur für die einfache Variablenersetzung in einer GatewayResponseBody-Mapping-Vorlage, die nicht von der Velocity Template Language-Engine verarbeitet wird, und für die Zugriffsprotokollierung verwendet werden. Weitere Informationen erhalten Sie unter Überwachen Sie WebSocket API die Ausführung mit CloudWatch Metriken und Einrichten von Gateway-Antworten, um Fehlerantworten anzupassen.
`$context.error.messageString`	Die Wert von `$context.error.message` in Anführungszeichen, d. h. `"$context.error.message"`.
`$context.error.responseType`	Ein Typ von. GatewayResponse Diese Variable kann nur für die einfache Variablenersetzung in einer GatewayResponseBody-Mapping-Vorlage, die nicht von der Velocity Template Language-Engine verarbeitet wird, und für die Zugriffsprotokollierung verwendet werden. Weitere Informationen erhalten Sie unter Überwachen Sie WebSocket API die Ausführung mit CloudWatch Metriken und Einrichten von Gateway-Antworten, um Fehlerantworten anzupassen.
`$context.error.validationErrorString`	Eine Zeichenfolge mit einer detaillierten Validierungs-Fehlermeldung.
`$context.extendedRequestId`	Die erweiterte ID, die API Gateway generiert und der Anfrage zuweist. API Die erweiterte Anforderungs-ID enthält zusätzliche nützliche Informationen für Debugging und Fehlerbehebung.
`$context.httpMethod`	Die verwendete HTTP Methode. Gültige Werte sind: `DELETE`, `GET`, `HEAD`, `OPTIONS`, `PATCH`, `POST` und `PUT`.
`$context.identity.accountId`	Die der Anfrage zugeordnete AWS Konto-ID.
`$context.identity.apiKey`	Bei API Methoden, die einen API Schlüssel benötigen, ist diese Variable der API Schlüssel, der der Methodenanforderung zugeordnet ist. Für Methoden, die keinen API Schlüssel benötigen, ist diese Variable Null. Weitere Informationen finden Sie unter Nutzungspläne und API Schlüssel für REST APIs in API Gateway .
`$context.identity.apiKeyId`	Die API Schlüssel-ID, die einer API Anfrage zugeordnet ist, für die ein API Schlüssel erforderlich ist.
`$context.identity.caller`	Die Hauptkennung des Aufrufers, der die Anforderung signiert hat. Wird für Ressourcen unterstützt, die IAM Autorisierung verwenden.
`$context.identity.cognitoAuthenticationProvider`	Eine durch Kommas getrennte Liste aller Amazon Cognito Cognito-Authentifizierungsanbieter, die von dem Anrufer verwendet werden, der die Anfrage stellt. Nur verfügbar, wenn die Anfrage mit Anmeldeinformationen von Amazon Cognito signiert wurde. Zum Beispiel für eine Identität aus einem Amazon Cognito-Benutzerpool, `cognito-idp. region.amazonaws.com/user_pool_id,cognito-idp.region.amazonaws.com/user_pool_id:CognitoSignIn:token subject claim` Informationen zu den verfügbaren Amazon Cognito-Authentifizierungsanbietern finden Sie unter Using Federated Identities im Amazon Cognito Developer Guide.
`$context.identity.cognitoAuthenticationType`	Der Amazon Cognito-Authentifizierungstyp des Aufrufers, der den Anfrage erstellt hat. Nur verfügbar, wenn die Anfrage mit Anmeldeinformationen von Amazon Cognito signiert wurde. Mögliche Werte sind `authenticated` für authentifizierte Identitäten und `unauthenticated` für nicht authentifizierte Identitäten.
`$context.identity.cognitoIdentityId`	Die Amazon Cognito Identitäts-ID des anfordernden Aufrufers. Nur verfügbar, wenn die Anfrage mit Anmeldeinformationen von Amazon Cognito signiert wurde.
`$context.identity.cognitoIdentityPoolId`	Die Amazon Cognito Identitätspool-ID des anfordernden Aufrufers. Nur verfügbar, wenn die Anfrage mit Anmeldeinformationen von Amazon Cognito signiert wurde.
`$context.identity.principalOrgId`	Die AWS -Organisations-ID.
`$context.identity.sourceIp`	Die Quell-IP-Adresse der unmittelbaren TCP Verbindung, die die Anfrage an den Gateway-Endpunkt stellt. API
`$context.identity.clientCert.clientCertPem`	Das PEM -kodierte Client-Zertifikat, das der Client bei der gegenseitigen TLS Authentifizierung vorgelegt hat. Vorhanden, wenn ein Client API mithilfe eines benutzerdefinierten Domänennamens, für den die Option Mutual aktiviert ist, auf eine zugreift. TLS Nur in Zugriffsprotokollen vorhanden, wenn die gegenseitige TLS Authentifizierung fehlschlägt.
`$context.identity.clientCert.subjectDN`	Der Distinguished Name des Zertifikatantragsstellers, den ein Client präsentiert. Ist vorhanden, wenn ein Client API mithilfe eines benutzerdefinierten Domänennamens, für den Mutual TLS aktiviert ist, auf einen zugreift. Nur in Zugriffsprotokollen vorhanden, wenn die gegenseitige TLS Authentifizierung fehlschlägt.
`$context.identity.clientCert.issuerDN`	Der Distinguished Name des Ausstellers des Zertifikats, das ein Client präsentiert. Ist vorhanden, wenn ein Client API mithilfe eines benutzerdefinierten Domänennamens, für den Mutual TLS aktiviert ist, auf einen zugreift. Nur in Zugriffsprotokollen vorhanden, wenn die gegenseitige TLS Authentifizierung fehlschlägt.
`$context.identity.clientCert.serialNumber`	Die Seriennummer des Zertifikats. Ist vorhanden, wenn ein Client API mithilfe eines benutzerdefinierten Domänennamens, für den Mutual TLS aktiviert ist, auf einen zugreift. Nur in Zugriffsprotokollen vorhanden, wenn die gegenseitige TLS Authentifizierung fehlschlägt.
`$context.identity.clientCert.validity.notBefore`	Das Datum, vor dem das Zertifikat ungültig ist. Ist vorhanden, wenn ein Client API mithilfe eines benutzerdefinierten Domänennamens, für den Mutual TLS aktiviert ist, auf einen zugreift. Nur in Zugriffsprotokollen vorhanden, wenn die gegenseitige TLS Authentifizierung fehlschlägt.
`$context.identity.clientCert.validity.notAfter`	Das Datum, nach dem das Zertifikat ungültig ist. Ist vorhanden, wenn ein Client API mithilfe eines benutzerdefinierten Domänennamens, für den Mutual TLS aktiviert ist, auf einen zugreift. Nur in Zugriffsprotokollen vorhanden, wenn die gegenseitige TLS Authentifizierung fehlschlägt.
`$context.identity.vpcId`	Die VPC ID der Person, die die Anfrage an den API Gateway-Endpunkt VPC stellt.
`$context.identity.vpceId`	Die VPC Endpunkt-ID des VPC Endpunkts, der die Anfrage an den API Gateway-Endpunkt stellt. Nur vorhanden, wenn Sie eine private habenAPI.
`$context.identity.user`	Die Hauptkennung des Benutzers, der für den Ressourcenzugriff autorisiert wird. Wird für Ressourcen unterstützt, die IAM Autorisierung verwenden.
`$context.identity.userAgent`	Der `User-Agent`Header des API Aufrufers.
`$context.identity.userArn`	Der Amazon-Ressourcenname (ARN) des effektiven Benutzers, der nach der Authentifizierung identifiziert wurde. Weitere Informationen finden Sie unter https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html.
`$context.isCanaryRequest`	Gibt zurück`true`, ob die Anfrage an den Canary gerichtet war und `false` ob die Anfrage nicht an den Canary gerichtet war. Nur vorhanden, wenn Sie einen Canary aktiviert haben.
`$context.path`	Der Anforderungspfad. Für eine Nicht-Proxy-Anfrage URL von `https://{rest-api-id}.execute-api.{region}.amazonaws.com/{stage}/root/child` lautet `/{stage}/root/child` der `$context.path` Wert beispielsweise.
`$context.protocol`	Das Anforderungsprotokoll ist z. B, `HTTP/1.1`. Anmerkung APIGateway APIs kann HTTP /2-Anfragen annehmen, aber API Gateway sendet Anfragen mit /1.1 an Backend-Integrationen. HTTP Daher wird das Anforderungsprotokoll auch dann als HTTP /1.1 protokolliert, wenn ein Client eine Anfrage sendet, die /2 verwendet. HTTP
`$context.requestId`	Eine ID für die Anforderung. Clients können diese Anforderungs-ID überschreiben. Wird `$context.extendedRequestId` für eine eindeutige Anforderungs-ID verwendet, die API Gateway generiert.
`$context.requestOverride.header.header_name`	Der Anforderungs-Header-Override. Wenn dieser Parameter definiert ist, enthält er die Header, die anstelle der HTTPHeader verwendet werden sollen, die im Bereich Integrationsanforderung definiert sind. Weitere Informationen finden Sie unter Verwenden Sie eine Zuordnungsvorlage, um die Anfrage- und Antwortparameter und Statuscodes eines API Benutzers zu überschreiben.
`$context.requestOverride.path.path_name`	Der Anforderungspfad-Override. Wenn dieser Parameter definiert ist, enthält er den zu verwendenden Anforderungspfad anstelle der URLPfadparameter, die im Bereich Integrationsanforderung definiert sind. Weitere Informationen finden Sie unter Verwenden Sie eine Zuordnungsvorlage, um die Anfrage- und Antwortparameter und Statuscodes eines API Benutzers zu überschreiben.
`$context.requestOverride.querystring.querystring_name`	Der Abfragestring-Override. Wenn dieser Parameter definiert ist, enthält er die Anforderungsabfragezeichenfolgen, die anstelle der im Bereich Integrationsanforderung definierten URLAbfragezeichenfolgenparameter verwendet werden sollen. Weitere Informationen finden Sie unter Verwenden Sie eine Zuordnungsvorlage, um die Anfrage- und Antwortparameter und Statuscodes eines API Benutzers zu überschreiben.
`$context.responseOverride.header.header_name`	Der Antwort-Header-Override. Wenn dieser Parameter definiert ist, enthält er den Header, der anstelle des Antwort-Headers, der als Standard-Mapping im Bereich Integrationsantwort definiert ist, ausgegeben werden soll. Weitere Informationen finden Sie unter Verwenden Sie eine Zuordnungsvorlage, um die Anfrage- und Antwortparameter und Statuscodes eines API Benutzers zu überschreiben.
`$context.responseOverride.status`	Der Antwortstatuscode-Override. Wenn dieser Parameter definiert ist, enthält er den Statuscode, der anstelle des Methoden-Antwortstatus, der als Standard-Mapping im Bereich Integrationsantwort definiert ist, ausgegeben werden soll. Weitere Informationen finden Sie unter Verwenden Sie eine Zuordnungsvorlage, um die Anfrage- und Antwortparameter und Statuscodes eines API Benutzers zu überschreiben.
`$context.requestTime`	Die Uhrzeit der Anfrage CLFim -Format ()`dd/MMM/yyyy:HH:mm:ss +-hhmm`.
`$context.requestTimeEpoch`	Die Anforderungszeit im Epoch-Format in Millisekunden.
`$context.resourceId`	Die Kennung, die API Gateway Ihrer Ressource zuweist.
`$context.resourcePath`	Der Pfad zu Ihrer Ressource. Für die Nicht-Proxy-Anfrage URI von lautet der `https://{rest-api-id}.execute-api.{region}.amazonaws.com/{stage}/root/child` `$context.resourcePath` Wert beispielsweise. `/root/child` Weitere Informationen finden Sie unter Tutorial: Erstellen Sie eine REST API mit einer HTTP Nicht-Proxy-Integration.
`$context.stage`	Die Bereitstellungsphase der API Anfrage (z. B. `Beta` oder`Prod`).
`$context.wafResponseCode`	Die von AWS WAF empfangene Antwort: `WAF_ALLOW` oder `WAF_BLOCK`. Wird nicht festgelegt, wenn die Phase nicht mit einem Web verknüpft istACL. Weitere Informationen finden Sie unter Verwenden Sie AWS WAF , um Ihre REST-APIs in API Gateway zu schützen.
`$context.webaclArn`	Das komplette ARN WebACL, anhand dessen entschieden wird, ob die Anfrage zugelassen oder blockiert werden soll. Wird nicht gesetzt, wenn die Bühne keinem Web zugeordnet istACL. Weitere Informationen finden Sie unter Verwenden Sie AWS WAF , um Ihre REST-APIs in API Gateway zu schützen.

Beispiel für `$context`-Variablenvorlage

Möglicherweise möchten Sie $context Variablen in einer Mapping-Vorlage verwenden, wenn Ihre API Methode strukturierte Daten an ein Back-End weitergibt, das verlangt, dass die Daten in einem bestimmten Format vorliegen.

Das folgende Beispiel zeigt eine Mapping-Vorlage für die Zuordnung eingehender $context Variablen zu Backend-Variablen mit geringfügig unterschiedlichen Namen in der Nutzlast einer Integrationsanforderung:

Anmerkung

Eine der Variablen ist ein API Schlüssel. In diesem Beispiel wird davon ausgegangen, dass die Methode einen API Schlüssel benötigt.


{
    "stage" : "$context.stage",
    "request_id" : "$context.requestId",
    "api_id" : "$context.apiId",
    "resource_path" : "$context.resourcePath",
    "resource_id" : "$context.resourceId",
    "http_method" : "$context.httpMethod",
    "source_ip" : "$context.identity.sourceIp",
    "user-agent" : "$context.identity.userAgent",
    "account_id" : "$context.identity.accountId",
    "api_key" : "$context.identity.apiKey",
    "caller" : "$context.identity.caller",
    "user" : "$context.identity.user",
    "user_arn" : "$context.identity.userArn"
}

Die Ausgabe dieser Mapping-Vorlage sollte wie folgt aussehen:


{
  stage: 'prod',
  request_id: 'abcdefg-000-000-0000-abcdefg',
  api_id: 'abcd1234',
  resource_path: '/',
  resource_id: 'efg567',
  http_method: 'GET',
  source_ip: '192.0.2.1',
  user-agent: 'curl/7.84.0',
  account_id: '111122223333',
  api_key: 'MyTestKey',
  caller: 'ABCD-0000-12345',
  user: 'ABCD-0000-12345',
  user_arn: 'arn:aws:sts::111122223333:assumed-role/Admin/carlos-salazar'
}

`$context`-Variablen nur für Zugriffsprotokollierung

Die folgenden $context-Variablen sind nur für Zugriffsprotokollierung verfügbar. Weitere Informationen finden Sie unter CloudWatch Logging für REST APIs in API Gateway einrichten. ( WebSocket APIsNäheres dazu finden Sie unterÜberwachen Sie WebSocket API die Ausführung mit CloudWatch Metriken.)

Parameter	Beschreibung
`$context.authorize.error`	Die Autorisierungsfehlermeldung.
`$context.authorize.latency`	Die Autorisierungslatenz in ms
`$context.authorize.status`	Der Statuscode, der von einem Autorisierungsversuch zurückgegeben wurde.
`$context.authorizer.error`	Die von einem Genehmiger zurückgegebene Fehlermeldung.
`$context.authorizer.integrationLatency`	Die Latenz der Authorizer-Integration in ms.
`$context.authorizer.integrationStatus`	Der von einem Lambda-Genehmiger zurückgegebene Statuscode.
`$context.authorizer.latency`	Der Genehmiger-Latenz in ms.
`$context.authorizer.requestId`	Die Anforderungs-ID des AWS Endpunkts.
`$context.authorizer.status`	Der von einem Genehmiger zurückgegebene Statuscode.
`$context.authenticate.error`	Die von einem Authentifizierungsversuch zurückgegebene Fehlermeldung.
`$context.authenticate.latency`	Die Authentifizierungslatenz in ms
`$context.authenticate.status`	Der Statuscode, der von einem Authentifizierungsversuch zurückgegeben wurde.
`$context.customDomain.basePathMatched`	Der Pfad für ein API Mapping, dem eine eingehende Anfrage entsprach. Anwendbar, wenn ein Client einen benutzerdefinierten Domänennamen für den Zugriff auf einen verwendetAPI. Wenn ein Client beispielsweise eine Anfrage an `https://api.example.com/v1/orders/1234` sendet und die Anfrage der API Zuordnung dem Pfad entspricht`v1/orders`, lautet der Wert`v1/orders`. Weitere Informationen hierzu finden Sie unter APIOrdnen Sie Stufen einem benutzerdefinierten Domainnamen zu für REST APIs.
`$context.endpointType`	Der Endpunkttyp vonAPI.
`$context.integration.error`	Die von einer Integration zurückgegebene Fehlermeldung.
`$context.integration.integrationStatus`	Bei der Lambda-Proxyintegration wurde der Statuscode vom Lambda-Funktionscode zurückgegeben AWS Lambda, nicht vom Backend-Funktionscode.
`$context.integration.latency`	Die Integrationslatenz in Millisekunden. Äquivalent mit `$context.integrationLatency`.
`$context.integration.requestId`	Die AWS Anforderungs-ID des Endpunkts. Äquivalent mit `$context.awsEndpointRequestId`.
`$context.integration.status`	Der von einer Integration zurückgegebene Statuscode. Bei Lambda-Proxy-Integrationen ist dies der Statuscode, der von Ihrem Lambda-Funktionscode zurückgegeben wird.
`$context.integrationLatency`	Die Integrationslatenz in Millisekunden.
`$context.integrationStatus`	Für die Lambda-Proxyintegration stellt dieser Parameter den Statuscode dar, der vom Lambda-Funktionscode zurückgegeben wurde AWS Lambda, nicht aus dem Back-End-Lambda-Funktionscode.
`$context.responseLatency`	Die Antwortlatenz in Millisekunden.
`$context.responseLength`	Die Länge der Antwortnutzlast in Byte.
`$context.status`	Der Status der Methodenantwort.
`$context.waf.error`	Die Fehlermeldung wurde von zurückgegeben. AWS WAF
`$context.waf.latency`	Die AWS WAF Latenz in ms.
`$context.waf.status`	Der Statuscode wurde von zurückgegeben AWS WAF.
`$context.xrayTraceId`	Die Trace-ID für die X-Ray-Trace. Weitere Informationen finden Sie unter AWS X-Ray Mit API-Gateway-REST-APIs einrichten.

`$input`-Variablen

Die $input-Variable stellt die Nutzlast und die Parameter der Methodenanforderung dar, die von der Mapping-Vorlage verarbeitet werden sollen. Er bietet die folgenden Funktionen:

Variable und Funktion	Beschreibung
`$input.body`	Gibt die Nutzlast der Raw-Anforderung als Zeichenfolge zurück. Sie können `$input.body` es verwenden, um ganze Fließkommazahlen beizubehalten, wie `10.00` z.
`$input.json(x)`	Diese Funktion wertet einen JSONPath Ausdruck aus und gibt die Ergebnisse als JSON Zeichenfolge zurück. Gibt beispielsweise eine JSON Zeichenfolge `$input.json('$.pets')` zurück, die die `pets` Struktur darstellt. Weitere Informationen zu JSONPath Java finden Sie unter JSONPathoder JSONPathfür Java.
`$input.params()`	Gibt die Zuweisung aller Anforderungsparameter zurück. Wir empfehlen, das Ergebnis `$util.escapeJavaScript` zu bereinigen, um einen möglichen Injektionsangriff zu vermeiden. Um die vollständige Kontrolle über die Bereinigung von Anfragen zu erhalten, verwenden Sie eine Proxy-Integration ohne Vorlage und übernehmen Sie die Anforderungsbereinigung in Ihrer Integration.
`$input.params(x)`	Gibt aus der Zeichenfolge eines Parameternamens `x` aus dem Pfad, der Abfragezeichenfolge oder dem Header-Wert (in dieser Reihenfolge) den Wert eines Methodenanforderungs-Parameters zurück. Wir empfehlen, den Parameter `$util.escapeJavaScript` zu bereinigen, um einen möglichen Injektionsangriff zu vermeiden. Um die vollständige Kontrolle über die Parameterbereinigung zu erhalten, verwenden Sie eine Proxy-Integration ohne Vorlage und übernehmen Sie die Anforderungsbereinigung in Ihrer Integration.
`$input.path(x)`	Nimmt einen JSONPath Ausdruck string (`x`) und gibt eine JSON Objektdarstellung des Ergebnisses zurück. Auf diese Weise können Sie nativ in der Apache Velocity Template Language () VTL auf Elemente der Payload zugreifen und diese bearbeiten. Beispiel: Der Ausdruck `$input.path('$.pets')` könnte das folgende Objekt zurückgeben: `[ { "id": 1, "type": "dog", "price": 249.99 }, { "id": 2, "type": "cat", "price": 124.99 }, { "id": 3, "type": "fish", "price": 0.99 } ]` `$input.path('$.pets').size()` gibt `"3"` zurück. Weitere Informationen zu Java finden Sie JSONPath unter JSONPathoder JSONPathfür Java.

Beispiele für `$input`-Variablenvorlage

Die folgenden Beispiele zeigen, wie die $input Variablen in Mapping-Vorlagen verwendet werden. Sie können eine Scheinintegration oder eine Lambda-Integration ohne Proxy verwenden, die das Eingabeereignis zurück an API Gateway zurückgibt, um diese Beispiele auszuprobieren.

Beispiel für Parameter-Mapping-Vorlage

Im folgenden Beispiel werden alle Anforderungsparameter, einschließlich, und path querystringheader, über eine JSON Nutzlast an den Integrationsendpunkt übergeben:


#set($allParams = $input.params())
{
  "params" : {
    #foreach($type in $allParams.keySet())
    #set($params = $allParams.get($type))
    "$type" : {
      #foreach($paramName in $params.keySet())
      "$paramName" : "$util.escapeJavaScript($params.get($paramName))"
      #if($foreach.hasNext),#end
      #end
    }
    #if($foreach.hasNext),#end
    #end
  }
}

Für eine Anfrage, die die folgenden Eingabeparameter enthält:

Ein Pfadparameter mit dem Namen myparam
Zeichenkettenparameter abfragen querystring1=value1,value2&querystring2=value3
Überschriften "header1" : "value1""header2" : "value2","header3" : "value3".

Die Ausgabe dieser Mapping-Vorlage sollte wie folgt aussehen:


{
  "params" : {
        "path" : {
            "path" : "myparam"
                }
    ,        "querystring" : {
            "querystring1" : "value1,value2"
      ,            "querystring2" : "value3"
                }
    ,        "header" : {
            "header3" : "value3"
      ,            "header2" : "value2"
      ,            "header1" : "value1"
                }
          }
}

JSONBeispiel für eine Zuordnungsvorlage

Sie können die $input-Variable verwenden, um Abfragezeichenfolgen und Anforderungstext mit oder ohne die Verwendung von Modellen abzurufen. Möglicherweise möchten Sie auch den Parameter und die Payload oder einen Unterabschnitt der Payload abrufen. Die folgenden drei Beispiele zeigen, wie das geht.

Im folgenden Beispiel wird eine Zuordnungsvorlage verwendet, um einen Unterabschnitt der Nutzlast abzurufen. In diesem Beispiel werden der Eingabeparameter name und dann der gesamte POST Text abgerufen:


{
    "name" : "$input.params('name')",
    "body" : $input.json('$') 
}

Für eine Anfrage, die die Parameter der Abfragezeichenfolge name=Bella&type=dog und den folgenden Hauptteil enthält:


{
    "Price" : "249.99",
    "Age": "6"
}

Die Ausgabe dieser Zuordnungsvorlage sollte wie folgt aussehen:


{
    "name" : "Bella",
    "body" : {"Price":"249.99","Age":"6"}
}

Wenn die JSON Eingabe Zeichen ohne Escape-Zeichen enthält, die nicht analysiert werden können JavaScript, gibt API Gateway möglicherweise eine 400-Antwort zurück. $util.escapeJavaScript($input.json('$'))Anwenden, um sicherzustellen, dass die JSON Eingabe ordnungsgemäß analysiert werden kann.

Das vorherige Beispiel mit $util.escapeJavaScript($input.json('$')) Applied lautet wie folgt:


{
    "name" : "$input.params('name')",
    "body" : $util.escapeJavaScript($input.json('$'))
}

In diesem Fall sollte die Ausgabe dieser Mapping-Vorlage wie folgt aussehen:


{
    "name" : "Bella",
    "body": {\"Price\":\"249.99\",\"Age\":\"6\"}
}

JSONPathBeispiel für einen Ausdruck

Das folgende Beispiel zeigt, wie ein JSONPath Ausdruck an die json() Methode übergeben wird. Sie könnten auch einen Unterabschnitt Ihres Anforderungstextobjekts lesen, indem Sie einen Punkt,, verwenden., um eine Eigenschaft anzugeben:


{
    "name" : "$input.params('name')",
    "body" : $input.json('$.Age')  
}

Für eine Anfrage, die die Parameter der Abfragezeichenfolge name=Bella&type=dog und den folgenden Hauptteil enthält:


{
    "Price" : "249.99",
    "Age": "6"
}

Die Ausgabe dieser Zuordnungsvorlage sollte wie folgt aussehen:


{
    "name" : "Bella",
    "body" : "6"
}

Wenn die Payload einer Methodenanforderung Zeichen ohne Escape-Zeichen enthält, die nicht analysiert werden können JavaScript, gibt API Gateway möglicherweise eine Antwort zurück. 400 $util.escapeJavaScript()Anwenden, um sicherzustellen, dass die JSON Eingabe ordnungsgemäß analysiert werden kann.

Das vorherige Beispiel mit $util.escapeJavaScript($input.json('$.Age')) Applied lautet wie folgt:


{
    "name" : "$input.params('name')",
    "body" : "$util.escapeJavaScript($input.json('$.Age'))" 
}

In diesem Fall sollte die Ausgabe dieser Mapping-Vorlage wie folgt aussehen:


{
    "name" : "Bella",
    "body": "\"6\""
}

Beispiel für Anfrage und Antwort

Im folgenden Beispiel wird $input.params()$input.path(), und $input.json() für eine Ressource mit dem Pfad verwendet/things/{id}:


{
    "id" : "$input.params('id')",
    "count" : "$input.path('$.things').size()",
    "things" : $input.json('$.things')"
}

Für eine Anfrage, die den Pfadparameter 123 und den folgenden Hauptteil enthält:


{
      "things": {
            "1": {},
            "2": {},
            "3": {}
      }
}

Die Ausgabe dieser Mapping-Vorlage sollte wie folgt aussehen:


{"id":"123","count":"3","things":{"1":{},"2":{},"3":{}}}

Das vorherige Beispiel mit $util.escapeJavaScript($input.json('$.things')) Applied lautet wie folgt:


{
     "id" : "$input.params('id')",
     "count" : "$input.path('$.things').size()",
     "things" : "$util.escapeJavaScript($input.json('$.things'))"
}

Die Ausgabe dieser Mapping-Vorlage sollte wie folgt aussehen:


{"id":"123","count":"3","things":"{\"1\":{},\"2\":{},\"3\":{}}"}

Weitere Mapping-Beispiele finden Sie unter Zuordnungsvorlagen für REST APIs.

`$stageVariables`

Stufenvariablen können in Parameter-Mapping- und Mapping-Vorlagen sowie als Platzhalter in Methodenintegrationen URLs verwendet ARNs und dort verwendet werden. Weitere Informationen finden Sie unter Verwenden Sie Stufenvariablen für ein REST API API In-Gateway.

Syntax	Beschreibung
`$stageVariables.<variable_name>`, `$stageVariables['<variable_name>']` oder `${stageVariables['<variable_name>']}`	`<variable_name>` steht für einen Stufenvariablennamen.

`$util`-Variablen

Die $util-Variable enthält Dienstprogrammfunktionen, die in Mapping-Vorlagen verwendet werden.

Anmerkung

Sofern nicht anders angegeben, ist der Standardzeichensatz UTF -8.

Funktion	Beschreibung
`$util.escapeJavaScript()`	Escapiert die Zeichen in einer Zeichenfolge mithilfe von JavaScript Zeichenfolgenregeln. Anmerkung Mit dieser Funktion werden alle einfachen Anführungszeichen (`'`) durch Escape-Zeichen (`\'`) geschützt. Die einfachen Escape-Anführungszeichen sind jedoch in JSON nicht gültig. Wenn also die Ausgabe dieser Funktion in einer JSON Eigenschaft verwendet wird, müssen Sie alle maskierten einfachen Anführungszeichen (`\'`) wieder in normale einfache Anführungszeichen (`'`) umwandeln. Das wird im folgenden Beispiel veranschaulicht: `"input" : "$util.escapeJavaScript(data).replaceAll("\\'","'")"`
`$util.parseJson()`	Nimmt „stringified“ an JSON und gibt eine Objektdarstellung des Ergebnisses zurück. Sie können das Ergebnis dieser Funktion verwenden, um nativ in der Apache Velocity Template Language () auf Elemente der Nutzlast zuzugreifen und diese zu bearbeiten. VTL Angenommen, Sie haben folgende Nutzlast: `{"errorMessage":"{\"key1\":\"var1\",\"key2\":{\"arr\":[1,2,3]}}"}` Und verwenden die folgende Mapping-Vorlage: `#set ($errorMessageObj = $util.parseJson($input.path('$.errorMessage'))) { "errorMessageObjKey2ArrVal" : $errorMessageObj.key2.arr[0] }` Dann erhalten Sie die folgende Ausgabe: `{ "errorMessageObjKey2ArrVal" : 1 }`
`$util.urlEncode()`	Konvertiert eine Zeichenfolge in das Format „application/x-www-form-urlencoded“.
`$util.urlDecode()`	Dekodiert eine Zeichenfolge „application/x-www-form-urlencoded“.
`$util.base64Encode()`	Codiert die Daten in eine base64-verschlüsselte Zeichenfolge.
`$util.base64Decode()`	Decodiert die Daten einer base64-verschlüsselten Zeichenfolge.

Warnung JavaScript ist in Ihrem Browser nicht verfügbar oder deaktiviert.

Zur Nutzung der AWS-Dokumentation muss JavaScript aktiviert sein. Weitere Informationen finden auf den Hilfe-Seiten Ihres Browsers.

Dokumentkonventionen

Integrations-Pass-Through-Verhalten

Gateway-Antworten