Lambda UDF の登録 Lambda UDF のセキュリティおよび権限の管理 Lambda UDF の認可パラメータの設定 Amazon Redshift と Lambda 間の JSON インターフェイスの使用

スカラー Lambda UDF の作成

Amazon Redshift は、AWS Lambda で定義されたカスタム関数を SQL クエリの一部として使用することができます。スカラー Lambda UDF は、Java、Go、PowerShell、Node.js、C#、Python、Ruby など、Lambda でサポートされている任意のプログラミング言語で記述できます。または、カスタムランタイムを使用できます。

Lambda UDF は Lambda で定義および管理され、Amazon Redshift でこれらの UDF を呼び出すアクセス権限を制御できます。同じクエリ内で複数の Lambda 関数を呼び出すことも、同じ関数を複数回呼び出すこともできます。

スカラー関数がサポートされている SQL ステートメントの句で Lambda UDF を使用します。また、SELECT、UPDATE、INSERT、DELETE などの SQL ステートメントで Lambda UDF を使用することもできます。

注記

Lambda UDF を使用すると、Lambda サービスから追加料金が発生する可能性があります。そうするかどうかは、Lambda リクエスト数 (UDF 呼び出し) や Lambda プログラム実行の合計時間などの要因によって異なります。ただし、Amazon Redshift で Lambda UDF を使用するための追加料金はありません。AWS Lambda の料金の詳細については、AWS Lambda の料金を参照してください。

Lambda リクエストの数は、Lambda UDF が使用される特定の SQL ステートメント句によって異なります。例えば、この関数が次ののような WHERE 句で使用されているとします。

SELECT a, b FROM t1 WHERE lambda_multiply(a, b) = 64; SELECT a, b FROM t1 WHERE a*b = lambda_multiply(2, 32)

この場合、Amazon Redshift はそれぞれの最初の SELECT ステートメントを呼び出し、2 番目の SELECT ステートメントを 1 回だけ呼び出します。

ただし、クエリの投影部分で UDF を使用すると、結果セット内の修飾された行または集約された行ごとに Lambda 関数を 1 回だけ呼び出す可能性があります。

Lambda UDF の登録

CREATE EXTERNAL FUNCTION コマンドでは、次のパラメータが作成されます。

(オプション) データ型を持つ引数のリスト。
1 つの戻りデータ型。
Amazon Redshift によって呼び出される外部関数の 1 つの関数名。
Amazon Redshift クラスターが Lambda を引き受けて呼び出すことが許可されている 1 つの IAM ロール。
Lambda UDF によって呼び出される 1 つのLambda 関数名。

CREATE EXTERNAL FUNCTION の詳細については、「CREATE EXTERNAL FUNCTION」を参照してください。

この関数の入力および戻りデータタイプは、どの標準 Amazon Redshift データタイプでも可能です。

Amazon Redshift は、外部関数がバッチ処理された引数と結果を送受信できるようにします。

Lambda UDF のセキュリティおよび権限の管理

Lambda UDF を作成するには、LANUGAGE EXFUNC の使用許可があることを確認してください。特定のユーザー、グループ、またはパブリックに対して、USAGE ON LANGUAGE EXFUNC を明示的に付与するか、USAGE ON LANGUAGE EXFUNC を取り消す必要があります。

次の例では、EXFUNC での使用を PUBLIC に付与します。


grant usage on language exfunc to PUBLIC;

次の例では、最初に PUBLIC に対して exfunc の使用を取り消し、次にユーザーグループ lambda_udf_devs に使用を許可します。


revoke usage on language exfunc from PUBLIC;
grant usage on language exfunc to group lambda_udf_devs;

Lambda UDF を実行するには、呼び出される各関数に対するアクセス許可があることを確認してください。デフォルトでは、新しい Lambda UDF を実行する許可が PUBLIC に付与されます。使用を制限するには、関数に対して PUBLIC からこの許可を取り消します。次に、特定のユーザーまたはグループに権限を付与します。

次の例では、PUBLIC から関数 exfunc_sum での実行を取り消します。次に、ユーザーグループ lambda_udf_devs に使用を許可します。


revoke execute on function exfunc_sum(int, int) from PUBLIC;
grant execute on function exfunc_sum(int, int) to group lambda_udf_devs;

スーパーユーザーは、デフォルトですべての権限を持っています。

権限の付与と取り消しの詳細については、「GRANT」および「REVOKE」を参照してください。

Lambda UDF の認可パラメータの設定

CREATE EXTERNAL FUNCTION コマンドには、AWS Lambda で Lambda 関数を呼び出すための認証が必要です。認可を行うには、CREATE EXTERNAL FUNCTION コマンドの実行時に、AWS Identity and Access Management (IAM) ロールを指定します。IAM ロールの詳細については、IAM ユーザーガイドの IAM ロールをご参照ください。

クラスターにアタッチされている Lambda 関数を呼び出す許可を持つ IAM ロールがある場合、コマンドの IAM_ROLE パラメータにロールの Amazon リソースネーム (ARN) を置き換えることができます。以下のセクションでは、CREATE EXTERNAL FUNCTION コマンドで IAM ロールを使用するステップについて説明します。

Lambda 用に IAM ロールを作成する

IAM ロールには、Lambda 関数を呼び出すための許可が必要です。IAM ロールの作成時に、次のいずれかの方法でアクセス許可を提供します。

