Einrichten einer WebSocket-API-Integrationsanforderung in API Gateway - Amazon API Gateway
WebSocket-API-Integrationsanforderung mit der API Gateway-Konsole einrichtenEinrichten einer Integrationsanforderung mithilfe der AWS CLIEingabeformat einer Lambda-Funktion für die Proxy-Integration von WebSocket-APIs

Einrichten einer WebSocket-API-Integrationsanforderung in API Gateway

Das Einrichten einer Integrationsanforderung umfasst die folgenden Schritte:

  • Auswählen eines Routenschlüssels zum Integrieren im Backend.

  • Festlegen des aufzurufenden Backend-Endpunkts. WebSocket-APIs unterstützen die folgenden Integrationstypen:

    • AWS_PROXY

    • AWS

    • HTTP_PROXY

    • HTTP

    • MOCK

    Weitere Informationen zu Integrationstypen finden Sie unter IntegrationType in der API-Gateway-V2-REST-API.

  • Konfigurieren, wie die Routenanforderungsdaten bei Bedarf in Integrationsanforderungsdaten konvertiert werden, durch Angabe einer oder mehrerer Anforderungsvorlagen.

WebSocket-API-Integrationsanforderung mit der API Gateway-Konsole einrichten

So fügen Sie über die API Gateway-Konsole eine Integrationsanforderung zu einer Route in einer WebSocket-API hinzu:

  1. Melden Sie sich bei der API Gateway-Konsole an, wählen Sie die API und wählen Sie Routes (Routen).

  2. Wählen Sie unter Routes (Routen) die Route aus.

  3. Wählen Sie die Registerkarte Integration request (Integrationsanforderung) und dann im Abschnitt Integration request settings (Einstellungen für Integrationsanforderungen) die Option Edit (Bearbeiten) aus.

  4. Wählen Sie für Integration type (Integrationstyp) eine der folgenden Optionen:

    • Wählen Sie Lambda function (Lambda-Funktion) nur dann aus, wenn Ihre API mit einer AWS Lambda-Funktion integriert werden soll, die Sie bereits in diesem oder einem anderen Konto erstellt haben.

      Um eine neue Lambda-Funktion in AWS Lambda zu erstellen, eine Ressourcenberechtigung für die Lambda-Funktion festzulegen oder andere Lambda-Service-Aktionen durchzuführen, wählen Sie stattdessen AWS-Service.

    • Wählen Sie HTTP, wenn Ihre API in einen vorhandenen HTTP-Endpunkt integriert wird. Weitere Informationen finden Sie unter HTTP-Integrationen für REST-APIs in API Gateway.

    • Wählen Sie Mock, wenn Sie API-Antworten direkt von API Gateway generieren möchten, ohne dass ein Integrations-Backend erforderlich ist. Weitere Informationen finden Sie unter Pseudointegrationen für REST-APIs in API Gateway.

    • Wählen Sie AWS-Service, wenn Ihre API direkt in einen AWS-Service integriert wird.

    • Wählen Sie VPC Link (VPC-Link), wenn Ihre API einen VpcLink als privaten Integrations-Endpunkt verwenden wird. Weitere Informationen finden Sie unter Private Integrationen für REST-APIs in API Gateway.

  5. Wenn Sie Lambda Function (Lambda-Funktion) wählen, gehen Sie wie folgt vor:

    1. Markieren Sie unter Use Lambda Proxy integration (Lambda-Proxy-Integration verwenden) das Kontrollkästchen, wenn Sie die Lambda-Proxy-Integration oder die kontoübergreifende Lambda-Proxy-Integration verwenden möchten.

    2. Geben Sie für Lambda Function (Lambda-Funktion) die Funktion auf eine der folgenden Arten an:

      • Wenn sich Ihre Lambda-Funktion in demselben Konto befindet, geben Sie den Funktionsnamen ein und wählen Sie dann die Funktion aus der Dropdown-Liste aus.

        Anmerkung

        Der Funktionsname kann optional seinen Alias oder seine Versionsangabe, wie in HelloWorld, HelloWorld:1 oder HelloWorld:alpha, enthalten.

      • Wenn sich die Funktion in einem anderen Konto befindet, geben Sie den ARN für die Funktion ein.

    3. Wenn Sie den Timeout-Standardwert von 29 Sekunden verwenden möchten, lassen Sie das Kontrollkästchen Default timeout (Standardzeitüberschreitung) aktiviert. Wenn Sie einen benutzerdefinierten Zeitüberschreitungswert festlegen möchten, wählen Sie Default timeout (Standardzeitüberschreitung) aus und geben Sie einen Zeitüberschreitungswert zwischen 50 und 29000 Millisekunden ein.

  6. Befolgen Sie bei Wahl von HTTP die Anweisungen in Schritt 4 von API-Integrationsanfrage über die API Gateway-Konsole einrichten.

  7. Befolgen Sie bei Wahl von Mock (Pseudo) die Anweisungen unter dem Schritt Request Templates (Vorlagen anfordern).

  8. Befolgen Sie bei Wahl von AWS-Service die Anweisungen in Schritt 6 von API-Integrationsanfrage über die API Gateway-Konsole einrichten.

  9. Wenn Sie VPC Link (VPC-Link) ausgewählt haben, gehen Sie wie folgt vor:

    1. Markieren Sie für VPC proxy integration (Proxy-Integration verwenden) das Kontrollkästchen, wenn Anforderungen über einen Proxy an Ihren VPCLink-Endpunkt gesendet werden sollen.

    2. Wählen Sie als HTTP method die HTTP-Methode aus, die am ehesten der Methode im HTTP-Backend entspricht.

    3. Wählen Sie in der Dropdownliste VPC link (VPC-Link) einen VPC-Link aus. Sie können [Use Stage Variables] auswählen und ${stageVariables.vpcLinkId} in das Textfeld unter der Liste eingeben.

      Sie können die vpcLinkId-Stufenvariable nach der Bereitstellung der API für eine Stufe definieren und ihren Wert auf die ID des VpcLink festlegen.

    4. Geben Sie als Endpunkt-URL die URL des HTTP-Backends ein, das von dieser Integration verwendet werden soll.

    5. Wenn Sie die Standardzeitüberschreitung von 29 Sekunden verwenden möchten, lassen Sie das Kontrollkästchen Default timeout (Standardzeitüberschreitung) aktiviert. Wenn Sie einen benutzerdefinierten Zeitüberschreitungswert festlegen möchten, wählen Sie Default timeout (Standardzeitüberschreitung) aus und geben Sie einen Zeitüberschreitungswert zwischen 50 und 29000 Millisekunden ein.

  10. Klicken Sie auf Änderungen speichern.

  11. Führen Sie unter Request Templates (Vorlagen anfordern) die folgenden Schritte durch:

    1. Um einen Template selection expression (Vorlagen-Auswahlausdruck) einzugeben, wählen Sie unter Request templates (Vorlagen anfordern) die Option Edit (Bearbeiten).

    2. Geben Sie einen Template selection expression (Vorlagen-Auswahlausdruck) ein. Verwenden Sie einen Ausdruck, nach dem API Gateway in der Nachrichtennutzlast sucht. Wenn er gefunden wird, wird er ausgewertet. Das Ergebnis ist ein Vorlagen-Schlüsselwert zur Auswahl der Datenzuweisungsvorlage, die auf die Daten in der Nachrichtennutzlast anzuwenden ist. Die Datenzuweisungsvorlage erstellen Sie im nächsten Schritt. Wählen Sie Edit (Bearbeiten) aus, um Ihre Änderungen zu speichern.

    3. Wählen Sie Create template (Vorlage erstellen), um die Datenzuweisungsvorlage zu erstellen. Geben Sie für Template key (Vorlagenschlüssel) einen Vorlagenschlüsselwert zur Auswahl der Datenzuweisungsvorlage ein, die auf die Daten in der Nachrichtennutzlast anzuwenden ist. Definieren Sie anschließend eine Zuweisungsvorlage. Wählen Sie Create template (Vorlage erstellen) aus.

      Weitere Informationen zu Vorlagen-Auswahlausdrücken finden Sie unter Vorlagen-Auswahlausdrücke.

