Lambda 関数 URL の呼び出し - AWS Lambda

Lambda 関数 URL の呼び出し

関数 URL は、Lambda 関数のための専用 HTTP エンドポイントです。関数 URL の作成と設定には、Lambda コンソールまたは Lambda API を使用します。関数 URL を作成すると、一意の URL エンドポイントが Lambda により自動的に生成されます。関数 URL を作成した後に、その URL エンドポイントが変更されることはありません。関数 URL のエンドポイントでは、次の形式を使用します。

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

関数 URL はデュアルスタックに対応しており、IPv4 と IPv6 をサポートしています。関数 URL の設定が完了すると、ウェブブラウザ、curl、Postman、または任意の HTTP クライアントからの、HTTP エンドポイントを介した関数の呼び出しが可能になります。関数 URL を呼び出すには、アクセス許可 lambda:InvokeFunctionUrl が必要です。詳しくは、「セキュリティと認証モデル」を参照してください。

関数 URL 呼び出しの基本

関数 URL が認証タイプに AWS_IAM を使用している場合、各 HTTP リクエストには、AWS Signature Version 4 (SigV4) による署名が必要です。awscurlPostman、および AWS SigV4 Proxy などのツールには、Sigv4 でリクエストに署名するための方法が既に組み込まれています。

関数 URL への HTTP リクエストの署名にツールを使用しない場合は、各リクエストには、SigV4 を使用して手動で署名する必要があります。関数 URL がリクエストを受信すると、Lambda が Sigv4 署名の処理を行います。署名が一致した場合のみ、Lambda によりリクエストが処理されます。SigV4 を使用してリクエストに手動で署名する方法については、「Amazon Web Services General Reference Guide」(アマゾンウェブサービス全般リファレンスガイド) の「Signing AWS requests with Signature Version 4」(署名バージョン 4 を使用した リクエストへの署名) を参照してください。

関数 URL が認証タイプに NONE を使用している場合は、リクエストには Sigv4 を使用した署名の必要はありません。ウェブブラウザ、curl、Postman、または任意の HTTP クライアントを使用して関数を呼び出すことができます。

関数へのシンプルな GET リクエストをテストするには、ウェブブラウザを使用します。例えば、関数 URL が https://abcdefg.lambda-url.us-east-1.on.aws で文字列パラメータ message を取り込む関数の場合、リクエストする URL は次のようになります。

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

POST リクエストなど、他の HTTP リクエストをテストする場合は、curl などのツールが利用できます。例えば、関数 URL への POST リクエストに一定の JSON データを含めたい場合には、次の curl コマンドを使用します。

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

リクエストとレスポンスのペイロード

クライアントが関数の URL を呼び出すと、Lambda は、まずこのリクエストをイベントオブジェクトにマップしてから、関数に受け渡します その関数の応答は、Lambda が関数 URL を介してクライアントに返信する HTTP レスポンスにマッピングされます。

このリクエストとレスポンスのイベント形式は、Amazon API Gateway ペイロード形式バージョン 2.0 と同じスキーマに従います。

リクエストペイロードの形式

リクエストペイロードは次の構造を持ちます。

