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. # Datentransformationen für WebSocket APIs im API Gateway In API Gateway kann die Methodenanforderung einer WebSocket API eine Nutzlast in einem anderen Format als die entsprechende Nutzlast der Integrationsanfrage annehmen, wie es im Backend erforderlich ist. Das Backend wiederum kann eine Integrationsantwortnutzlast zurückgeben, die nicht der Methodenantwortnutzlast entspricht, die das Frontend erwartet. In Amazon API Gateway können Sie Zuweisungsvorlagen verwenden, um die Nutzdaten einer Methodenanforderung der entsprechenden Integrationsanforderung zuzuordnen bzw. die Nutzdaten einer Integrationsanforderung der entsprechenden Methodenantwort zuzuordnen. Sie erstellen eine Zuweisungsvorlage und geben einen Vorlagen-Auswahlausdruck an, um zu bestimmen, welche Vorlage für die erforderlichen Datentransformationen verwendet werden soll. Sie können Datenzuordnungen verwenden, um Daten aus einer [Routenanforderung](api-gateway-basic-concept.md#apigateway-definition-route-request) einer Backend-Integration zuzuordnen. Weitere Informationen hierzu finden Sie unter [Datenzuordnung für WebSocket APIs in API Gateway einrichten](websocket-api-data-mapping.md). ## Zuweisungsvorlagen und Modelle [Eine *Mapping-Vorlage* ist ein in [Velocity Template Language (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html) ausgedrücktes Skript, das mithilfe von Ausdrücken auf die Nutzlast angewendet wird. JSONPath ](https://goessner.net/articles/JsonPath/) Weitere Informationen über API Gateway-Zuordnungsvorlagen finden Sie unter [Zuordnen von Vorlagentransformationen für REST APIs in API Gateway](models-mappings.md). Die Nutzlast kann ein dem [JSON-Schema Entwurf 4](https://datatracker.ietf.org/doc/html/draft-zyp-json-schema-04) entsprechendes *Datenmodell* umfassen. Sie müssen kein Modell definieren, um eine Zuweisungsvorlage zu erstellen. Ein Modell kann Ihnen jedoch bei der Erstellung einer Vorlage helfen, da API Gateway einen Vorlagenentwurf auf der Grundlage eines bereitgestellten Modells generiert. Weitere Informationen über API Gateway-Modelle finden Sie unter [Datenmodelle für REST APIs](models-mappings-models.md). ## Vorlagen-Auswahlausdrücke [Um eine Payload mit einer Mapping-Vorlage zu transformieren, geben Sie in einer [Integrationsanfrage oder Integrationsantwort](apigateway-websocket-api-integration-requests.md) einen Ausdruck für die WebSocket API-Vorlagenauswahl an.](apigateway-websocket-api-integration-responses.md) Durch Auswerten dieses Ausdrucks wird die Eingabe- oder Ausgabevorlage (falls vorhanden) bestimmt, die zum Transformieren des Anforderungstexts in den Integrationsanforderungstext (über eine Eingabevorlage) oder des Integrationsantworttext in den Routenantworttext (über eine Ausgabevorlage) verwendet werden soll. `Integration.TemplateSelectionExpression` unterstützt `${request.body.jsonPath}` und statische Werte. `IntegrationResponse.TemplateSelectionExpression` unterstützt `${request.body.jsonPath}`, `${integration.response.statuscode}`, `${integration.response.header.headerName}`, `${integration.response.multivalueheader.headerName}` und statische Werte. ## Integrationsantwort-Auswahlausdrücke Wenn Sie [eine Integrationsantwort für eine WebSocket API einrichten](apigateway-websocket-api-integration-responses.md), können Sie optional einen Auswahlausdruck für eine Integrationsantwort angeben. Dieser Ausdruck bestimmt, welche `[https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid-integrationresponses-integrationresponseid.html](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid-integrationresponses-integrationresponseid.html)` ausgewählt werden sollte, wenn eine Integration zurückgegeben wird. Der Wert dieses Ausdrucks wird zurzeit durch API Gateway eingeschränkt, wie nachfolgend definiert. Beachten Sie, dass dieser Ausdruck nur für *Nicht-Proxy-Integrationen* relevant ist. Eine Proxy-Integration übergibt die Antwortnutzlast einfach ohne Modellierung oder Modifikation an die aufrufende Methode zurück. Im Gegensatz zu den anderen vorhergehenden Auswahlausdrücken unterstützt dieser Ausdruck derzeit ein *Musterabgleich*-Format. Der Ausdruck sollte in Schrägstriche verpackt werden. Derzeit ist der Wert je nach fixier `[https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid.html#apis-apiid-integrations-integrationid-prop-integration-integrationtype](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid.html#apis-apiid-integrations-integrationid-prop-integration-integrationtype)`: + Für Lambda-basierte Integrationen lautet er `$integration.response.body.errorMessage`. + Für `HTTP`- und `MOCK`-Integrationen ist dies `$integration.response.statuscode`. + Für `HTTP_PROXY` und `AWS_PROXY` wird der Ausdruck nicht verwendet, da Sie anfordern, dass die Nutzlast über die aufrufende Methode übergeben wird. # Datenzuordnung für WebSocket APIs in API Gateway einrichten Mit der *Datenzuordnung* können Sie Daten aus einer [Routenanforderung](api-gateway-basic-concept.md#apigateway-definition-route-request) einer Backend-Integration zuordnen. **Anmerkung** Die Datenzuordnung für wird in der WebSocket APIs nicht unterstützt AWS-Managementkonsole. Sie müssen das AWS CLI, oder ein SDK verwenden AWS CloudFormation, um die Datenzuordnung zu konfigurieren. **Topics** + [Zuordnen von Routenanforderungsdaten zu Integrationsanforderungsparametern](#websocket-mapping-request-parameters) + [Beispiele](#websocket-data-mapping-examples) ## Zuordnen von Routenanforderungsdaten zu Integrationsanforderungsparametern Integrationsanforderungsparameter können aus beliebigen definierten Routenanforderungsparametern, dem Anforderungstext [`context` oder ](api-gateway-mapping-template-reference.md#context-variable-reference) [`stage`](api-gateway-mapping-template-reference.md#stagevariables-template-reference)-Variablen und statischen Werten zugeordnet werden. In der folgenden Tabelle sehen Sie Datenzuordnungsausdrücke für Integrationsanfragen. In der Tabelle ist *`PARAM_NAME`* der Name eines Routenanforderungsparameters des angegebenen Parametertyps. Es muss mit dem regulären Ausdruck übereinstimmen`'^[a-zA-Z0-9._$-]+$]'`. *JSONPath\$1EXPRESSION*ist ein JSONPath Ausdruck für ein JSON-Feld des Hauptteils der Anfrage. | Zugewiesene Datenquelle | Mapping-Ausdruck | | --- | --- | | Anforderungsabfragezeichenfolge (wird nur für die \$1connect-Route unterstützt) | route.request.querystring.PARAM\$1NAME | | Anforderungs-Header (wird nur für die \$1connect-Route unterstützt) | route.request.header.PARAM\$1NAME | | Abfragezeichenfolge mit mehreren Werten (nur für die \$1connect-Route unterstützt) | route.request.multivaluequerystring.PARAM\$1NAME | | Anforderungsheader mit mehreren Werten (nur für die \$1connect-Route unterstützt) | route.request.multivalueheader.PARAM\$1NAME | | Anforderungstext | route.request.body.JSONPath\$1EXPRESSION | | Stufenvariablen | stageVariables.VARIABLE\$1NAME | | Kontextvariablen | context.VARIABLE\$1NAME, wobei die Variable zu den [unterstützten Kontextvariablen](api-gateway-mapping-template-reference.md#context-variable-reference) gehören muss. | | Statischer Wert | 'STATIC\$1VALUE'. Das STATIC\$1VALUE ist ein Zeichenkettenliteral und muss in einfache Anführungszeichen eingeschlossen werden. | Achten Sie beim Erstellen einer Datenzuordnung auf das AWS CLI richtige Format für die Verwendung von Literalen mit Zeichenfolgen in. AWS CLI Weitere Informationen finden Sie unter [Verwenden von Zeichenfolgen mit Anführungszeichen in der AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-usage-parameters-quoting-strings.html) im *Benutzerhandbuch zur AWS Command Line Interface *. ## Beispiele In den folgenden AWS CLI Beispielen werden Datenzuordnungen konfiguriert. Eine CloudFormation Beispielvorlage finden Sie unter. [samples/websocket-data-mapping.zip](samples/websocket-data-mapping.zip) ### Zuordnen der ConnectionID eines Clients zu einem Header in einer Integrationsanforderung Der folgende [update-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-integration.html)-Befehl weist die `connectionId` eines Clients dem `connectionId`-Header in der Anfrage an eine Backend-Integration zu: ``` aws apigatewayv2 update-integration \ --integration-id abc123 \ --api-id a1b2c3d4 \ --request-parameters 'integration.request.header.connectionId'='context.connectionId' ``` ### Zuordnen eines Abfragezeichenfolgenparameters zu einem Header in einer Integrationsanforderung Das folgende Beispiel weist einen `authToken`-Abfragezeichenfolgenparameter dem `authToken`-Header in der Integrationsanforderung zu. 1. Verwenden Sie den folgenden [update-route](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-route.html)-Befehl, um den `authToken`-Abfragezeichenfolgenparameter zu den Anforderungsparametern der Route hinzuzufügen. ``` aws apigatewayv2 update-route --route-id 0abcdef \ --api-id a1b2c3d4 \ --request-parameters '{"route.request.querystring.authToken": {"Required": false}}' ``` 1. Verwenden Sie den folgenden [update-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-integration.html)-Befehl, um den Abfragezeichenfolgenparameter dem `authToken`-Header in der Anfrage an die Backend-Integration zuzuweisen. ``` aws apigatewayv2 update-integration \ --integration-id abc123 \ --api-id a1b2c3d4 \ --request-parameters 'integration.request.header.authToken'='route.request.querystring.authToken' ``` 1. (Optional) Gehen Sie bei Bedarf wie folgt vor, [delete-route-request-parameter](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/delete-route-request-parameter.html)um den `authToken` Abfragezeichenfolgenparameter aus den Anforderungsparametern der Route zu löschen. ``` aws apigatewayv2 delete-route-request-parameter \ --route-id 0abcdef \ --api-id a1b2c3d4 \ --request-parameter-key 'route.request.querystring.authToken' ``` # WebSocket Referenz zur API-Zuordnungsvorlage für API Gateway In diesem Abschnitt werden die Variablen zusammengefasst, die derzeit WebSocket APIs in API Gateway unterstützt werden. | Parameter | Beschreibung | | --- | --- | | \$1context.connectionId | Eine eindeutige ID für die Verbindung, die für einen Rückruf an den Client verwendet werden kann. | | \$1context.connectedAt | Die [Epoch](https://en.wikipedia.org/wiki/Unix_time)-formatierte Verbindungszeit. | | \$1context.domainName | Ein Domainname für die WebSocket API. Dies kann für einen Rückruf an den Client (anstelle eines hardcodierten Wertes) verwendet werden. | | \$1context.eventType | Der Ereignistyp: `CONNECT`, `MESSAGE` oder `DISCONNECT`. | | \$1context.messageId | Eine eindeutige serverseitige ID für eine Nachricht. Nur verfügbar, wenn der `$context.eventType` `MESSAGE` ist. | | \$1context.routeKey | Der ausgewählte Routenschlüssel. | | \$1context.requestId | Entspricht `$context.extendedRequestId`. | | \$1context.extendedRequestId | Eine automatisch generierte ID für den API-Aufruf, die weitere nützliche Informationen für das Debugging/die Fehlerbehebung enthält. | | \$1context.apiId | Die ID, die API Gateway Ihrer API zuweist. | | \$1context.authorizer.principalId | Die ID des Prinzipalbenutzer, die dem vom Client gesendeten und von einer Lambda-Funktion eines API Gateway-Lambda-Genehmigers (früher "benutzerdefinierter Genehmiger") zurückgegebenen Token zugeordnet ist. | | \$1context.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
}
Dann gibt der Aufruf von `$context.authorizer.key` die Zeichenfolge `"value"` zurück, der Aufruf von `$context.authorizer.numKey` gibt die Zeichenfolge `"1"` zurück und der Aufruf von `$context.authorizer.boolKey` gibt den Wert `"true"` zurück. | | \$1context.error.messageString | Die Wert von \$1context.error.message in Anführungszeichen, d. h. "\$1context.error.message". | | \$1context.error.validationErrorString | Eine Zeichenfolge mit einer detaillierten Validierungs-Fehlermeldung. | | \$1context.identity.accountId | Die der Anfrage zugeordnete AWS Konto-ID. | | \$1context.identity.apiKey | Der API-Besitzerschlüssel, der der schlüsselfähigen API-Anforderung zugewiesen ist. | | \$1context.identity.apiKeyId | Die API-Schlüssel-ID, die der schlüsselfähigen API-Anforderung zugewiesen ist | | \$1context.identity.caller | Die Prinzipal-ID des Aufrufers, von dem die Anforderung stammt. | | \$1context.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](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-identity.html) im *Amazon-Cognito-Entwicklerhandbuch*. | | \$1context.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. | | \$1context.identity.cognitoIdentityId | Die Amazon Cognito Identitäts-ID des anfordernden Aufrufers. Nur verfügbar, wenn die Anfrage mit Anmeldeinformationen von Amazon Cognito signiert wurde. | | \$1context.identity.cognitoIdentityPoolId | Die Amazon Cognito Identitätspool-ID des anfordernden Aufrufers. Nur verfügbar, wenn die Anfrage mit Anmeldeinformationen von Amazon Cognito signiert wurde. | | \$1context.identity.sourceIp | Die Quell-IP-Adresse der TCP-Verbindung, von der die Anforderung an API Gateway gesendet wird. | | \$1context.identity.user | Die Prinzipal-ID des Benutzers, von dem die Anforderung stammt. | | \$1context.identity.userAgent | Der Benutzeragent des API-Aufrufers. | | \$1context.identity.userArn | Der ARN (Amazon Resource Name) des tatsächlichen Benutzers nach der Authentifizierung. | | \$1context.requestTime | Die Anforderungszeit im [CLF](https://httpd.apache.org/docs/current/logs.html#common)-Format (dd/MMM/yyyy:HH:mm:ss \$1-hhmm). | | \$1context.requestTimeEpoch | Die Anforderungszeit im [Epoch](https://en.wikipedia.org/wiki/Unix_time)-Format in Millisekunden. | | \$1context.stage | Die Bereitstellungsstufe des API-Aufrufs (z. B. "Beta" oder "Prod"). | | \$1context.status | Der Antwortstatus. | | \$1input.body | Gibt die Raw-Nutzlast als Zeichenfolge zurück. | | \$1input.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](https://goessner.net/articles/JsonPath/)oder [JSONPath für Java](https://github.com/json-path/JsonPath). | | \$1input.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)](https://velocity.apache.org/engine/devel/vtl-reference.html) 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').count()` gibt `"3"` zurück. Weitere Informationen zu JSONPath Java finden Sie unter [JSONPath](http://goessner.net/articles/JsonPath/)oder [JSONPath für Java](https://github.com/jayway/JsonPath). | | \$1stageVariables. | **steht für einen Stufenvariablennamen. | | \$1stageVariables[''] | **steht für einen beliebigen Stufenvariablennamen. | | \$1\$1stageVariables['']\$1 | **steht für einen beliebigen Stufenvariablennamen. | | \$1util.escapeJavaScript() | Escapiert die Zeichen in einer Zeichenfolge mithilfe von JavaScript Zeichenfolgenregeln. 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: 
 $util.escapeJavaScript(data).replaceAll("\\'","'")
| | \$1util.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
}
| | \$1util.urlEncode() | Konvertiert eine Zeichenfolge in das Format „application/x-www-form-urlencoded“. | | \$1util.urlDecode() | Dekodiert eine Zeichenfolge „application/x-www-form-urlencoded“. | | \$1util.base64Encode() | Codiert die Daten in eine base64-verschlüsselte Zeichenfolge. | | \$1util.base64Decode() | Decodiert die Daten einer base64-verschlüsselten Zeichenfolge. |