Aufrufen von Lambda-Funktions-URLs

Eine Funktions-URL ist ein dedizierter HTTPS-Endpunkt für Ihre Lambda-Funktion. Sie können eine Funktions-URL über die Lambda-Konsole oder die Lambda-API erstellen und konfigurieren. Wenn Sie eine Funktions-URL erstellen, generiert Lambda automatisch einen eindeutigen URL-Endpunkt für Sie. Sobald Sie eine Funktions-URL erstellt haben, ändert sich ihr URL-Endpunkt nie mehr. Funktions-URL-Endpunkte haben das folgende Format:

https://<url-id>.lambda-url.<region>.on.aws

Anmerkung

Funktions-URLs werden in den folgenden Regionen nicht unterstützt: Asien-Pazifik (Hyderabad) (ap-south-2), Asien-Pazifik (Melbourne) (ap-southeast-4), Kanada West (Calgary) (ca-west-1), Europa (Spanien) (eu-south-2), Europa (Zürich) (eu-central-2), Israel (Tel Aviv) (il-central-1) und Naher Osten (VAE) (me-central-1).

Funktions-URLs sind Dual-Stack-fähig und unterstützen IPv4 und IPv6. Nachdem Sie Ihre Funktions-URL konfiguriert haben, können Sie Ihre Funktion über ihren HTTP(S)-Endpunkt über einen Webbrowser, cURL, Postman oder einen beliebigen HTTP-Client aufrufen. Um eine Funktions-URL aufzurufen, müssen Sie lambda:InvokeFunctionUrl-Berechtigungen haben. Weitere Informationen finden Sie unter Zugriffskontrolle.

Grundlagen des Aufrufs von Funktions-URLs

Wenn Ihre Funktions-URL den Auth-Typ AWS_IAM hat, müssen Sie jede HTTP-Anfrage mit der AWS Signature Version 4 (SigV4) signieren. Tools wie awscurl, Postman und AWSSigV4-Proxy bieten integrierte Möglichkeiten, Ihre Anfragen mit SigV4 zu signieren.

Wenn Sie kein Tool verwenden, um HTTP-Anfragen an Ihre Funktions-URL zu signieren, müssen Sie jede Anfrage manuell mit SigV4 signieren. Wenn Ihre Funktions-URL eine Anfrage erhält, berechnet Lambda auch die SigV4-Signatur. Nur wenn die Signaturen übereinstimmen, verarbeitet Lambda die Anfrage. Anweisungen zum manuellen Signieren Ihrer Anforderungen mit SigV4 finden Sie unter Signieren von AWS-Anforderungen mit Signature Version 4 im Allgemeine Amazon Web Services-Referenz.

Wenn Ihre Funktions-URL den Authentifizierungstyp NONE verwendet, müssen Sie Ihre Anfragen nicht mit SigV4 signieren. Sie können Ihre Funktion per Webbrowser, cURL, Postman oder einem beliebigen HTTP-Client aufrufen.

Um einfache GET-Anfragen an Ihre Funktion zu testen, verwenden Sie einen Webbrowser. Wenn Ihre Funktions-URL zum Beispiel https://abcdefg.lambda-url.us-east-1.on.aws ist und sie einen Zeichenfolgeparameter message aufnimmt, könnte Ihre Anforderungs-URL folgendermaßen aussehen:

https://abcdefg.lambda-url.us-east-1.on.aws/?message=HelloWorld

Um andere HTTP-Anfragen zu testen, z. B. eine POST-Anfrage, können Sie ein Tool wie cURL verwenden. Wenn Sie z. B. einige JSON-Daten in eine POST-Anfrage an Ihre Funktions-URL aufnehmen möchten, können Sie den folgenden cURL-Befehl verwenden:

curl -v 'https://abcdefg.lambda-url.us-east-1.on.aws/?message=HelloWorld' \
-H 'content-type: application/json' \
-d '{ "example": "test" }'

Anfordern und Beantworten von Nutzlasten

Wenn ein Client Ihre Funktions-URL aufruft, ordnet Lambda die Anforderung einem Ereignisobjekt zu, bevor es sie an Ihre Funktion übergibt. Die Antwort Ihrer Funktion wird dann einer HTTP-Antwort zugeordnet, die Lambda über die Funktions-URL an den Client zurücksendet.

