RDS for PostgreSQL DB インスタンスから AWS Lambda 関数を呼び出す - Amazon Relational Database Service

RDS for PostgreSQL DB インスタンスから AWS Lambda 関数を呼び出す

RDS for PostgreSQL DB インスタンスから AWS Lambda 関数を呼び出すことができます。これを行うには、 RDS for PostgreSQL で提供される aws_lambda PostgreSQL 拡張機能を使用します。

AWS Lambdaは、コードの実行に使用できるコンピューティングサービスです。例えば、DB インスタンスのイベント通知を処理するときに Lambda を使用することができます。Lambda の詳細については、AWS Lambda デベロッパーガイドの「AWS Lambda とは」を参照してください。

注記

次の RDS for PostgreSQL バージョンでは、AWS Lambda 関数の呼び出しがサポートされています。

  • 12.6 以降のマイナーバージョン

  • 13.2 以降のマイナーバージョン

Lambda 関数の使用の概要

次の手順を使用して、 RDS for PostgreSQL データベースから Lambda 関数を呼び出すことができます。

RDS for PostgreSQL データベースから Lambda 関数を呼び出すには

  1. 必要な PostgreSQL 拡張機能をインストールします。例えば、aws_lambda および aws_commons などがあります。これを行うには psql を起動し、以下のコマンドを実行します。

    CREATE EXTENSION IF NOT EXISTS aws_lambda CASCADE;

    aws_lambda 拡張機能には、Lambda にある関数の呼び出しに使用する aws_lambda.invoke 関数が含まれます。aws_commons 拡張機能は、追加のヘルパー関数を提供するために含まれています。

  2. 使用する Lambda 関数の名前か Amazon リソースネーム (ARN) を見つけます。このプロセスの詳細については、「使用する Lambda 関数の指定」を参照してください。

  3. Lambda 関数へのアクセス許可を提供します。

    Lambda 関数を呼び出すには、の RDS for PostgreSQL DB インスタンスに Lambda API 呼び出しオペレーションにアクセスするアクセス許可を与えます。これには、次の手順が含まれます。

    1. 呼びだす Lambda 関数へのアクセスを提供する AWS Identity and Access Management (IAM) ポリシーを作成します。

    2. IAM ロールを作成します。

    3. 作成した IAM ポリシーを、作成したロールにアタッチします。

    4. この IAM ロールを DB インスタンスに追加します。

    このプロセスの詳細については、「Lambda へのアクセスを RDS に許可する」を参照してください。

  4. aws_lambda.invoke 関数を使用して Lambda 関数を実行します。このプロセスの詳細については、「Lambda 関数を呼び出す」を参照してください。

使用する Lambda 関数の指定

使用する Lambda 関数を見つけるときは、次の情報を指定します。

  • 関数名–Lambda関数、ARN、バージョンまたはエイリアスの名前。可能な形式のリストについては、Lambda関数名の形式を参照してください。

  • AWS リージョン – (オプション) Lambda 関数がある AWS リージョン。リージョンの値を指定せず、関数の ARN で値が指定されていない場合、 RDSDB インスタンスと同じ リージョンを使用します。

    AWS リージョン名と関連する値のリストについては、「リージョン、アベイラビリティーゾーン、および Local Zones」を参照してください。

Lambda 関数名の情報を保持するときは、aws_commons.create_lambda_function_arn 関数を使用します。この関数は、次に示すとおり、名前情報を保存する aws_commons._lambda_function_arn_1 複合構造を作成します。

psql=> SELECT aws_commons.create_lambda_function_arn( 'my-function', 'us-west-2' ) AS aws_lambda_arn_1 \gset psql=> SELECT aws_commons.create_lambda_function_arn( '123456789012:function:my-function', 'us-west-2' ) AS lambda_partial_arn_1 \gset psql=> SELECT aws_commons.create_lambda_function_arn( 'arn:aws:lambda:us-west-2:123456789012:function:my-function' ) AS lambda_arn_1 \gset

これらの値は、後で、aws_lambda.invoke 関数を呼び出す際にパラメータとして指定できます。例については、「Lambda 関数を呼び出す」を参照してください。

Lambda へのアクセスを RDS に許可する

Lambda 関数を使用するには、PostgreSQL の DB インスタンスに Lambda へのアクセス許可を付与します。これには、以下の手順を使用します。