IAM ロールの作成中に、[Attach permissions policy (アクセス許可ポリシーのアタッチ)] ページで AWSLambdaRole ポリシーをアタッチします。AWSLambdaRole ポリシーは、最小要件である Lambda 関数を呼び出すためのアクセス許可を付与します。詳細およびその他のポリシーについては、AWS Lambda デベロッパーガイドの AWS Lambda のアイデンティティベースの IAM ポリシーを参照してください。
すべてのリソースの lambda:InvokeFunction 許可、またはその関数の ARN を持つ特定の Lambda 関数を使用して、IAM ロールにアタッチする独自のカスタムポリシーを作成します。ポリシー作成方法の詳細については、「IAM ユーザーガイド」の「IAM ポリシーの作成」を参照してください。

次のポリシー例では、特定の Lambda 関数で Lambda を呼び出すことができます。
```
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "Invoke",
            "Effect": "Allow",
            "Action": [
                "lambda:InvokeFunction"
            ],
            "Resource": "arn:aws:lambda:us-west-2:123456789012:function:my-function"
        }
    ]
}
```
Lambda 関数のリソースの詳細については、「IAM API リファレンス」の「Lambda アクションのリソースと条件」を参照してください。

必要なアクセス許可を使用してカスタムポリシーを作成した後、IAM ロールの作成中に、[Attach permissions policy (アクセス許可ポリシーのアタッチ)] ページでポリシーを IAM ロールにアタッチできます。

IAM ロールを作成する手順については、「Amazon Redshift 管理ガイド」の「ユーザーに代わって Amazon Redshift が他の AWS サービスにアクセスすることを許可する」を参照してください。

新しい IAM ロールを作成しない場合は、前述したアクセス許可を既存の IAM ロールに追加できます。

クラスターを使用して IAM ロールを関連付ける

IAM ロールをクラスターにアタッチします。クラスターにロールを追加するか、Amazon Redshift マネジメントコンソール、CLI、または API を使用してクラスターに関連付けられるロールを表示できます。詳細については、「Amazon Redshift 管理ガイド」の「IAM ロールをクラスターと関連付ける」を参照してください。

コマンドに IAM ロールを含める

CREATE EXTERNAL FUNCTION コマンドに IAM ロール ARN を含めます。IAM ロールを作成する場合、IAM はロールの Amazon リソースネーム (ARN) を返します。IAM ロールを指定するには、IAM_ROLE パラメータでロールの ARN を指定します。以下に、IAM_ROLE パラメータの構文を示します。


IAM_ROLE 'arn:aws:iam::aws-account-id:role/role-name'

同じリージョン内の他のアカウントに存在する Lambda 関数を呼び出すには、Amazon Redshift での IAM ロールの連鎖を参照してください。

Amazon Redshift と AWS Lambda 間で JSON インターフェイスを使用する

Amazon Redshift は、Amazon Redshift が通信するすべての Lambda 関数に共通のインターフェイスを使用します。

次のテーブルに、JSON ペイロードで期待できる指定済みの Lambda 関数の入力フィールド一覧を示しています。

フィールド名	説明	値の範囲
request_id	各呼び出しリクエストを一意に識別する汎用一意識別子 (UUID)。	有効な UUID。
クラスター	クラスターのフル Amazon リソースネーム（ARN）。	有効なクラスター ARN。
ユーザー	コールを発信するユーザーの名前。	有効なユーザー名
データベース	クエリが実行されているデータベースの名前。	有効なデータベース名。
external_function	呼び出しを行う外部関数の完全修飾名。	有効な完全修飾関数名。
query_id	呼び出しを行うクエリのクエリ ID。	有効なクエリ ID。
num_records	ペイロードでの引数の数。	1～2^64 の値。
引数	指定した形式のデータペイロード。	配列形式のデータは JSON 配列である必要があります。各要素は、引数の数が 1 より大きい場合、配列であるレコードです。配列を使用することで、Amazon Redshift はペイロード内でのレコードの順序を保持します。

JSON 配列の順序によって、バッチ処理の順序が決まります。Lambda 関数では、引数を繰り返し取得して、正確な数のレコードを生成する必要があります。ペイロードの例を次に示します。


{
  "request_id" : "23FF1F97-F28A-44AA-AB67-266ED976BF40",
  "cluster" : 'arn:aws:redshift:xxxx',
  "user" : "adminuser",
  "database" : "db1",
  "external_function": "public.foo",
  "query_id" : 5678234,
  "num_records" : 4,
  "arguments" : [
     [ 1, 2 ],
     [ 3, null],
     null,
     [ 4, 6]
   ]
 }

Lambda 関数の戻り出力には、次のフィールドが含まれます。

フィールド名	説明	値の範囲
success	関数の成功または失敗表示。	`"true"` または `"false"` 値。
error_msg	成功値が `"false"` の場合 (関数が失敗した場合) のエラーメッセージです。それ以外の場合、このフィールドは無視されます。	有効なメッセージ。
num_records	ペイロードのレコード数。	1～2^64 の値。
結果	指定された形式の呼び出し結果。	該当なし

Lambda 関数出力の例を次に示します。


{
  "success": true,   // true indicates the call succeeded
  "error_msg" : "my function isn't working",  // shall only exist when success != true
  "num_records": 4,      // number of records in this payload
  "results" : [
     1,
     4,
     null,
     7
   ]
}

SQL クエリから Lambda 関数を呼び出す場合、Amazon Redshift は次の点を考慮して、接続のセキュリティを確保します。

GRANT および REVOKE 権限。UDF セキュリティと権限の詳細については、「UDF のセキュリティおよび権限」を参照してください。
Amazon Redshift は、指定された Lambda 関数に最低限のデータセットのみを送信します。
Amazon Redshift は、指定された IAM ロールを持つ指定済みの Lambda 関数のみを呼び出します。

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

エラーおよび警告のログ記録

UDF の使用例