从 Aurora PostgreSQL 数据库集群 中调用 Amazon Lambda 函数 - Amazon Aurora
使用 Lambda 函数的概述指定要使用的 Lambda 函数授予 Aurora 访问 Lambda 权限调用 Lambda 函数函数参考
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅中国的 Amazon Web Services 服务入门。

从 Aurora PostgreSQL 数据库集群 中调用 Amazon Lambda 函数

您可以从 Aurora PostgreSQL 数据库集群 中调用 Amazon Lambda 函数。为此，请使用通过 Aurora PostgreSQL 提供的 aws_lambda PostgreSQL 扩展。

Amazon Lambda 是可用来运行代码的计算服务。例如，您可以使用 Lambda 函数处理来自数据库实例的事件通知。有关 Lambda 的更多信息，请参阅 Amazon Lambda Developer Guide 中的 什么是 Amazon Lambda？

注意

Aurora PostgreSQL 11.9 及更高版本支持调用 Amazon Lambda 函数。

使用 Lambda 函数的概述

您可以使用以下程序从 Aurora PostgreSQL 数据库中调用 Lambda 函数。

从 Aurora 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 函数，请向 Aurora PostgreSQL 数据库集群 授予访问 Lambda 调用 API 操作的权限。此操作包括以下步骤：

    1. 创建一个 Amazon Identity and Access Management (IAM) 策略，该策略提供对要调用的 Lambda 函数的访问权限。

    2. 创建一个 IAM 角色。

    3. 将您创建的 IAM 策略附加到您创建的角色。

    4. 将此 IAM 角色添加到 数据库集群 。

    有关此过程的详细信息，请参阅 授予 Aurora 访问 Lambda 权限。

  4. 使用 aws_lambda.invoke 函数运行 Lambda 函数。有关此过程的详细信息，请参阅 调用 Lambda 函数。

指定要使用的 Lambda 函数

要标识要使用的 Lambda 函数，请指定以下信息：

  • 函数名称 – Lambda 函数、ARN、版本或别名的名称。有关可能的格式的列表，请参阅 Lambda 函数名称格式。

  • Amazon 区域 –（可选）Lambda 函数所在的 Amazon 区域。如果您未指定区域值并且未在函数 ARN 中指定该值，则 Aurora 将使用与 数据库集群 相同的区域。

    有关 Amazon 区域名称和关联值的列表，请参阅 区域和可用区 。

要保存 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-cn:lambda:us-west-2:123456789012:function:my-function' ) AS lambda_arn_1 \gset

稍后，您可以在调用 aws_lambda.invoke 函数时将这些值中的任何一个作为参数提供。有关示例，请参阅 调用 Lambda 函数。

授予 Aurora 访问 Lambda 权限

要使用 Lambda 函数，请授予 PostgreSQL 数据库集群 访问 Lambda 的权限。为此，请使用以下过程。