Einrichten einer Integrationsanforderung mithilfe der AWS CLI

Sie können eine Integrationsanforderung für eine Route in einer WebSocket-API wie im folgenden Beispiel mithilfe der AWS CLI erstellen, die eine Pseudo-Integration erstellt:

  1. Erstellen Sie eine Datei mit dem Namen integration-params.json und dem folgenden Inhalt:

    {"PassthroughBehavior": "WHEN_NO_MATCH", "TimeoutInMillis": 29000, "ConnectionType": "INTERNET", "RequestTemplates": {"application/json": "{\"statusCode\":200}"}, "IntegrationType": "MOCK"}

  2. Verwenden Sie den folgenden create-integration-Befehl, um die Mock-Integration zu erstellen.

    aws apigatewayv2 --region us-east-1 create-integration --api-id aabbccddee --cli-input-json file://integration-params.json

    Die Ausgabe sieht wie folgt aus:

    {
    "PassthroughBehavior": "WHEN_NO_MATCH",
    "TimeoutInMillis": 29000,
    "ConnectionType": "INTERNET",
    "IntegrationResponseSelectionExpression": "${response.statuscode}",
    "RequestTemplates": {
        "application/json": "{\"statusCode\":200}"
    },
    "IntegrationId": "0abcdef",
    "IntegrationType": "MOCK"
}

