Lambda 関数 URL の呼び出し

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

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

注記

関数 URLsは、アジアパシフィック (ハイデラバード) (ap-south-2）、アジアパシフィック (メルボルン) ()、ap-southeast-4カナダ西部 (カルガリー) ()、ca-west-1欧州 (スペイン) ()、eu-south-2欧州 (チューリッヒ) ()、eu-central-2イスラエル (テルアビブ) ()、il-central-1中東 (アラブ首長国連邦) () の各リージョンではサポートされていませんme-central-1。

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

関数 URL 呼び出しの基本

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

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

関数 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 '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 文字列。サポートされている文字は、a-z、A-Z、0-9、.、_、-、%、&、=、+ などです。	"?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 (ユーザー 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 メソッド。有効な値には、GET、POST、PUT、HEAD、OPTIONS、PATCH および 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 は以下のような想定を立てます。

• statusCode は 200。

• content-type は application/json。

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

• isBase64Encoded は false。

次の例は、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!" }