授予 PostgreSQL 数据库集群 访问 Lambda 的权限

  1. 创建 IAM 策略。

    此策略提供让您的 PostgreSQL 数据库集群 调用 Lambda 函数的权限。

    在创建此策略的过程中，请执行以下步骤：

    1. 在策略中包括允许从 Aurora PostgreSQL 数据库集群 进行 Lambda 调用所需的操作 lambda:InvokeFunction。

    2. 包括标识 Lambda 函数的 Amazon 资源名称 (ARN)。用于访问 Lambda 的 ARN 格式为：arn:aws-cn:lambda:::function:example_function/*

    有关为 Aurora PostgreSQL 创建 IAM 策略的更多信息，请参阅 创建和使用 IAM 策略进行 IAM 数据库访问。另请参阅 IAM 用户指南 中的 IAM 教程：创建和附加您的第一个客户托管策略 。

    以下 Amazon 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-cn:lambda:<region>:<123456789012>:function:example_function" } ] }'

    创建策略后，请记下策略的 ARN。在将策略附加到 IAM 角色时，您在后面的步骤中需要使用 ARN。

  2. 创建一个 IAM 角色。

    这样，Aurora PostgreSQL 就可以代表您代入 IAM 角色以访问 Lambda 函数。有关更多信息，请参阅 IAM 用户指南 中的 创建向 IAM 用户委派权限的角色 。

    以下示例说明了如何使用 Amazon 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 角色。

    以下 Amazon CLI 命令将之前创建的策略附加到名为 rds-lambda-role 的角色。将 your-policy-arn 替换为您在先前的步骤中记下的策略 ARN。 

    aws iam attach-role-policy --policy-arn your-policy-arn --role-name rds-lambda-role

  4. 将 IAM 角色添加到数据库集群中。您可以使用 Amazon CLI 执行该操作，如下所述。

    使用以下 CLI 命令将 IAM 角色添加到名为 my-db-cluster 的 Aurora PostgreSQL 数据库集群中。将 your-role-arn 替换为您在上一步中记下的角色 ARN。使用 Lambda 作为 --feature-name 选项的值，如下所示。 

    aws rds add-role-to-db-cluster \ --db-cluster-identifier my-db-cluster \ --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 类型的调用是异步的，在没有返回负载的情况下立即返回。如果您不需要在工作流程进行之前了解 Lambda 函数的结果，请使用 Event 类型的调用。有关异步调用的示例，请参阅 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 函数调用的示例。以下两个 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_lambda.invoke 函数调用中包含 aws_commons.create_lambda_function_arn 函数调用来创建结构，如下所示。 

    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 执行日志

您可以请求在函数响应中包含最后 4KB 的执行日志，如下所示。

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 编码的字符串。您可以使用 decode 和 convert_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');

要包含客户端上下文，请将 JSON 对象用于 aws_lambda.invoke 函数的 context 参数。

调用 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-cn:lambda:us-west-2:123456789012:function:my-function" returned error "Unhandled", details: "<Error details string>".

函数参考

以下是通过 Aurora PostgreSQL 调用 Lambda 函数所用函数的参考。

aws_lambda.invoke

为 Aurora PostgreSQL 数据库集群 运行 Lambda 函数。

有关调用 Lambda 函数的更多详细信息，另请参阅中的Amazon Lambda Developer Guide中的调用。

语法

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。有关可能的格式的列表，请参阅Amazon Lambda Developer Guide.中的 Lambda 函数名称格式。

payload

Lambda 函数的输入。格式可以是 JSON 或 JSONB。有关更多信息，请参阅 PostgreSQL 文档中的 JSON 类型。

区域

（可选）函数的 Lambda 区域。默认情况下，Aurora 会从 function_name 中的完整 ARN 中解析 Amazon 区域或使用 Aurora PostgreSQL 数据库实例区域。如果此区域值与 function_name ARN 中提供的值冲突，则会引发错误。

invocation_type

Lambda 函数的调用类型。值区分大小写。可能的值包括：

  • RequestResponse – 默认值。Lambda 函数的这种调用类型是同步的，并在结果中返回响应负载。当工作流程依赖于立即接收 Lambda 函数结果时，请使用 RequestResponse 调用类型。

  • Event – Lambda 函数的这种调用类型是异步的，并在没有返回负载的情况下立即返回。如果您不需要在工作流程开始之前了解 Lambda 函数的结果，请使用 Event 调用类型。

  • DryRun – 这种类型的调用在不允许 Lambda 函数的情况下测试访问权限。

log_type

要在 log_result 输出参数中返回的 Lambda 日志类型。值区分大小写。可能的值包括：

  • Tail – 返回的 log_result 输出参数将包含最后 4KB 的执行日志。

  • None – 未返回 Lambda 日志信息。

context

JSON 或 JSONB 格式的客户端上下文。要使用的字段包括 custom 和 env。

限定符

标识要调用的 Lambda 函数版本的限定符。如果此值与 function_name ARN 中提供的值冲突，则会引发错误。

输出参数

status_code

HTTP 状态响应代码。有关更多信息，请参阅Amazon Lambda Developer Guide中的Lambda调用响应元素。

payload

从运行的 Lambda 函数返回的信息。格式为 JSON 或 JSONB。

executed_version

运行的 Lambda 函数的版本。

log_result

如果 log_type 值在调用 Lambda 函数时为 Tail，则会返回执行日志信息。结果包含以 Base64 编码的最后 4 KB 执行日志。

aws_commons.create_lambda_function_arn

创建一个 aws_commons._lambda_function_arn_1 结构来保存 Lambda 函数名称信息。您可以在 aws_lambda.invoke aws_lambda.invoke 函数的 function_name 参数中使用 aws_commons.create_lambda_function_arn 函数的结果。

语法

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 函数所在的Amazon 区域的可选文本字符串。有关区域名称和关联值的列表，请参阅 区域和可用区 。