Alternativ können Sie eine Integrationsanforderung für eine Proxy-Integration mithilfe der AWS CLI einrichten:

  1. Erstellen Sie eine Lambda-Funktion in der Lambda-Konsole und geben Sie ihr eine grundlegende Lambda-Ausführungsrolle.

  2. Verwenden Sie den folgenden create-integration–Befehl, um eine Integration zu erstellen.

    aws apigatewayv2 create-integration --api-id aabbccddee --integration-type AWS_PROXY --integration-method POST --integration-uri arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123412341234:function:simpleproxy-echo-e2e/invocations

Die Ausgabe sieht wie folgt aus:

{
    "PassthroughBehavior": "WHEN_NO_MATCH",
    "IntegrationMethod": "POST",
    "TimeoutInMillis": 29000,
    "ConnectionType": "INTERNET",
    "IntegrationUri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123412341234:function:simpleproxy-echo-e2e/invocations",
    "IntegrationId": "abcdefg",
    "IntegrationType": "AWS_PROXY"
}

Eingabeformat einer Lambda-Funktion für die Proxy-Integration von WebSocket-APIs

Bei der Lambda-Proxy-Integration ordnet API Gateway die gesamte Client-Anforderung dem event-Eingabeparameter der Backend-Lambda-Funktion zu. Im folgenden Beispiel sehen Sie die Struktur des Eingabeereignisses der $connect-Route und des Eingabeereignisses der $disconnect-Route, die das API Gateway an eine Lambda-Proxy-Integration sendet.

Input from the $connect route
{
    headers: {
      Host: 'abcd123.execute-api.us-east-1.amazonaws.com',
      'Sec-WebSocket-Extensions': 'permessage-deflate; client_max_window_bits',
      'Sec-WebSocket-Key': '...',
      'Sec-WebSocket-Version': '13',
      'X-Amzn-Trace-Id': '...',
      'X-Forwarded-For': '192.0.2.1',
      'X-Forwarded-Port': '443',
      'X-Forwarded-Proto': 'https'
    },
    multiValueHeaders: {
      Host: [ 'abcd123.execute-api.us-east-1.amazonaws.com' ],
      'Sec-WebSocket-Extensions': [ 'permessage-deflate; client_max_window_bits' ],
      'Sec-WebSocket-Key': [ '...' ],
      'Sec-WebSocket-Version': [ '13' ],
      'X-Amzn-Trace-Id': [ '...' ],
      'X-Forwarded-For': [ '192.0.2.1' ],
      'X-Forwarded-Port': [ '443' ],
      'X-Forwarded-Proto': [ 'https' ]
    },
    requestContext: {
      routeKey: '$connect',
      eventType: 'CONNECT',
      extendedRequestId: 'ABCD1234=',
      requestTime: '09/Feb/2024:18:11:43 +0000',
      messageDirection: 'IN',
      stage: 'prod',
      connectedAt: 1707502303419,
      requestTimeEpoch: 1707502303420,
      identity: { sourceIp: '192.0.2.1' },
      requestId: 'ABCD1234=',
      domainName: 'abcd1234.execute-api.us-east-1.amazonaws.com',
      connectionId: 'AAAA1234=',
      apiId: 'abcd1234'
    },
    isBase64Encoded: false
  }
Input from the $disconnect route
{
    headers: {
      Host: 'abcd1234.execute-api.us-east-1.amazonaws.com',
      'x-api-key': '',
      'X-Forwarded-For': '',
      'x-restapi': ''
    },
    multiValueHeaders: {
      Host: [ 'abcd1234.execute-api.us-east-1.amazonaws.com' ],
      'x-api-key': [ '' ],
      'X-Forwarded-For': [ '' ],
      'x-restapi': [ '' ]
    },
    requestContext: {
      routeKey: '$disconnect',
      disconnectStatusCode: 1005,
      eventType: 'DISCONNECT',
      extendedRequestId: 'ABCD1234=',
      requestTime: '09/Feb/2024:18:23:28 +0000',
      messageDirection: 'IN',
      disconnectReason: 'Client-side close frame status not set',
      stage: 'prod',
      connectedAt: 1707503007396,
      requestTimeEpoch: 1707503008941,
      identity: { sourceIp: '192.0.2.1' },
      requestId: 'ABCD1234=',
      domainName: 'abcd1234.execute-api.us-east-1.amazonaws.com',
      connectionId: 'AAAA1234=',
      apiId: 'abcd1234'
    },
    isBase64Encoded: false
  }