Referenz zu API Gateway-Mapping-Vorlage und -Zugriffsprotokollierungsvariablen

Fokusmodus

Referenz zu API Gateway-Mapping-Vorlage und -Zugriffsprotokollierungsvariablen - Amazon API Gateway

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

Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.

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 Mapping-Vorlagen 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 Zugriffsprotokollierung CloudWatch
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 Daten-Mapping-Referenz für Amazon API Gateway-API-Anfragen und Antworten.

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

Die folgenden $context Variablen können in Datenmodellen, Autorisierern, Zuordnungsvorlagen und der Zugriffsprotokollierung verwendet werden. CloudWatch API Gateway 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 ID, die API Gateway Ihrer 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 In der Rolle „Genehmiger“ den Zugriff auf REST-APIs mithilfe von Amazon-Cognito-Benutzerpools steuern. Anmerkung Bei einem Aufruf von `$context.authorizer.claims` wird null (0) zurückgegeben.
`$context.authorizer.principalId`	Die ID des Prinzipalbenutzers in Verbindung mit dem Token, das vom Client gesendet und von einem API Gateway-Lambda-Genehmiger (früher als benutzerdefinierter Genehmiger bekannt) zurückgegeben wurde. Weitere Informationen finden Sie unter API Gateway-Lambda-Genehmiger verwenden.
`$context.authorizer.property`	Der in einer Zeichenfolge umgewandelte Wert des angegebenen Schlüssel-Wert-Paares der `context`-Zuordnung, der von einer API Gateway Lambda-Genehmigerfunktion zurückgegeben wird. Angenommen, der Genehmiger gibt folgende `context`-Zuweisung zurück: `"context" : { "key": "value", "numKey": 1, "boolKey": true }` Ein Aufruf von `$context.authorizer.key` gibt die Zeichenfolge `"value"` zurück, ein Aufruf von `$context.authorizer.numKey` gibt die Zeichenfolge `"1"` zurück und ein Aufruf von `$context.authorizer.boolKey` gibt die Zeichenfolge `"true"` zurück. Denn `property` das einzige unterstützte Sonderzeichen ist der `(_)` Unterstrich. Weitere Informationen finden Sie unter API Gateway-Lambda-Genehmiger verwenden.
`$context.awsEndpointRequestId`	Die Anforderungs-ID des AWS Endpunkts.
`$context.deploymentId`	Die ID der API-Bereitstellung
`$context.domainName`	Der zum Aufrufen der API verwendete vollständige Domänennamen. 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 Die WebSocket-API-Ausführung mit CloudWatch-Metriken überwachen 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 Die WebSocket-API-Ausführung mit CloudWatch-Metriken überwachen 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 API-Anfrage zuweist. 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 AWS Anfrage zugeordnete Konto-ID.
`$context.identity.apiKey`	Bei API-Methoden, für die ein API-Schlüssel erforderlich ist, ist diese Variable der API-Schlüssel für die Methodenanforderung. Bei Methoden, für die kein API-Schlüssel erforderlich ist, ist diese Variable nichtig. 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 für die API-Anforderung, falls 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 die IAM-Autorisierung verwenden.
`$context.identity.cognitoAuthenticationProvider`	Eine durch Komma getrennte Liste aller Amazon-Cognito-Authentifizierungsanbieter, die vom anfordernden Aufrufer verwendet werden. 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` Weitere Informationen zu verfügbaren Amazon-Cognito-Authentifizierungsanbietern finden Sie unter Verbundidentitäten verwenden im Amazon-Cognito-Entwicklerhandbuch.
`$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 TCP-Verbindung, von der die Anforderung an den API-Gateway-Endpunkt gesendet wird.
`$context.identity.clientCert.clientCertPem`	Das PEM-codierte Clientzertifikat, das der Client während der gegenseitigen TLS-Authentifizierung präsentiert hat. Vorhanden, wenn ein Client mithilfe eines benutzerdefinierten Domänennamens, für den gegenseitige TLS aktiviert ist, auf eine API zugreift. 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. Vorhanden, wenn ein Client mithilfe eines benutzerdefinierten Domain-Namens, für den gegenseitige TLS aktiviert ist, auf eine API 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. Vorhanden, wenn ein Client mithilfe eines benutzerdefinierten Domänennamens, für den gegenseitige TLS aktiviert ist, auf eine API zugreift. Nur in Zugriffsprotokollen vorhanden, wenn die gegenseitige TLS-Authentifizierung fehlschlägt.
`$context.identity.clientCert.serialNumber`	Die Seriennummer des Zertifikats. Vorhanden, wenn ein Client mithilfe eines benutzerdefinierten Domänennamens, für den gegenseitige TLS aktiviert ist, auf eine API 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. Vorhanden, wenn ein Client mithilfe eines benutzerdefinierten Domänennamens, für den gegenseitige TLS aktiviert ist, auf eine API 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. Vorhanden, wenn ein Client mithilfe eines benutzerdefinierten Domänennamens, für den gegenseitige TLS aktiviert ist, auf eine API zugreift. Nur in Zugriffsprotokollen vorhanden, wenn die gegenseitige TLS-Authentifizierung fehlschlägt.
`$context.identity.vpcId`	Die VPC-ID der VPC, deren Anforderung an den API-Gateway-Endpunkt gesendet wird.
`$context.identity.vpceId`	Die VPC-Endpunkt-ID des VPC-Endpunkts, dessen Anforderung an den API-Gateway-Endpunkt gesendet wird. Diese ist nur vorhanden, wenn Ihre API privat ist.
`$context.identity.user`	Die Hauptkennung des Benutzers, der für den Ressourcenzugriff autorisiert wird. Wird für Ressourcen unterstützt, die die IAM-Autorisierung verwenden.
`$context.identity.userAgent`	Die `User-Agent`-Kopfzeile des API-Aufrufers.
`$context.identity.userArn`	Der ARN (Amazon Resource Name) des tatsächlichen Benutzers nach der Authentifizierung. Weitere Informationen finden Sie unter https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html.
`$context.isCanaryRequest`	Gibt `true` zurück, wenn die Anforderung an den Canary gerichtet war oder `false`, wenn die Anforderung nicht an den Canary ging. Dies ist nur vorhanden, wenn Sie einen Canary aktiviert haben.
`$context.path`	Der Anforderungspfad. Bei einer Nicht-Proxy-Anforderungs-URL von `https://{rest-api-id}.execute-api.{region}.amazonaws.com/{stage}/root/child` lautet der `$context.path`-Wert beispielsweise `/{stage}/root/child`.
`$context.protocol`	Das Anforderungsprotokoll ist z. B, `HTTP/1.1`. Anmerkung API Gateway APIs kann HTTP/2-Anfragen akzeptieren, aber API Gateway sendet Anfragen über HTTP/1.1 an Backend-Integrationen. Infolgedessen wird das Anforderungsprotokoll als HTTP/1.1 protokolliert, auch wenn ein Client eine Anfrage sendet, die HTTP/2 verwendet.
`$context.requestId`	Eine ID für die Anforderung. Clients können diese Anforderungs-ID überschreiben. Verwenden von `$context.extendedRequestId` für eine eindeutige Anforderungs-ID, die API Gateway generiert.
`$context.requestOverride.header.header_name`	Der Anforderungs-Header-Override. Wenn dieser Parameter definiert ist, enthält er die Header, die statt der HTTP Header, die im Bereich Integrationsanforderung definiert sind, verwendet werden sollen. Weitere Informationen finden Sie unter Verwendung einer Zuweisungsvorlage zum Überschreiben der Anforderungs- und Antwortparameter und Statuscodes einer API.
`$context.requestOverride.path.path_name`	Der Anforderungspfad-Override. Wenn dieser Parameter definiert ist, enthält er den Anforderungspfad, der statt der URL-Pfadparameter, die im Bereich Integrationsanforderung definiert sind, verwendet werden soll. Weitere Informationen finden Sie unter Verwendung einer Zuweisungsvorlage zum Überschreiben der Anforderungs- und Antwortparameter und Statuscodes einer API.
`$context.requestOverride.querystring.querystring_name`	Der Abfragestring-Override. Wenn dieser Parameter definiert ist, enthält er die Abfragestrings, die statt der URL-Abfragestring-Parameter, die im Bereich Integrationsanforderung definiert sind, verwendet werden sollen. Weitere Informationen finden Sie unter Verwendung einer Zuweisungsvorlage zum Überschreiben der Anforderungs- und Antwortparameter und Statuscodes einer API.
`$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 Verwendung einer Zuweisungsvorlage zum Überschreiben der Anforderungs- und Antwortparameter und Statuscodes einer API.
`$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 Verwendung einer Zuweisungsvorlage zum Überschreiben der Anforderungs- und Antwortparameter und Statuscodes einer API.
`$context.requestTime`	Die Anforderungszeit im CLF-Format (`dd/MMM/yyyy:HH:mm:ss +-hhmm`).
`$context.requestTimeEpoch`	Die Anforderungszeit im Epoch-Format in Millisekunden.
`$context.resourceId`	Der Bezeichner, den API Gateway Ihrer Ressource zuweist.
`$context.resourcePath`	Der Pfad zu Ihrer Ressource. Beim Nicht-Proxy-Anforderungs-URI von `https://{rest-api-id}.execute-api.{region}.amazonaws.com/{stage}/root/child` lautet der `$context.resourcePath`-Wert beispielsweise `/root/child`. Weitere Informationen finden Sie unter Tutorial: REST-API mit HTTP-API ohne Proxy-Integration erstellen.
`$context.stage`	Die Bereitstellungsstufe der API-Anforderung (z. B. `Beta` oder `Prod`).
`$context.wafResponseCode`	Die von AWS WAF empfangene Antwort: `WAF_ALLOW` oder `WAF_BLOCK`. Wird nicht festgelegt, wenn die Stufe mit keiner Web-ACL verknüpft ist. Weitere Informationen finden Sie unter Verwenden Sie AWS WAF , um Ihren REST APIs in API Gateway zu schützen.
`$context.webaclArn`	Vollständiger ARN der Web-Zugriffskontrollliste (Web-ACL), anhand deren entschieden wird, ob die Anforderung zugelassen oder blockiert wird. Wird nicht festgelegt, wenn die Stufe mit keiner Web-ACL verknüpft ist. Weitere Informationen finden Sie unter Verwenden Sie AWS WAF , um Ihren REST APIs in API Gateway zu schützen.

