Verwenden der Lambda-Laufzeit-API für benutzerdefinierte Laufzeiten

AWS Lambda bietet eine HTTP-API für benutzerdefinierte Laufzeiten, um Aufrufereignisse von Lambda zu empfangen und Antwortdaten innerhalb der Lambda-Ausführungsumgebung zurückzusenden. Dieser Abschnitt enthält die API-Referenz für die Lambda-Laufzeiten-API.

Die OpenAPI-Spezifikation für die Laufzeit-API-Version 2018-06-01 ist unter runtime-api.zip verfügbar.

Um eine API-Anforderungs-URL zu erstellen, rufen Laufzeitumgebungen den API-Endpunkt aus der AWS_LAMBDA_RUNTIME_API-Umgebungsvariablen ab, fügen die API-Version und dann den gewünschten Ressourcenpfad hinzu.

curl "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/invocation/next"

Nächster Aufruf

Pfad – /runtime/invocation/next

Methode – GET

Die Laufzeit sendet diese Meldung an Lambda, um ein Aufrufereignis anzufordern. Der Antworttext enthält die Nutzlast aus dem Aufruf. Dabei handelt es sich um ein JSON-Dokument, das Ereignisdaten aus dem Funktionsauslöser enthält. Die Antwort-Header enthalten zusätzliche Daten zum Aufruf.

Legen Sie kein Timeout für die GET-Anfrage fest, da sich die Antwort verzögern könnte. Zwischen dem Zeitpunkt, an dem Lambda die Laufzeit bootet, und dem Zeitpunkt, zu dem die Laufzeit ein Ereignis zurückgibt, wird der Laufzeitprozess möglicherweise für mehrere Sekunden eingefroren.

Eine Anforderungs-ID (Lambda-Runtime-Aws-Request-Id) identifiziert ein eindeutiges Ereignis. Anforderungs-IDs werden von Ereignisquellen bereitgestellt oder von Lambda bei der Aufnahme automatisch generiert. Verwenden Sie die Anforderungs-ID im URL-Pfad, wenn Sie die Antwort oder den Fehler senden.

Eine Aufruf-ID (Lambda-Runtime-Invocation-Id) steht für einen einzelnen Aufrufversuch für ein Ereignis. Eine einzelne Anforderungs-ID kann zu mehreren Aufrufversuchen führen, von denen jeder seine eigene eindeutige Aufruf-ID hat. Lambda verwendet jede Aufruf-ID genau einmal und verwendet sie nie wieder. Gibt diesen Wert erneut an und ruft auf. /response /error Der Header ist aus Gründen der Abwärtskompatibilität mit vorhandenen Laufzeiten optional. Wenn Sie ihn weglassen, wird keine Ablehnung ausgelöst. Lambda lehnt nur ab, 400 InvalidInvocationId wenn der Header vorhanden ist, sein Wert aber nicht mit dem aktiven Aufruf übereinstimmt.

Der Nachverfolgungs-Header enthält die Nachverfolgungs-ID, die ID des übergeordneten Segments und die Erfassungsentscheidung Wenn die Anforderung erfasst wurde, wurde die Anforderung von Lambda oder einem Upstream-Service erfasst. Die Laufzeit sollte die _X_AMZN_TRACE_ID auf den Wert des Headers festlegen. Das X-Ray SDK liest dies, um die IDs abzurufen und zu bestimmen, ob die Anfrage verfolgt werden soll.

Aufrufantwort

Pfad – /runtime/invocation/AwsRequestId/response

Methode – POST

Nachdem die Funktion bis zum Abschluss ausgeführt wurde, schickt die Laufzeitumgebung eine Aufrufantwort an Lambda. Im Fall synchroner Aufrufe schickt Lambda die Antwort anschließend an den Client zurück.

Anfordern von Headern

Lambda-Runtime-Invocation-Id— Gibt den Wert zurück, der von empfangen wurde/next. Lambda lehnt die Anfrage ab, 400 InvalidInvocationId wenn der Wert nicht mit dem aktiven Aufruf übereinstimmt.

REQUEST_ID=156cb537-e2d4-11e8-9b34-d36013741fb9
INVOCATION_ID=<value from Lambda-Runtime-Invocation-Id response header>
curl "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/invocation/$REQUEST_ID/response"  -d "SUCCESS" --header "Lambda-Runtime-Invocation-Id: $INVOCATION_ID"

Initialisierungsfehler

Wenn die Funktion einen Fehler zurückgibt oder die Laufzeit während der Initialisierung auf einen Fehler stößt, verwendet die Laufzeit diese Methode, um den Fehler an Lambda zu melden.

Pfad – /runtime/init/error

Methode – POST

Header

Lambda-Runtime-Function-Error-Type – Der Fehlertyp, auf den die Laufzeit gestoßen ist. Dieser Header ist optional. Lambda akzeptiert jeden Zeichenkettenwert. Wir empfehlen, das Format zu verwenden<Category.Reason>, in dem Kategorie Runtime oder ist Function und Reason mit einem Großbuchstaben beginnt. Beispiel:

Werte, die diesem Muster nicht entsprechen, werden auf Runtime.Unknown oder Function.Unknown normalisiert.