{ "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 }
パラメータ 説明

version

このイベントでのペイロード形式のバージョン。現在 Lambda 関数 URL では、ペイロード形式バージョン 2.0 をサポートしています。

2.0

routeKey

関数 URL ではこのパラメーターを使用しません。Lambda は、プレースホルダーとしてこの値に $default を設定します。

$default

rawPath

リクエストパス。例えば、リクエスト URL が https://{url-id}.lambda-url.{region}.on.aws/example/test/demo の場合は、raw パス値は /example/test/demo となります。

/example/test/demo

rawQueryString

リクエストのクエリ文字列パラメータを含む raw 文字列。

"?parameter1=value1&parameter2=value2"

cookies

リクエストの一部として送信されたすべての Cookie を含む配列。

["Cookie_1=Value_1", "Cookie_2=Value_2"]

headers

キーと値のペアで表されるリクエストヘッダーのリスト。

{"header1": "value1", "header2": "value2"}

queryStringParameters

リクエストに対するクエリパラメータです。例えば、リクエスト URL が https://{url-id}.lambda-url.{region}.on.aws/example?name=Jane である場合の queryStringParameters の値は、キーに name を、値に Jane を持つ、JSON オブジェクトとなります

{"name": "Jane"}

requestContext

リクエストに関する追加的な情報 (requestId、リクエストの発行時刻、および AWS Identity and Access Management (IAM) 経由で承認された場合は発信者の身元、その他) を含むオブジェクト。

requestContext.accountId

関数所有者の AWS アカウント ID。

"123456789012"

requestContext.apiId

関数 URL ID。

"33anwqw8fj"

requestContext.authentication

関数 URL ではこのパラメーターを使用しません。Lambda では null がセットされます。

null

requestContext.authorizer

関数 URL で AWS_IAM の認証タイプが使用されている場合の、発信者の ID に関する情報を含むオブジェクト。それ以外の場合、Lambda はこれに null をセットします。

requestContext.authorizer.iam.accessKey

発信者 ID のアクセスキー。

"AKIAIOSFODNN7EXAMPLE"

requestContext.authorizer.iam.accountId

発信者の AWS アカウント ID。

"111122223333"

requestContext.authorizer.iam.callerId

発信者の ID (IAM ユーザー ID)。

"AIDACKCEVSQ6C2EXAMPLE"

requestContext.authorizer.iam.cognitoIdentity

関数 URL ではこのパラメーターを使用しません。Lambda は、この値に null を設定するか、JSON からこれを除外します。

null

requestContext.authorizer.iam.principalOrgId

発信者の身元に関連付けられているプリンシパル組織 ID。

"AIDACKCEVSQORGEXAMPLE"

requestContext.authorizer.iam.userArn

発信者の身元のユーザー Amazon リソースネーム (ARN)。

"arn:aws:iam::111122223333:user/example-user"

requestContext.authorizer.iam.userId

発信者の身元のユーザー ID。

"AIDACOSFODNN7EXAMPLE2"

requestContext.domainName

関数 URL のドメイン名。

"<url-id>.lambda-url.us-west-2.on.aws"

requestContext.domainPrefix

関数 URL のドメインプレフィックス。

"<url-id>"

requestContext.http

HTTP リクエストの詳細を含むオブジェクト。

requestContext.http.method

リクエストで使用されている HTTP メソッド。有効な値には、GETPOSTPUTHEADOPTIONSPATCH および DELETE があります。

GET

requestContext.http.path

リクエストパス。例えば、リクエスト URL が https://{url-id}.lambda-url.{region}.on.aws/example/test/demo であれば、パス値は /example/test/demo となります。

/example/test/demo

requestContext.http.protocol

リクエストのプロトコル。

HTTP/1.1

requestContext.http.sourceIp

リクエストを発行した即時 TCP 接続のソース IP アドレス。

123.123.123.123

requestContext.http.userAgent

User-Agent リクエストヘッダー値。

Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) Gecko/20100101 Firefox/42.0

requestContext.requestId

呼び出しリクエストの ID。この ID は、関数に関連する呼び出しログをトレースするために使用できます。

e1506fd5-9e7b-434f-bd42-4f8fa224b599

requestContext.routeKey

関数 URL ではこのパラメーターを使用しません。Lambda は、プレースホルダーとしてこの値に $default を設定します。

$default

requestContext.stage

関数 URL ではこのパラメーターを使用しません。Lambda は、プレースホルダーとしてこの値に $default を設定します。

$default

requestContext.time

リクエストのタイムスタンプです。

"07/Sep/2021:22:50:22 +0000"

requestContext.timeEpoch

リクエストのタイムスタンプ (Unix エポック秒)。

"1631055022677"

body

リクエスト本文。リクエストのコンテンツタイプがバイナリの場合、本文は base64 でエンコードされます。

{"key1": "value1", "key2": "value2"}

pathParameters

関数 URL ではこのパラメーターを使用しません。Lambda は、この値に null を設定するか、JSON からこれを除外します。

null

isBase64Encoded

ボディがバイナリペイロードで base64 でエンコードされている場合は TRUE、それ以外の場合は FALSE です。

FALSE

stageVariables

関数 URL ではこのパラメーターを使用しません。Lambda は、この値に null を設定するか、JSON からこれを除外します。

null

レスポンスペイロードの形式

関数からレスポンスが返されると、Lambda はそのレスポンスを解析し HTTP の形式に変換します。関数レスポンスペイロードの形式は以下のとおりです。

{ "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 は自動的にレスポンス形式を推定します。関数が有効な JSON を返し、かつ statusCode を返さない場合、Lambda は以下のような想定を立てます。

  • statusCode200

  • content-typeapplication/json

  • body は関数のレスポンス。

  • isBase64Encodedfalse

次の例は、Lambda 関数の出力がレスポンスペイロードにどのようにマッピングされるか、また、レスポンスペイロードが最終的な HTTP レスポンスにどのようにマッピングされるかを示しています。関数の URL を呼び出したクライアントには、HTTP 応答が表示されます。

文字列による応答の出力例
Lambda 関数出力 インタプリティングされたレスポンス出力 HTTP レスポンス (クライアントに表示されるもの)
"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!"
JSON によるレスポンスの出力例
Lambda 関数出力 インタプリティングされたレスポンス出力 HTTP レスポンス (クライアントに表示されるもの)
{ "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!" }
カスタムレスポンスでの出力例
Lambda 関数出力 インタプリティングされたレスポンス出力 HTTP レスポンス (クライアントに表示されるもの)
{ "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!" }

cookie

関数から Cookie を返す場合、手動で set-cookie ヘッダーを追加しないでください。代わりに、レスポンスペイロードオブジェクトに Cookie を含めます。Lambda はこれを自動的に解釈し、次の例のように HTTP レスポンスの set-cookie ヘッダーとして追加します。

クッキーを返すレスポンスの出力例
Lambda 関数出力 HTTP レスポンス (クライアントに表示されるもの)
{ "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!" }