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.
Referenz zu API Gateway-Mapping-Vorlage und -Zugriffsprotokollierungsvariablen
Dieser Abschnitt enthält Referenzinformationen zu den Variablen und Funktionen, die Amazon API Gateway für die Verwendung mit Datenmodellen, Genehmigern, Zuweisungsvorlagen und CloudWatch Zugriffsprotokollierung definiert. Detaillierte Informationen zur Verwendung dieser Variablen und Funktionen finden Sie unter Grundlegendes zu Zuweisungsvorlagen. Weitere Informationen zur Velocity Template Language (VTL) finden Sie in der VTL-Referenz
Themen
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, Genehmiger, Zuweisungsvorlagen und CloudWatch Zugriffsprotokollierung
Die folgenden $context
Variablen können in Datenmodellen, Genehmigern, Zuweisungsvorlagen und CloudWatch Zugriffsprotokollierung verwendet werden.
Informationen zu $context
Variablen, die nur in der 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. |
Eine Eigenschaft der Claims, die aus dem Amazon Cognito-Benutzerpool zurückgegeben werden, nachdem der Methodenaufrufer erfolgreich authentifiziert wurde. Weitere Informationen finden Sie unter Zugriff auf eine REST-API mit Amazon Cognito-Benutzerpools als Genehmiger steuern. AnmerkungBei einem Aufruf von |
$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. |
Der in einer Zeichenfolge umgewandelte Wert des angegebenen Schlüssel-Wert-Paares der
Dann gibt der Aufruf von Weitere Informationen finden Sie unter API Gateway-Lambda-Genehmiger verwenden. |
$context.awsEndpointRequestId |
Die Anforderungs-ID des AWS Endpunkts. |
$context.domainName |
Der zum Aufrufen der API verwendete vollständige Domänennamen. Dieser Wert sollte mit dem für den eingehenden |
$context.domainPrefix |
Das erste Label der |
$context.error.message |
Eine Zeichenfolge, die eine API Gateway-Fehlermeldung enthält. Diese Variable kann nur für die einfache Ersetzung von Variablen in einer GatewayResponse Textzuweisungsvorlage verwendet werden, die nicht von der Velocity Template Language-Engine verarbeitet wird, und in der Zugriffsprotokollierung. Weitere Informationen finden Sie unter 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 Ersetzung von Variablen in einer GatewayResponse Textzuweisungsvorlage verwendet werden, die nicht von der Velocity Template Language-Engine verarbeitet wird, und in der Zugriffsprotokollierung. Weitere Informationen finden Sie unter 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: |
$context.identity.accountId |
Die AWS Konto-ID, die der Anforderung zugeordnet ist. |
$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 Erstellen und Verwenden von Nutzungsplänen mit API-Schlüsseln. |
$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 der Amazon Cognito-Authentifizierungsanbieter, die vom Aufrufer, der die Anfrage stellt, 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, Weitere Informationen 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 |
$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 |
|
$context.identity.sourceIp |
Die Quell-IP-Adresse der TCP-Verbindung, von der die Anforderung an API Gateway 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.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 |
$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.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 . AnmerkungAPI-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.requestOverride.header. |
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 Mapping-Vorlage zum Überschreiben der Anforderungs- und Antwortparameter und -Statuscodes einer API. |
$context.requestOverride.path. |
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 Mapping-Vorlage zum Überschreiben der Anforderungs- und Antwortparameter und -Statuscodes einer API. |
$context.requestOverride.querystring. |
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 Mapping-Vorlage zum Überschreiben der Anforderungs- und Antwortparameter und -Statuscodes einer API. |
$context.responseOverride.header. |
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 Mapping-Vorlage 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 Mapping-Vorlage zum Überschreiben der Anforderungs- und Antwortparameter und -Statuscodes einer API. |
$context.requestTime |
Die Anforderungszeit im CLFdd/MMM/yyyy:HH:mm:ss
+-hhmm ). |
$context.requestTimeEpoch |
Die Anforderungszeit im Epoch |
$context.resourceId |
Der Bezeichner, den API Gateway Ihrer Ressource zuweist. |
$context.resourcePath |
Der Pfad zu Ihrer Ressource. Beim Nicht-Proxy-Anforderungs-URI von |
$context.stage |
Die Bereitstellungsstufe der API-Anforderung (z. B. |
$context.wafResponseCode |
Die von AWS WAF empfangene Antwort: |
$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 von AWS WAF zum Schutz Ihrer APIs. |
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
Beachten Sie, dass eine der Variablen ein API-Schlüssel ist. Dieses Beispiel setzt voraus, dass für die Methode "API-Schlüssel erforderlich" aktiviert ist.
{ "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" }
$context
-Variablen nur für Zugriffsprotokollierung
Die folgenden $context
-Variablen sind nur für Zugriffsprotokollierung verfügbar. Weitere Informationen finden Sie unter Einrichten der CloudWatch-Protokollierung für eine REST-API in API Gateway. (Informationen zu WebSocket APIs finden Sie unter 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 |
Der Genehmiger-Latenz 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, 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 |
$context.integration.error |
Die von einer Integration zurückgegebene Fehlermeldung. |
$context.integration.integrationStatus |
Bei der Lambda-Proxy-Integration der von zurückgegebene Statuscode AWS Lambda, nicht vom Backend-Lambda-Funktionscode. |
$context.integration.latency |
Die Integrationslatenz in Millisekunden. Äquivalent mit $context.integrationLatency . |
$context.integration.requestId |
Die Anforderungs-ID des AWS 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-Proxy-Integration stellt dieser Parameter den Statuscode dar, der von zurückgegeben wird AWS Lambda, nicht vom Backend-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 von zurückgegebene Fehlermeldung AWS WAF. |
$context.waf.latency |
Die AWS WAF Latenz in ms. |
$context.waf.status |
Der von zurückgegebene Statuscode AWS WAF. |
$context.xrayTraceId |
Die Trace-ID für die X-Ray-Trace. Weitere Informationen finden Sie unter Einrichten von AWS X-Ray mit API-Gateway-REST-APIs. |
$input
-Variablen
Die $input
-Variable stellt die Nutzlast und die Parameter der Methodenanforderung dar, die von der Mapping-Vorlage verarbeitet werden sollen. Sie bietet vier Funktionen:
Variable und Funktion | Beschreibung |
---|---|
$input.body |
Gibt die Nutzlast der Raw-Anforderung als Zeichenfolge zurück. |
$input.json(x) |
Diese Funktion wertet einen JSONPath-Ausdruck aus und gibt die Ergebnisse als JSON-Zeichenfolge zurück. Beispielsweise gibt Weitere Informationen zu JSONPath finden Sie unter JSONPath |
$input.params() |
Gibt die Zuweisung aller Anforderungsparameter zurück. Wir empfehlen, das Ergebnis |
$input.params(x) |
Gibt aus der Zeichenfolge eines Parameternamens |
$input.path(x) |
Empfängt eine JSONPath-Ausdruckszeichenfolge ( Beispiel: Der Ausdruck
Weitere Informationen zu JSONPath finden Sie unter JSONPath |
Beispiele für $input
-Variablenvorlage
Beispiel für Parameter-Mapping-Vorlage
Im folgenden Beispiel des Parameter-Mappings werden alle Parameter 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 } }
Von dieser Mapping-Vorlage werden alle Anforderungsparameter in der Nutzlast wie folgt ausgegeben:
{ "params" : { "path" : { "path_name" : "path_value", ... } "header" : { "header_name" : "header_value", ... } "querystring" : { "querystring_name" : "querystring_value", ... } } }
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 Teil der Nutzlast über die Lambda-Funktion abrufen. In den folgenden Beispielen wird dies veranschaulicht.
Beispiel-JSON-Mapping-Vorlage mit $input
Das folgende Beispiel zeigt, wie mithilfe eines Mappings ein Name aus der Abfragezeichenfolge gelesen und dann der gesamte POST-Text in ein Element eingebunden wird:
{ "name" : "$input.params('name')", "body" : $input.json('$') }
Wenn die JSON-Eingabe Zeichen enthält, die nicht durch Escape-Zeichen geschützt sind und von nicht analysiert werden können JavaScript, wird möglicherweise eine 400-Antwort zurückgegeben. Die Verwendung von $util.escapeJavaScript($input.json('$'))
stellt sicher, dass die JSON-Eingabe ordnungsgemäß analysiert werden kann.
Beispiel-Mapping-Vorlage mit $input
Das folgende Beispiel zeigt, wie ein JSONPath-Ausdruck an die Methode json()
übergeben wird. Sie können auch eine bestimmte Eigenschaft des Anforderungstextobjekts lesen, wenn Sie einen Punkt (.)
und dann den Eigenschaftennamen eingeben:
{ "name" : "$input.params('name')", "body" : $input.json('$.mykey') }
Wenn eine Methodenanforderungsnutzlast Zeichen enthält, die nicht durch Escape-Zeichen geschützt sind und von nicht analysiert werden können JavaScript, erhalten Sie möglicherweise eine -400
Antwort. In diesem Fall müssen Sie wie folgt die Funktion $util.escapeJavaScript()
in der Mapping-Vorlage aufrufen:
{ "name" : "$input.params('name')", "body" : "$util.escapeJavaScript($input.json('$.mykey'))" }
Beispielanforderung und -antwort mit $input
Im folgenden Beispiel werden alle drei Funktionen verwendet:
Anforderungsvorlage:
Resource: /things/{id} With input template: { "id" : "$input.params('id')", "count" : "$input.path('$.things').size()", "things" : "$util.escapeJavaScript($input.json('$.things'))" } POST /things/abc { "things" : { "1" : {}, "2" : {}, "3" : {} } }
Antwort:
{ "id": "abc", "count": "3", "things": { "1": {}, "2": {}, "3": {} } }
Weitere Mapping-Beispiele finden Sie unter Grundlegendes zu Zuweisungsvorlagen.
$stageVariables
Stufenvariablen können zur Zuweisung von Parametern und für Mapping-Vorlagen verwendet werden sowie als Platzhalter in ARNs und URLs bei Methodenintegrationen. Weitere Informationen finden Sie unter Einrichten von Stufenvariablen für eine REST-API-Bereitstellung.
Syntax | Beschreibung |
---|---|
$stageVariables. |
|
$stageVariables[' |
|
${stageVariables[' |
|
$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() |
Entfernt die Zeichen in einer Zeichenfolge mithilfe von JavaScript Zeichenfolgenregeln. AnmerkungMit dieser Funktion werden alle einfachen Anführungszeichen (
|
$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:
Und verwenden die folgende Mapping-Vorlage:
Dann erhalten Sie die folgende Ausgabe:
|
$util.urlEncode() |
Konvertiert eine Zeichenfolge in das "application/x-www-form-urlencoded"-Format. |
$util.urlDecode() |
Dekodiert eine "application/x-www-form-urlencoded"-Zeichenfolge. |
$util.base64Encode() |
Codiert die Daten in eine base64-verschlüsselte Zeichenfolge. |
$util.base64Decode() |
Decodiert die Daten einer base64-verschlüsselten Zeichenfolge. |