Body-Parameter

ErrorRequest – Informationen über den Fehler. Erforderlich: Nein

Dieses Feld ist ein JSON-Objekt mit der folgenden Struktur:

{
      errorMessage: string (text description of the error),
      errorType: string,
      stackTrace: array of strings
}

Beachten Sie, dass Lambda jeden Wert für errorType akzeptiert.

Das folgende Beispiel zeigt eine Lambda-Funktionsfehlermeldung, in der die Funktion die im Aufruf bereitgestellten Ereignisdaten nicht analysieren konnte.

{
      "errorMessage" : "Error parsing event data.",
      "errorType" : "InvalidEventDataException",
      "stackTrace": [ ]
}      

ERROR="{\"errorMessage\" : \"Failed to load function.\", \"errorType\" : \"InvalidFunctionException\"}"
curl "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/init/error" -d "$ERROR" --header "Lambda-Runtime-Function-Error-Type: Unhandled"

Aufruffehler

Wenn die Funktion einen Fehler zurückgibt oder die Laufzeit auf einen Fehler stößt, verwendet die Laufzeitumgebung diese Methode, um den Fehler an Lambda zu melden.

Pfad – /runtime/invocation/AwsRequestId/error

Methode – POST

Header

Lambda-Runtime-Function-Error-Type – Der Fehlertyp, auf den die Laufzeit gestoßen ist. Erforderlich: Nein.

Dieser Header besteht aus einem Zeichenfolgen-Wert. Lambda akzeptiert jede Zeichenfolge, aber wir empfehlen ein Format von <category.reason>. Beispiel:

Lambda-Runtime-Invocation-Id— Gibt den Wert zurück, der von empfangen wurde/next. Lambda lehnt die Anfrage ab, 400 InvalidInvocationId wenn der Wert nicht mit dem aktiven Aufruf übereinstimmt.

Body-Parameter

ErrorRequest – Informationen über den Fehler. Erforderlich: Nein

Dieses Feld ist ein JSON-Objekt mit der folgenden Struktur:

{
      errorMessage: string (text description of the error),
      errorType: string,
      stackTrace: array of strings
}

Beachten Sie, dass Lambda jeden Wert für errorType akzeptiert.

Das folgende Beispiel zeigt eine Lambda-Funktionsfehlermeldung, in der die Funktion die im Aufruf bereitgestellten Ereignisdaten nicht analysieren konnte.

{
      "errorMessage" : "Error parsing event data.",
      "errorType" : "InvalidEventDataException",
      "stackTrace": [ ]
}      

REQUEST_ID=156cb537-e2d4-11e8-9b34-d36013741fb9
ERROR="{\"errorMessage\" : \"Error parsing event data.\", \"errorType\" : \"InvalidEventDataException\"}"
curl "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/invocation/$REQUEST_ID/error" -d "$ERROR" --header "Lambda-Runtime-Function-Error-Type: Unhandled"

After-Restore (gilt nur für SnapStart)

Pfad – /runtime/restore/next

Methode – GET

Nachdem die Pre-Snapshot-Hooks abgeschlossen sind, wird die Runtime aufgerufen. GET /runtime/restore/next Dies ist ein Blockierungsaufruf im Iterator-Stil, ähnlich dem/runtime/invocation/next, der Lambda signalisiert, dass die Laufzeit bereit ist, einen Snapshot der Ausführungsumgebung zu erstellen. Die Anforderung wird blockiert, bis Lambda die Ausführungsumgebung anhand eines Snapshots wiederherstellt, und gibt dann eine HTTP 200-Antwort mit leerem Text zurück.

Header

Keine Header erforderlich.

Erforderliche Syntax

GET /2018-06-01/runtime/restore/next HTTP/1.1
Host: ${AWS_LAMBDA_RUNTIME_API}

Antwortsyntax

HTTP/1.1 200 OK
Content-Length: 0

Wiederherstellungsfehler (gilt nur für SnapStart)

Wenn ein Hook nach der Wiederherstellung fehlschlägt oder die Laufzeit während der Wiederherstellung auf einen Fehler stößt, verwendet die Runtime diese Methode, um den Fehler an Lambda zu melden. Lambda schlägt den In-Flight-Aufruf fehl und zerstört die Ausführungsumgebung.

Pfad – /runtime/restore/error

Methode – POST

Header

Lambda-Runtime-Function-Error-Type – Der Fehlertyp, auf den die Laufzeit gestoßen ist. Dieser Header ist optional. Lambda akzeptiert jeden Zeichenkettenwert. Wir empfehlen, das Format zu verwenden<Category.Reason>, in dem Kategorie Runtime oder ist Function und Reason mit einem Großbuchstaben beginnt (z. B.Runtime.AfterRestoreError). Werte, die diesem Muster nicht entsprechen, werden auf oder normalisiert. Runtime.Unknown Function.Unknown

POST /2018-06-01/runtime/restore/error HTTP/1.1
Host: ${AWS_LAMBDA_RUNTIME_API}
Lambda-Runtime-Function-Error-Type: Runtime.AfterRestoreError

HTTP/1.1 202 Accepted
Content-Type: application/json

{"status":"OK"}