Aufrufen von Lambda-Funktions-URLs - AWS Lambda
Grundlagen des Aufrufs von Funktions-URLsAnfordern und Beantworten von Nutzlasten

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.

Tipp

Lambda bietet zwei Möglichkeiten, Ihre Funktion über einen HTTP-Endpunkt aufzurufen: Funktions-URLs und Amazon API Gateway. Wenn Sie sich nicht sicher sind, welche Methode für Ihren Anwendungsfall am besten geeignet ist, siehe Wählen Sie eine Methode, um Ihre Lambda-Funktion über eine HTTP-Anfrage aufzurufen.

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 AWS-Regionen nicht unterstützt: Asien-Pazifik (Hyderabad) (ap-south-2), Asien-Pazifik (Melbourne) (ap-southeast-4), Asien-Pazifik (Malaysia) (ap-southeast-5), Asien-Pazifik (Neuseeland) (ap-southeast-6), Asien-Pazifik (Thailand) (ap-southeast-7), Asien-Pazifik (Taipeh) (ap-east-2), 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- und lambda:InvokeFunction-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 Postman bieten integrierte Möglichkeiten, Ihre Anforderungen 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 is 200.

    Anmerkung

    Die gültigen statusCode liegen im Bereich von 100 bis 599.

  • content-type is application/json.

  • body ist die Antwort der Funktion.

  • isBase64Encoded is 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.

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!"
}