Beispiel für `$context`-Variablenvorlage

Die Verwendung einer $context-Variablen in einer Mapping-Vorlage kann sinnvoll sein, wenn Ihre API-Methode strukturierte Daten an ein Backend übermittelt, das ein bestimmtes Datenformat erfordert.

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 vorausgesetzt, dass die Methode einen API-Schlüssel erfordert.


{
    "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 Zuweisungsvorlage 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 Richten Sie die CloudWatch Protokollierung für REST APIs in API Gateway ein. (Näheres dazu finden Sie unter.) WebSocket APIs Die WebSocket-API-Ausführung mit CloudWatch-Metriken überwachen

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 Integrationslatenz des Genehmigers in Millisekunden
`$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, mit dem eine eingehende Anforderung übereinstimmte. Gilt, wenn ein Client einen benutzerdefinierten Domain-Namen für den Zugriff auf eine API verwendet. Wenn ein Client beispielsweise eine Anforderung an `https://api.example.com/v1/orders/1234` sendet und die Anforderung dem API-Mapping mit dem Pfad `v1/orders` übereinstimmt, lautet der Wert `v1/orders`. Weitere Informationen hierzu finden Sie unter Ordnen Sie API-Stufen einem benutzerdefinierten Domainnamen für REST zu APIs.
`$context.endpointType`	Der Endpunkttyp der API.
`$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 einrichten APIs.

`$input`-Variablen

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

Variable und Funktion	Beschreibung
`$input.body`	Gibt die Nutzlast der Raw-Anforderung als Zeichenfolge zurück. Sie können `$input.body` verwenden, um ganze Fließkommazahlen beizubehalten, z. B. `10.00`.
`$input.json(x)`	Diese Funktion wertet einen JSONPath Ausdruck aus und gibt die Ergebnisse als JSON-Zeichenfolge zurück. Beispielsweise gibt `$input.json('$.pets')` eine JSON-Zeichenfolge zurück, die die `pets`-Struktur abbildet. Weitere Informationen zu JSONPath, finden Sie unter JSONPathoder JSONPath fü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. Dies ermöglicht einen nativen Zugriff auf Elemente der Nutzlast in Apache Velocity Template Language (VTL) und deren Bearbeitung. 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 JSONPath Java finden Sie unter JSONPathoder JSONPath für Java.

Beispiele für `$input`-Variablenvorlage

Im folgenden Beispiel sehen Sie, wie Sie die $input-Variablen in Zuweisungsvorlagen verwenden. Sie können eine Scheinintegration oder eine Lambda-Nicht-Proxy-Integration verwenden, die das Eingabeereignis an API Gateway zurückgibt, um diese Beispiele auszuprobieren.

Beispiel für Parameter-Mapping-Vorlage

Im folgenden Beispiel werden alle Anforderungsparameter einschließlich path, querystring und header ü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 Anforderung, die die folgenden Eingabeparameter enthält:

Einen Pfadparameter namens myparam
Die Abfragezeichenfolgenparameter querystring1=value1,value2&querystring2=value3
Die Header "header1" : "value1", "header2" : "value2" und "header3" : "value3"

Die Ausgabe dieser Zuweisungsvorlage sollte wie folgt aussehen:


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

Beispiel einer JSON-Zuweisungsvorlage

Sie können die $input-Variable verwenden, um Abfragezeichenfolgen und Anforderungstext mit oder ohne die Verwendung von Modellen abzurufen. Sie können auch den Parameter und die Nutzlast oder nur einen Unterabschnitt der Nutzlast abrufen. In den folgenden drei Beispielen wird dies veranschaulicht.

Im folgenden Beispiel wird eine Zuweisungsvorlage verwendet, um einen Teilabschnitt der Nutzdaten 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 Anforderung, die die Parameter der Abfragezeichenfolge name=Bella&type=dog und den folgenden Text enthält:


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

Die Ausgabe dieser Zuweisungsvorlage 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. Eine Anwendung von $util.escapeJavaScript($input.json('$')) stellt sicher, dass die JSON-Eingabe ordnungsgemäß eingelesen werden kann.

Im vorangegangenen Beispiel hätte eine Anwendung von $util.escapeJavaScript($input.json('$')) folgendes Ergebnis:


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

In diesem Fall sollte die Ausgabe dieser Zuweisungsvorlage wie folgt aussehen:


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

JSONPath Beispiel für einen Ausdruck

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


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

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


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

Die Ausgabe dieser Zuweisungsvorlage 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 Eine Anwendung von $util.escapeJavaScript() stellt sicher, dass die JSON-Eingabe ordnungsgemäß eingelesen werden kann.

Im vorangegangenen Beispiel hätte eine Anwendung von $util.escapeJavaScript($input.json('$.Age')) folgendes Ergebnis:


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

In diesem Fall sollte die Ausgabe dieser Zuweisungsvorlage wie folgt aussehen:


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

Beispiel für Anforderung und Antwort

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


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

Für eine Anforderung, die den Pfadparameter 123 und den folgenden Text enthält:


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

Die Ausgabe dieser Zuweisungsvorlage sollte wie folgt aussehen:


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

Im vorangegangenen Beispiel hätte eine Anwendung von $util.escapeJavaScript($input.json('$.things')) folgendes Ergebnis:


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

Die Ausgabe dieser Zuweisungsvorlage sollte wie folgt aussehen:


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

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

`$stageVariables`

Stufenvariablen können in der Parameterzuweisung und in Zuordnungsvorlagen sowie als Platzhalter in ARNs Methodenintegrationen URLs verwendet werden. Weitere Informationen finden Sie unter Stufenvariablen für eine REST-API in API Gateway verwenden.

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, wird UTF-8 als Standardzeichensatz genutzt.

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. Allerdings sind diese durch Escape-Zeichen geschützten einfachen Anführungszeichen in JSON nicht zulässig. Sofern die Ausgabe dieser Funktion in einer JSON-Eigenschaft verwendet werden soll, müssen alle einfachen Anführungszeichen, die durch Escape-Zeichen geschützt sind (`\'`), wieder in reguläre einfache Anführungszeichen (`'`) geändert werden. Das wird im folgenden Beispiel veranschaulicht: `"input" : "$util.escapeJavaScript(data).replaceAll("\\'","'")"`
`$util.parseJson()`	Erhält das "stringify"-JSON-Objekt und gibt eine Objektdarstellung des Ergebnisses zurück. Mit dem Ergebnis dieser Funktion können Sie Elemente der Nutzlast, die in Apache Velocity Template Language (VTL) sind, aufrufen und bearbeiten. 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

Auf dieser Seite

Wählen Sie Ihre Cookie-Einstellungen aus

Cookie-Einstellungen anpassen

Essenziell

Leistung

Funktional

Werbung

Cookie-Einstellungen konnten nicht gespeichert werden

Referenz zu API Gateway-Mapping-Vorlage und -Zugriffsprotokollierungsvariablen

Themen

Anmerkung

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

Anmerkung

Anmerkung

Beispiel für `$context`-Variablenvorlage

Anmerkung

`$context`-Variablen nur für Zugriffsprotokollierung

`$input`-Variablen

Beispiele für `$input`-Variablenvorlage

Beispiel für Parameter-Mapping-Vorlage

Beispiel einer JSON-Zuweisungsvorlage

JSONPath Beispiel für einen Ausdruck

Beispiel für Anforderung und Antwort

`$stageVariables`

`$util`-Variablen

Anmerkung

Anmerkung

Auf dieser Seite

Related resources

Hat Ihnen diese Seite geholfen?

Related resources

Nächstes Thema:

Vorheriges Thema:

Brauchen Sie Hilfe?