Die Formate für Anforderungs- und Antwortereignisse folgen dem gleichen Schema wie die Amazon-API-Gateway-Nutzlastformatversion 2.0.

Anforderungsnutzlastformat

Eine Anforderungsnutzlast hat die folgende Struktur:

{
  "version": "2.0",
  "routeKey": "$default",
  "rawPath": "/my/path",
  "rawQueryString": "parameter1=value1&parameter1=value2&parameter2=value",
  "cookies": [
    "cookie1",
    "cookie2"
  ],
  "headers": {
    "header1": "value1",
    "header2": "value1,value2"
  },
  "queryStringParameters": {
    "parameter1": "value1,value2",
    "parameter2": "value"
  },
  "requestContext": {
    "accountId": "123456789012",
    "apiId": "<urlid>",
    "authentication": null,
    "authorizer": {
        "iam": {
                "accessKey": "AKIA...",
                "accountId": "111122223333",
                "callerId": "AIDA...",
                "cognitoIdentity": null,
                "principalOrgId": null,
                "userArn": "arn:aws:iam::111122223333:user/example-user",
                "userId": "AIDA..."
        }
    },
    "domainName": "<url-id>.lambda-url.us-west-2.on.aws",
    "domainPrefix": "<url-id>",
    "http": {
      "method": "POST",
      "path": "/my/path",
      "protocol": "HTTP/1.1",
      "sourceIp": "123.123.123.123",
      "userAgent": "agent"
    },
    "requestId": "id",
    "routeKey": "$default",
    "stage": "$default",
    "time": "12/Mar/2020:19:03:58 +0000",
    "timeEpoch": 1583348638390
  },
  "body": "Hello from client!",
  "pathParameters": null,
  "isBase64Encoded": false,
  "stageVariables": null
}