PostgreSQL の DB インスタンスに Lambda へのアクセスを付与する

  1. IAM ポリシーを作成します。

    このポリシーは、PostgreSQL DB インスタンスに Lambda 関数の呼び出しを許可するアクセス許可を付与します。

    このポリシーの作成の一環として、次の手順を実行します。

    1. lambda:InvokeFunction が Lambda に RDS for PostgreSQL DB インスタンスからの呼び出しを許可できるよう、必要なアクションをポリシーに加えます。

    2. Lambda 関数を識別する Amazon リソースネーム (ARN) を加えます。Lambda アクセス用の ARN 形式は arn:aws:lambda:::function:example_function/* です。

    RDS for PostgreSQL のための IAM ポリシーの作成詳細については、「IAM データベースアクセス用の IAM ポリシーの作成と使用」を参照してください。IAM ユーザーガイド の「IAM チュートリアル: はじめてのカスタマー管理ポリシーの作成とアタッチ」も参照してください。

    以下の AWS CLI コマンドでは、これらのオプションを指定して、rds-lambda-policy という名前の IAM ポリシーを作成します。このポリシーは、example_function という名前の関数へのアクセス権を付与します。

    aws iam create-policy --policy-name rds-lambda-policy --policy-document '{ "Version": "2012-10-17", "Statement": [ { "Sid": "AllowAccessToExampleFunction", "Effect": "Allow", "Action": "lambda:InvokeFunction", "Resource": "arn:aws:lambda:<region>:<123456789012>:function:example_function" } ] }'

    ポリシーを作成したら、ポリシーの ARN を書き留めます。ポリシーを IAM ロールにアタッチする場合、後続のステップで ARN が必要です。

  2. IAM ロールを作成します。

    これにより RDS for PostgreSQL は、ユーザーに代わって Lambda 関数にアクセスするための IAM ロールを、引き受けることができます。詳細については、IAM ユーザーガイド の「IAMユーザーにアクセス許可を委任するロールの作成」を参照してください。

    以下の例は、AWS CLI コマンドを使用して、rds-lambda-role という名前のロールを作成する例を示しています。

    aws iam create-role --role-name rds-lambda-role --assume-role-policy-document '{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "rds.amazonaws.com" }, "Action": "sts:AssumeRole" } ] }'
  3. 作成した IAM ポリシーを、作成した IAM ロールにアタッチします。

    次の AWS CLI コマンドでは、先ほど作成したポリシーを rds-lambda-role という名前のロールにアタッチします。your-policy-arn は、以前のステップで書き留めたポリシー ARN に置き換えます。

    aws iam attach-role-policy --policy-arn your-policy-arn --role-name rds-lambda-role
  4. DB インスタンスに IAM ロールを追加します。これを行うには、以下で説明するとおり AWS CLI を使用します。

    次の CLI コマンドを使用して、my-db-instance という名前の PostgreSQL DB インスタンス用の RDS に IAM ロールを追加します。your-role-arn を、以前のステップで書き留めたロール ARN に置き換えます。次に示すとおり、Lambda オプションの値には --feature-name を使用します。

    aws rds add-role-to-db-instance \ --db-instance-identifier my-db-instance \ --feature-name Lambda \ --role-arn your-role-arn \ --region your-region

Lambda 関数を呼び出す

次に、aws_lambda.invoke 関数の呼び出し方の例をいくつか見ていきます。aws_lambda.invoke 関数を使用する前に、以下の前提条件を満たしていることを確認してください。

Lambda 関数は、同期的または非同期的に呼び出すことが可能です。これは、aws_lambda.invoke 関数の invocation_type パラメータに対して次の値を使用することで、制御します。

  • Lambda 関数の RequestResponse の呼び出しタイプは同期で、aws_lambda.invoke 関数の結果にレスポンスペイロードを返します。ワークフローが Lambda 関数の結果をすぐに受け取ることに依存しているときは、RequestResponse 呼び出しのタイプを使用します。以下の例のほとんどは、同期呼び出しを使用しています。

    RequestResponse の呼び出しタイプがデフォルトです。

  • Lambda 関数の Event の呼び出しタイプは非同期で、返されたペイロードなしにすぐに返されます。ワークフローを先に進める前に Event 関数の結果を知る必要がないときは、Lambda の呼び出しタイプを使用します。非同期呼び出しの例については、「Lambda 関数の非同期イベント呼び出し」を参照してください。

次の aws_lambda.invoke 例では aws_lambda_arn_1 構造を使用しています。これには、Lambda 関数の識別情報が含まれています。この構造を作成するには aws_commons.create_lambda_function_arn 関数を使用します。aws_commons.create_lambda_function_arn 関数の使用例については、「使用する Lambda 関数の指定」を参照してください。

Lambda 関数の同期的な RequestResponse 呼び出し

以下は、Lambda 関数の同期呼び出しの例です。次の 2 つの aws_lambda.invoke 関数呼び出しの結果は、同じです。

psql=> SELECT * FROM aws_lambda.invoke(:'aws_lambda_arn_1', '{"body": "Hello from Postgres!"}'::json); psql=> SELECT * FROM aws_lambda.invoke(:'aws_lambda_arn_1', '{"body": "Hello from Postgres!"}'::json, 'RequestResponse');

パラメータの説明は次のとおりです。

  • :'aws_lambda_arn_1' – このパラメータは、呼び出す Lambda 関数を識別する構造です。この例では、変数を使用して、前に作成した構造を指定します。代わりに、以下のように aws_commons.create_lambda_function_arn 関数呼び出し内にインラインで aws_lambda.invoke 関数呼び出しを含めることで、同じ構造を作成できます。

    psql=> SELECT * FROM aws_lambda.invoke(aws_commons.create_lambda_function_arn('my-function', 'us-west-2'), '{"body": "Hello from Postgres!"}'::json );
  • '{"body": "Hello from PostgreSQL!"}'::json – Lambda関数に渡す JSON ペイロード。

  • 'RequestResponse'–Lambda 呼び出しタイプ。

Lambda 関数の非同期イベント呼び出し

以下は、Lambda 関数の非同期呼び出しの例です。Event 呼び出しタイプは、指定された入力ペイロードを使用して Lambda 関数の呼び出しをスケジュールし、すぐに返します。Lambda 関数の結果に依存しない特定のワークフローでは、Event 呼び出しタイプを使用します。

psql=> SELECT * FROM aws_lambda.invoke(:'aws_lambda_arn_1', '{"body": "Hello from Postgres!"}'::json, 'Event');

関数レスポンスで Lambda 実行ログを要求する

次に示すとおり、実行ログの最後の 4 KB を関数レスポンスに含めるよう要求することができます。

psql=> SELECT *, select convert_from(decode(log_result, 'base64'), 'utf-8') as log FROM aws_lambda.invoke(:'aws_lambda_arn_1', '{"body": "Hello from Postgres!"}'::json, 'RequestResponse', 'Tail');

aws_lambda.invoke 関数の log_type パラメータを Tail に設定して、実行ログをレスポンスに含めます。この log_type パラメータのデフォルト値は None です。

返された log_result は、base64 エンコードされた文字列です。このコンテンツは、decodeconvert_from PostgreSQL 関数の組み合わせを使用してデコードできます。

Lambda 関数にクライアントコンテキストを含める

ペイロードとは別のクライアントコンテキスト情報は、次のように渡すことができます。

psql=> SELECT *, convert_from(decode(log_result, 'base64'), 'utf-8') as log FROM aws_lambda.invoke(:'aws_lambda_arn_1', '{"body": "Hello from Postgres!"}'::json, 'RequestResponse', 'Tail');

クライアントコンテキストを含めるときは、aws_lambda.invoke 関数の context パラメータに JSON オブジェクトを使用します。

Lambda 関数の特定のバージョンへのアクセスを拒否する

Lambda 関数の特定のバージョンを呼び出す例については、以下を参照してください。

psql=> SELECT * FROM aws_lambda.invoke(:'aws_lambda_arn_1', '{"body": "Hello from Postgres!"}'::json, 'RequestResponse', 'None', NULL, 'custom_version');

Lambda 関数のバージョンを識別するには、aws_lambda.invoke 関数の qualifier パラメータを使用します。この例では、'custom_version' は、呼び出す関数のバージョンを識別するエイリアスかバージョンです。

代わりに、次のように Lambda 関数名情報を使って関数の修飾子を指定することもできます。

psql=> SELECT * FROM aws_lambda.invoke(aws_commons.create_lambda_function_arn('my-function:custom_version', 'us-west-2'), '{"body": "Hello from Postgres!"}'::json );

Lambda 関数エラーの処理

リクエストの処理中に Lambda 関数が例外をスローした場合、aws_lambda.invoke は、次のように PostgreSQL エラーで失敗します。

psql=> SELECT * FROM aws_lambda.invoke(:'aws_lambda_arn_1', '{"body": "Hello from Postgres!"}'::json); ERROR: lambda invocation failed DETAIL: "arn:aws:lambda:us-west-2:123456789012:function:my-function" returned error "Unhandled", details: "<Error details string>".

関数リファレンス

以下は、RDS for PostgreSQL のための RDS で Lambda 関数を呼び出すために使用する関数のリファレンスです。

aws_lambda.invoke

RDS for PostgreSQL DB インスタンスの Lambda 関数を実行します。

Lambda関数の呼び出しの詳細については、AWS Lambda デベロッパーガイドの「呼び出し」も参照してください。

構文

JSON
aws_lambda.invoke( IN function_name TEXT, IN payload JSON, IN region TEXT DEFAULT NULL, IN invocation_type TEXT DEFAULT 'RequestResponse', IN log_type TEXT DEFAULT 'None', IN context JSON DEFAULT NULL, IN qualifier VARCHAR(128) DEFAULT NULL, OUT status_code INT, OUT payload JSON, OUT executed_version TEXT, OUT log_result TEXT)
aws_lambda.invoke( IN function_name aws_commons._lambda_function_arn_1, IN payload JSON, IN invocation_type TEXT DEFAULT 'RequestResponse', IN log_type TEXT DEFAULT 'None', IN context JSON DEFAULT NULL, IN qualifier VARCHAR(128) DEFAULT NULL, OUT status_code INT, OUT payload JSON, OUT executed_version TEXT, OUT log_result TEXT)
JSONB
aws_lambda.invoke( IN function_name TEXT, IN payload JSONB, IN region TEXT DEFAULT NULL, IN invocation_type TEXT DEFAULT 'RequestResponse', IN log_type TEXT DEFAULT 'None', IN context JSONB DEFAULT NULL, IN qualifier VARCHAR(128) DEFAULT NULL, OUT status_code INT, OUT payload JSONB, OUT executed_version TEXT, OUT log_result TEXT)
aws_lambda.invoke( IN function_name aws_commons._lambda_function_arn_1, IN payload JSONB, IN invocation_type TEXT DEFAULT 'RequestResponse', IN log_type TEXT DEFAULT 'None', IN context JSONB DEFAULT NULL, IN qualifier VARCHAR(128) DEFAULT NULL, OUT status_code INT, OUT payload JSONB, OUT executed_version TEXT, OUT log_result TEXT )

入力パラメータ

function_name

Lambda 関数の識別名。値には、関数名、ARN、または部分的な ARN を指定できます。可能な形式のリストについては、AWS Lambda デベロッパーガイドの「Lambda関数名の形式」を参照してください。

payload

Lambda 関数の入力。形式には、JSON または JSONB を使用できます。詳細については、PostgreSQL ドキュメントの「JSON タイプ」を参照してください。

リージョン

(オプション) 関数の Lambda リージョン。デフォルトでは、RDSfunction_name の完全な ARN から AWS リージョンを解決するか、RDS for PostgreSQL DB インスタンスリージョンを使用します。このリージョン値が function_name ARN で指定されたものと競合する場合、エラーが発生します。

invocation_type

Lambda 関数の呼び出しタイプ。 値は大文字と小文字が区別されます。以下に示しているのは、可能な値です。

  • RequestResponse–デフォルト。Lambda 関数の呼び出しタイプは同期で、結果にレスポンスペイロードを返します。ワークフローが Lambda 関数の結果をすぐに受け取ることに依存しているときは、RequestResponse 呼び出しのタイプを使用します。

  • Event– Lambda 関数の呼び出しタイプは非同期で、返されたぺイロードなしにすぐに返されます。ワークフローを先に進める前に Lambda 関数の結果を知る必要がないときは、Event の呼び出しタイプを使用します。

  • DryRun– この呼び出しタイプは、Lambda 関数を実行することなくアクセスをテストします。

log_type

log_result出力パラメータで返される Lambda ログのタイプ。 値は大文字と小文字が区別されます。以下に示しているのは、可能な値です。

  • Tail – 返された log_result 出力パラメータには、実行ログの最後の 4 KB が含まれます。

  • None – Lambda のないログ情報は返されません。

context

JSON または JSONB形式のクライアントコンテキスト。使用されるフィールドには customenv が含まれます 。

修飾子

呼び出される Lambda 関数のバージョンを識別する修飾子。この値が function_name ARN で指定されたものと競合する場合、エラーが発生します。

出力パラメータ

status_code

HTTP ステータスレスポンスコード。詳細については、AWS Lambda デベロッパーガイドの「Lambda 応答要素の呼び出し」を参照してください。

payload

実行された Lambda 関数から返された情報。形式は JSON または JSONB です。

executedversion

実行された Lambda 関数のバージョン。

result

Lambda 関数が呼び出されたとき log_type 値が Tail である場合に返される実行ログ情報。結果には、Base64 でエンコードされた実行ログの最後の 4 KB が含まれます。

aws_commons.create_lambda_function_arn

Lambda 関数名情報を保持するように、aws_commons._lambda_function_arn_1 構造を作成します。aws_commons.create_lambda_function_arn 関数の結果は、aws_lambda.invoke function_name 関数の aws_lambda.invoke パラメータで使用します。

構文

aws_commons.create_lambda_function_arn( function_name TEXT, region TEXT DEFAULT NULL ) RETURNS aws_commons._lambda_function_arn_1

入力パラメータ

function_name

Lambda 関数名を含む必須のテキスト文字列。値には、関数名、部分的な ARN、または完全な ARN を指定します。

リージョン

Lambda 関数がある AWS リージョンを含む、オプションのテキスト文字列。 リージョン名と関連する値のリストについては、「」を参照してください。リージョン、アベイラビリティーゾーン、および Local Zones