Invoke
Lambda 関数を呼び出します。関数は、同期的に (レスポンスを待って)、または非同期的に呼び出すことが可能です。デフォルトでは、Lambda は関数を同期的に呼び出します (つまり InvocationType は RequestResponse です)。関数を非同期的に呼び出すには、InvocationType を Event に設定します。Lambda は、同期呼び出しの場合にのみ ClientContext オブジェクトを関数に渡します。
同期呼び出しの場合、エラーを含む関数レスポンスの詳細が、レスポンス本文とヘッダーに含まれます。どちらの呼び出しタイプについても、詳細は、実行ログおよびトレースに記載されています。
エラーが発生すると、関数が複数回呼び出される可能性があります。再試行の動作は、エラータイプ、クライアント、イベントソース、呼び出しタイプによって異なります。たとえば、関数を非同期に呼び出してエラーが返された場合、Lambda は関数を最大 2 回実行します。詳細については、「Lambda でのエラー処理と自動再試行」を参照してください。
非同期呼び出しの場合、Lambda はイベントを、関数に送信する前にキューに追加します。関数に、キューに対応する十分な容量がない場合、イベントが失われる可能性があります。場合によっては、エラーが発生しなくても、関数が同じイベントを複数回受信することがあります。処理されなかったイベントを保持するには、デッドレターキューで関数を設定します。
API レスポンスのステータスコードには、関数エラーは反映されません。エラーコードは、許可エラー、クォータエラー、または関数のコードと設定に関する問題など、関数の実行を妨げるエラーのためのものです。例えば、関数の実行がアカウントレベル (ConcurrentInvocationLimitExceeded) または関数レベル (ReservedFunctionConcurrentInvocationLimitExceeded) のいずれかで同時実行制限を超過する原因となる場合、Lambda は TooManyRequestsException を返します。
タイムアウトが長い関数では、同期呼び出し中、レスポンスを待っている間にクライアントが切断される場合があります。HTTP クライアント、SDK、ファイアウォール、プロキシ、またはオペレーティングシステムを構成して、タイムアウトまたはキープアライブ設定での長い接続を許可するようにしてください。
このオペレーションには lambda:InvokeFunction アクションに対するアクセス許可が必要です。クロスアカウントの呼び出しに対する許可を設定する方法の詳細については、他のアカウントに関数のアクセス権の付与を参照してください。
リクエストの構文
POST /2015-03-31/functions/FunctionName/invocations?Qualifier=Qualifier HTTP/1.1
X-Amz-Invocation-Type: InvocationType
X-Amz-Log-Type: LogType
X-Amz-Client-Context: ClientContext
PayloadURI リクエストパラメータ
リクエストでは、次の URI パラメータを使用します。
- ClientContext
-
コンテキストオブジェクトで関数に渡される、呼び出し側クライアントに関する最大 3,583 バイトの base64 でエンコードされたデータです。Lambda は、同期呼び出しの場合にのみ
ClientContextオブジェクトを関数に渡します。 - FunctionName
-
Lambda 関数、バージョン、またはエイリアスの名前。
名前の形式
-
関数名 –
my-function(名前のみ)、my-function:v1(エイリアス付き)。 -
関数 ARN –
arn:aws:lambda:us-west-2:123456789012:function:my-function。 -
部分的な ARN –
123456789012:function:my-function。
バージョン番号またはエイリアスを任意の形式に追加できます。完全な ARN にのみ適用される長さの制限。関数名のみを指定する場合、64 文字の長さに制限されます。
長さの制限: 最小長は 1 です。最大長は 170 です。
パターン:
(arn:(aws[a-zA-Z-]*)?:lambda:)?([a-z]{2}(-gov)?-[a-z]+-\d{1}:)?(\d{12}:)?(function:)?([a-zA-Z0-9-_\.]+)(:(\$LATEST|[a-zA-Z0-9-_]+))?必須: はい
-
- InvocationType
-
次のオプションから選択します。
-
RequestResponse(デフォルト) – 関数を同期的に呼び出します。関数がレスポンスを返すかタイムアウトするまで、接続を開いたままにします。API レスポンスには、関数レスポンスと追加データが含まれます。 -
Event– 関数を非同期的に呼び出します。複数回失敗するイベントを、関数のデッドレターキューに送信します (設定されている場合)。API レスポンスには、ステータスコードのみが含まれます。 -
DryRun– パラメータ値を検証し、ユーザーまたはロールが、関数を呼び出す許可を持っていることを確認します。
有効な値:
Event | RequestResponse | DryRun -
- LogType
-
Tailに設定し、実行ログをレスポンスに含めます。同期的に呼び出された関数にのみ適用されます。有効な値:
None | Tail - Qualifier
-
バージョンまたはエイリアスを指定して、関数の公開されたバージョンを呼び出します。
長さの制限: 最小長は 1 です。最大長は 128 です。
Pattern:
(|[a-zA-Z0-9$_-]+)
リクエストボディ
リクエストは以下のバイナリデータを受け入れます。
- Payload
-
入力として Lambda 関数に提供される JSON。
JSON を直接入力できます。例えば、
--payload '{ "key": "value" }'です。ファイルパスを指定することもできます。例えば、--payload file://payload.jsonです。
レスポンスの構文
HTTP/1.1 StatusCode
X-Amz-Function-Error: FunctionError
X-Amz-Log-Result: LogResult
X-Amz-Executed-Version: ExecutedVersion
Payloadレスポンス要素
アクションが成功すると、以下の HTTP レスポンスが返されます。
- StatusCode
-
HTTP ステータスコードは、成功したリクエストの 200 の範囲内にあります。
RequestResponse呼び出しタイプの場合、ステータスコードは 200 です。Event呼び出しタイプの場合、ステータスコードは 202 です。DryRun呼び出しタイプの場合、ステータスコードは 204 です。
レスポンスでは、以下の HTTP ヘッダーが返されます。
- ExecutedVersion
-
実行された関数のバージョン。エイリアスを使用して関数を呼び出すと、エイリアスが解決したバージョンが示されます。
長さの制限: 最小長は 1 です。最大長は 1,024 です。
パターン:
(\$LATEST|[0-9]+) - FunctionError
-
エラーが存在する場合、関数の実行中にエラーが発生したことを示します。エラーの詳細は、レスポンスペイロードに含まれています。
- LogResult
-
base64 でエンコードされた、実行ログの最後の 4 KB です。
レスポンスは、HTTP 本文として以下を返します。
- Payload
-
関数からのレスポンス、またはエラーオブジェクト。
エラー
すべてのアクションに共通のエラーについては、「共通エラー」を参照してください。
- EC2AccessDeniedException
-
VPC 設定を構成するには、追加のアクセス許可が必要です。
HTTP ステータスコード: 502
- EC2ThrottledException
-
Amazon EC2 が、Lambda 関数用に提供された実行ロールを使用した関数の初期化中に AWS Lambda をスロットルしました。
HTTP ステータスコード: 502
- EC2UnexpectedException
-
AWS Lambda が、Lambda 関数のセットアップ中に想定外の Amazon EC2 クライアント例外を受け取りました。
HTTP ステータスコード: 502
- EFSIOException
-
接続されているファイルシステムの読み込みまたは書き込み中にエラーが発生しました。
HTTP ステータスコード: 410
- EFSMountConnectivityException
-
Lambda 関数が、設定されたファイルシステムに対するネットワーク接続を確立できませんでした。
HTTP ステータスコード: 408
- EFSMountFailureException
-
許可または設定の問題が原因で、Lambda 関数は設定されたファイルシステムをマウントできませんでした。
HTTP ステータスコード: 403
- EFSMountTimeoutException
-
Lambda 関数は、設定されたファイルシステムに対するネットワーク接続を確立しましたが、マウント操作がタイムアウトしました。
HTTP ステータスコード: 408
- ENILimitReachedException
-
ネットワークインターフェイスの制限に達したため、AWS Lambda は Lambda 関数設定の一部として指定された VPC で Elastic Network Interface を作成できませんでした。詳細については、「Lambda クォータ」を参照してください。
HTTP ステータスコード: 502
- InvalidParameterValueException
-
リクエストに含まれているパラメータの 1 つが無効です。
HTTP ステータスコード：400
- InvalidRequestContentException
-
リクエストボディを JSON として解析できませんでした。
HTTP ステータスコード：400
- InvalidRuntimeException
-
指定されたランタイムまたはランタイムバージョンは、サポートされていません。
HTTP ステータスコード: 502
- InvalidSecurityGroupIDException
-
Lambda 関数の VPC 設定で指定されているセキュリティグループ ID が無効です。
HTTP ステータスコード: 502
- InvalidSubnetIDException
-
Lambda 関数の VPC 設定で指定されているサブネット ID が無効です。
HTTP ステータスコード: 502
- InvalidZipFileException
-
AWS Lambda がデプロイパッケージを解凍できませんでした。
HTTP ステータスコード: 502
- KMSAccessDeniedException
-
AWS KMS アクセスが拒否されたため、Lambda は環境変数を復号化できませんでした。Lambda 関数の KMS アクセス許可をチェックしてください。
HTTP ステータスコード: 502
- KMSDisabledException
-
使用した AWS KMS keyが無効化されているため、Lambda は環境変数を復号化できませんでした。Lambda 関数の KMS キー設定をチェックしてください。
HTTP ステータスコード: 502
- KMSInvalidStateException
-
使用した AWS KMS keyの状態が複合化に有効なものではないため、Lambda は環境変数を復号化できませんでした。関数の KMS キー設定をチェックしてください。
HTTP ステータスコード: 502
- KMSNotFoundException
-
AWS KMS keyが見つからなかったため、Lambda は環境変数を復号化できませんでした。関数の KMS キー設定をチェックしてください。
HTTP ステータスコード: 502
- RecursiveInvocationException
-
他の AWS リソースと再帰的なループで関数が呼び出されていることを Lambda が検出したため、関数の呼び出しを停止しました。
HTTP ステータスコード：400
- RequestTooLargeException
-
リクエストペイロードが
Invokeリクエストボディの JSON 入力クォータを超過しました。詳細については、「Lambda クォータ」を参照してください。HTTP ステータスコード: 413
- ResourceConflictException
-
リソースが既に存在しているか、別のオペレーションが進行中です。
HTTP ステータスコード: 409
- ResourceNotFoundException
-
リクエストで指定されたリソースは存在しません。
HTTP ステータスコード: 404
- ResourceNotReadyException
-
関数が非アクティブなため、その VPC 接続を使用できません。VPC 接続が再度確立されるのを待ち、再試行してください。
HTTP ステータスコード: 502
- ServiceException
-
AWS Lambda サービスで内部エラーが発生しました。
HTTP ステータスコード: 500
- SnapStartException
-
afterRestore()ランタイムフックでエラーが発生しました。詳細については、Amazon CloudWatch Logs をチェックしてください。HTTP ステータスコード：400
- SnapStartNotReadyException
-
Lambda が関数を初期化しています。関数は、関数の状態が
Activeになったときに呼び出すことができます。HTTP ステータスコード: 409
- SnapStartTimeoutException
-
Lambda は、タイムアウト制限内にスナップショットを復元できませんでした。
HTTP ステータスコード: 408
- SubnetIPAddressLimitReachedException
-
1 つ、または複数の設定されたサブネットに利用可能な IP アドレスがないことから、AWS Lambda は Lambda 関数の VPC アクセスを設定できませんでした。
HTTP ステータスコード: 502
- TooManyRequestsException
-
リクエストスループット制限を超えました。詳細については、「Lambda クォータ」を参照してください。
HTTP ステータスコード: 429
- UnsupportedMediaTypeException
-
Invokeリクエストボディのコンテンツタイプが JSON ではありません。HTTP ステータスコード: 415
以下の資料も参照してください。
言語固有の AWS SDK のいずれかでこの API を使用する方法の詳細については、以下を参照してください。