Parameter	Beschreibung	Beispiel
version	Die Nutzlastformatversion für dieses Ereignis. Lambda-Funktions-URLs unterstützen derzeit die Nutzlastformatversion 2.0.	2.0
routeKey	Funktions-URLs verwenden diesen Parameter nicht. Lambda setzt dies auf $default als Platzhalter.	$default
rawPath	Der Anforderungspfad. Wenn die Anforderungs-URL beispielsweise https://{url-id}.lambda-url.{region}.on.aws/example/test/demo ist, dann ist der Rohpfadwert /example/test/demo.	/example/test/demo
rawQueryString	Die Rohzeichenfolge, die die Abfragezeichenfolge-Parameter der Anforderung enthält. Zu den unterstützten Zeichen gehören a-z, A-Z, 0-9, ., _, -, %, &, =, und +.	"?parameter1=value1&parameter2=value2"
cookies	Ein Array, das alle Cookies enthält, die im Rahmen der Anforderung gesendet wurden.	["Cookie_1=Value_1", "Cookie_2=Value_2"]
headers	Die Liste der Anforderungs-Header, die als Schlüssel-Wert-Paare dargestellt werden.	{"header1": "value1", "header2": "value2"}
queryStringParameters	Die Abfrageparameter für die Anforderung. Wenn die Anforderungs-URL beispielsweise https://{url-id}.lambda-url.{region}.on.aws/example?name=Jane ist, dann ist der queryStringParameters-Wert ein JSON-Objekt mit einem Schlüssel von name und einem Wert von Jane.	{"name": "Jane"}
requestContext	Ein Objekt, das zusätzliche Informationen über die Anforderung enthält, z. B. requestId, den Zeitpunkt der Anfrage und die Identität des Anrufers, falls über AWS Identity and Access Management (IAM) autorisiert.
requestContext.accountId	Die AWS-Konto-ID des Funktionsbesitzers.	"123456789012"
requestContext.apiId	Die ID der Funktions-URL.	"33anwqw8fj"
requestContext.authentication	Funktions-URLs verwenden diesen Parameter nicht. Lambda setzt dies auf null.	null
requestContext.authorizer	Ein Objekt, das Informationen über die Aufruferidentität enthält, wenn die Funktions-URL den Authentifizierungstyp AWS_IAM verwendet. Ansonsten setzt Lambda dies auf null.
requestContext.authorizer.iam.accessKey	Der Zugriffsschlüssel der Anruferidentität.	"AKIAIOSFODNN7EXAMPLE"
requestContext.authorizer.iam.accountId	Die AWS-Konto-Identitäts-ID des Anrufers.	"111122223333"
requestContext.authorizer.iam.callerId	Die ID (Benutzer-ID) des Aufrufers.	"AIDACKCEVSQ6C2EXAMPLE"
requestContext.authorizer.iam.cognitoIdentity	Funktions-URLs verwenden diesen Parameter nicht. Lambda setzt dies auf null oder schließt dies aus der JSON aus.	null
requestContext.authorizer.iam.principalOrgId	Die Prinzipal-Organisations-ID, die mit der Anruferidentität verknüpft ist.	"AIDACKCEVSQORGEXAMPLE"
requestContext.authorizer.iam.userArn	Der Benutzer-ARN (Amazon-Ressourcenname) der Anruferidentität.	"arn:aws:iam::111122223333:user/example-user"
requestContext.authorizer.iam.userId	Die Benutzer-ID des Anrufers.	"AIDACOSFODNN7EXAMPLE2"
requestContext.domainName	Der Domain-Name der Funktions-URL.	"<url-id>.lambda-url.us-west-2.on.aws"
requestContext.domainPrefix	Das Domain-Präfix der Funktions-URL.	"<url-id>"
requestContext.http	Ein Objekt, das Details zur HTTP-Anforderung enthält.
requestContext.http.method	Die in der Anforderung verwendete HTTP-Methode. Gültige Werte sind unter anderem GET, POST, PUT, HEAD, OPTIONS, PATCH und DELETE.	GET
requestContext.http.path	Der Anforderungspfad. Zum Beispiel, wenn die Anforderungs-URL https://{url-id}.lambda-url.{region}.on.aws/example/test/demo ist, dann ist der Pfadwert /example/test/demo.	/example/test/demo
requestContext.http.protocol	Das Protokoll der Anforderung.	HTTP/1.1
requestContext.http.sourceIp	Die Quell-IP-Adresse der TCP-Verbindung, von der die Anforderung stammt.	123.123.123.123
requestContext.http.userAgent	Der Headerwert der Benutzer-Agent-Anforderung.	Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) Gecko/20100101 Firefox/42.0
requestContext.requestId	Die ID der aktuellen Aufrufanforderung. Sie können diese ID verwenden, um Aufrufprotokolle zu verfolgen, die sich auf Ihre Funktion beziehen.	e1506fd5-9e7b-434f-bd42-4f8fa224b599
requestContext.routeKey	Funktions-URLs verwenden diesen Parameter nicht. Lambda setzt dies auf $default als Platzhalter.	$default
requestContext.stage	Funktions-URLs verwenden diesen Parameter nicht. Lambda setzt dies auf $default als Platzhalter.	$default
requestContext.time	Der Zeitstempel der Anfrage.	"07/Sep/2021:22:50:22 +0000"
requestContext.timeEpoch	Die Uhrzeit der Anfrage in Unix-Epochen-Zeit.	"1631055022677"
body	Der Text der Anforderung. Wenn der Inhaltstyp der Anforderung binär ist, ist der Text base64-kodiert.	{"key1": "value1", "key2": "value2"}
pathParameters	Funktions-URLs verwenden diesen Parameter nicht. Lambda setzt dies auf null oder schließt dies aus der JSON aus.	null
isBase64Encoded	TRUE, wenn der Text eine binäre Nutzlast hat und base64-kodiert ist. Ansonsten FALSE.	FALSE
stageVariables	Funktions-URLs verwenden diesen Parameter nicht. Lambda setzt dies auf null oder schließt dies aus der JSON aus.	null

Antwortnutzlastformat

Wenn Ihre Funktion eine Antwort zurückgibt, analysiert Lambda die Antwort und konvertiert sie in eine HTTP-Antwort. Funktionsantwortnutzlasten haben das folgende Format:

