Variablen für Datentransformationen für API Gateway - Amazon API Gateway
Kontextvariablen für DatentransformationenEingabevariablenStufenvariablenUtil-Variablen

Variablen für Datentransformationen für API Gateway

Wenn Sie eine Parameterzuweisung erstellen, können Sie Kontextvariablen als Datenquelle verwenden. Wenn Sie Zuweisungsvorlagen-Transformationen erstellen, können Sie Kontextvariablen sowie input- und util-Variablen in Skripten verwenden, die Sie in der Velocity Template Language (VTL) schreiben. Beispiele für Zuweisungsvorlagen, die diese Referenzvariablen verwenden, finden Sie unter Beispiele für die Verwendung von Variablen bei Zuweisungsvorlagen-Transformationen in API Gateway.

Eine Liste der Referenzvariablen für Zugriffsprotokollierung finden Sie unter Variablen für die Zugriffsprotokollierung in API Gateway.

Kontextvariablen für Datentransformationen

Für Datenumwandlungen können Sie die folgenden $context-Variablen verwenden, bei denen die Groß-/Kleinschreibung beachtet werden muss.

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.

Bei Eigenschaft ist das einzige unterstützte Sonderzeichen 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 eine einfache Variablenersetzung in einer Textzuweisungsvorlage des Typs GatewayResponse, die von der VTL (Velocity Template Language)-Engine nicht verarbeitet wird, sowie bei der 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 eine einfache Variablenersetzung in einer Textzuweisungsvorlage des Typs GatewayResponse, die von der VTL (Velocity Template Language)-Engine nicht verarbeitet wird, sowie bei der 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 AWS-Konto-ID der Anforderung.
$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 können HTTP/2-Anfragen akzeptieren, aber API Gateway sendet Anfragen mithilfe von 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 Überschreiben der Anforderungs- und Antwortparameter sowie Statuscodes Ihrer API für REST-APIs in API Gateway.
$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 Überschreiben der Anforderungs- und Antwortparameter sowie Statuscodes Ihrer API für REST-APIs in API Gateway.
$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 Überschreiben der Anforderungs- und Antwortparameter sowie Statuscodes Ihrer API für REST-APIs in API Gateway.
$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 Überschreiben der Anforderungs- und Antwortparameter sowie Statuscodes Ihrer API für REST-APIs in API Gateway.
$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 Überschreiben der Anforderungs- und Antwortparameter sowie Statuscodes Ihrer API für REST-APIs in API Gateway.
$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 So schützen Sie Ihre REST-APIs in API Gateway mithilfe von AWS WAF.
$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 So schützen Sie Ihre REST-APIs in API Gateway mithilfe von AWS WAF.

Eingabevariablen

Sie können die folgenden $input-Variablen, bei denen die Groß- und Kleinschreibung beachtet werden muss, verwenden, um auf die Nutzdaten der Methodenanforderung und die Parameter der Methodenanforderung zu verweisen. Die folgenden Funktionen sind verfügbar:

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 JSONPath oder JSONPath for 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)

Empfängt eine JSONPath-Ausdruckszeichenfolge (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 finden Sie unter JSONPath oder JSONPath for Java.

Stufenvariablen

Sie können die folgenden Stufenvariablen als Platzhalter für ARNs und URLs in Methodenintegrationen verwenden. 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 gibt einen Stufenvariablennamen an.

Util-Variablen

Sie können die folgenden $util-Variablen verwenden, bei denen Groß- und Kleinschreibung beachtet werden muss, um Dienstprogrammfunktionen für Zuweisungsvorlagen zu verwenden. Sofern nicht anders angegeben, wird UTF-8 als Standardzeichensatz genutzt.

Funktion Beschreibung
$util.escapeJavaScript()

Die Zeichen einer Zeichenfolge werden unter Beachtung der JavaScript-Zeichenfolgenregeln durch Escape-Zeichen geschützt.

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()

Wandelt eine Zeichenfolge in das Format "application/x-www-form-urlencoded" um.
$util.urlDecode()

Decodiert eine Zeichenfolge des Typs "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.