{
   "statusCode": 201,
    "headers": {
        "Content-Type": "application/json",
        "My-Custom-Header": "Custom Value"
    },
    "body": "{ \"message\": \"Hello, world!\" }",
    "cookies": [
        "Cookie_1=Value1; Expires=21 Oct 2021 07:48 GMT",
        "Cookie_2=Value2; Max-Age=78000"
    ],
    "isBase64Encoded": false
}

Lambda leitet das Antwortformat für Sie ab. Wenn Ihre Funktion gültiges JSON zurückgibt und keinen statusCode zurückgibt, geht Lambda von Folgendem aus:

• statusCode ist 200.

• content-type ist application/json.

• body ist die Antwort der Funktion.

• isBase64Encoded ist false.

Die folgenden Beispiele zeigen, wie die Ausgabe Ihrer Lambda-Funktion der Antwortnutzlast und die Antwortnutzlast der endgültigen HTTP-Antwort zugeordnet wird. Wenn der Client Ihre Funktions-URL aufruft, wird die HTTP-Antwort angezeigt.

Beispielausgabe für eine Zeichenfolgeantwort
Lambda-Funktionsausgabe	Interpretierte Antwortausgabe	HTTP-Antwort (was der Client sieht)
"Hello, world!"	{ "statusCode": 200, "body": "Hello, world!", "headers": { "content-type": "application/json" }, "isBase64Encoded": false }	HTTP/2 200 date: Wed, 08 Sep 2021 18:02:24 GMT content-type: application/json content-length: 15 "Hello, world!"

Beispielausgabe für eine JSON-Antwort
Lambda-Funktionsausgabe	Interpretierte Antwortausgabe	HTTP-Antwort (was der Client sieht)
{ "message": "Hello, world!" }	{ "statusCode": 200, "body": { "message": "Hello, world!" }, "headers": { "content-type": "application/json" }, "isBase64Encoded": false }	HTTP/2 200 date: Wed, 08 Sep 2021 18:02:24 GMT content-type: application/json content-length: 34 { "message": "Hello, world!" }

Beispielausgabe für eine benutzerdefinierte Antwort
Lambda-Funktionsausgabe	Interpretierte Antwortausgabe	HTTP-Antwort (was der Client sieht)
{ "statusCode": 201, "headers": { "Content-Type": "application/json", "My-Custom-Header": "Custom Value" }, "body": JSON.stringify({ "message": "Hello, world!" }), "isBase64Encoded": false }	{ "statusCode": 201, "headers": { "Content-Type": "application/json", "My-Custom-Header": "Custom Value" }, "body": JSON.stringify({ "message": "Hello, world!" }), "isBase64Encoded": false }	HTTP/2 201 date: Wed, 08 Sep 2021 18:02:24 GMT content-type: application/json content-length: 27 my-custom-header: Custom Value { "message": "Hello, world!" }

Cookies

Um Cookies von Ihrer Funktion zurückzugeben, fügen Sie set-cookie-Header nicht manuell hinzu. Fügen Sie stattdessen die Cookies in Ihr Antwortnutzlastobjekt ein. Lambda interpretiert dies automatisch und fügt sie als set-cookie-Header in Ihre HTTP-Antwort ein, wie im folgenden Beispiel gezeigt.

Beispielausgabe für eine Antwort, die Cookies zurückgibt
Lambda-Funktionsausgabe	HTTP-Antwort (was der Client sieht)
{ "statusCode": 201, "headers": { "Content-Type": "application/json", "My-Custom-Header": "Custom Value" }, "body": JSON.stringify({ "message": "Hello, world!" }), "cookies": [ "Cookie_1=Value1; Expires=21 Oct 2021 07:48 GMT", "Cookie_2=Value2; Max-Age=78000" ], "isBase64Encoded": false }	HTTP/2 201 date: Wed, 08 Sep 2021 18:02:24 GMT content-type: application/json content-length: 27 my-custom-header: Custom Value set-cookie: Cookie_1=Value2; Expires=21 Oct 2021 07:48 GMT set-cookie: Cookie_2=Value2; Max-Age=78000 { "message": "Hello, world!" }