创建 API CONNECTION

API CONNECTION 主要用于存储和保护第三方应用服务的身份认证信息。借助 API CONNECTION，云器 Lakehouse 的 EXTERNAL FUNCTION（外部函数）能够以安全的方式通过 API 调用与这些服务进行交互。目前，API CONNECTION 支持的外部服务包括 阿里云函数计算（Function Compute）、腾讯云云函数（Cloud Functions），以及 AWS Lambda。

语法

CREATE API CONNECTION [ IF NOT EXISTS ] <connection_name> TYPE CLOUD_FUNCTION PROVIDER = '<provider>' REGION = '<region>' ROLE_ARN = '<role_arn>' NAMESPACE = '<namespace>' CODE_BUCKET = '<code_bucket>'

参数说明

参数	说明
`connection_name` connection_name	要创建的 API 连接名称。
`PROVIDER` PROVIDER	云函数服务提供商。支持的取值包括： `'tencent'` 'tencent' 、 `'aliyun'` 'aliyun' 和 `'aws'` 'aws' 。
`REGION` REGION	云函数部署所在的区域。示例： • 阿里云： `'cn-shanghai'` 'cn-shanghai' （区域代码参考） • 腾讯云： `'ap-beijing'` 'ap-beijing' （区域代码参考） • AWS： `'ap-southeast-1'` 'ap-southeast-1' （国际）或 `'cn-north-1'` 'cn-north-1' （中国）
`ROLE_ARN` ROLE_ARN	用于执行云函数的角色 ARN 示例（阿里云）： `acs:ram::1222800000000000:role/czudfrole` acs:ram::1222800000000000:role/czudfrole 示例（腾讯云）： `qcs::cam::uin/1000*****:roleName/LakehouseRole` qcs::cam::uin/1000***:roleName/LakehouseRole 示例（AWS**）： `arn:aws:iam::928925945197:role/Lambda-S3-Role` arn:aws:iam::928925945197:role/Lambda-S3-Role
`NAMESPACE` NAMESPACE	云函数的命名空间。腾讯云需要提供该值。对于其他云服务，可填写 `'default'` 'default' ，或根据实际情况留空。
`CODE_BUCKET` CODE_BUCKET	存储云函数代码包的对象存储 bucket 名称。腾讯云格式为 `Bucket名-APP_ID` Bucket名-APP_ID ，如 `myfunction-131xxxxx` myfunction-131xxxxx 。

其中，NAMESPACE：在腾讯云使用必须提供。如果是其他云服务则可以不填写或者直接填写

'default'

'default'

该值如下图所示获取

案例说明

API CONNECTION 主要应用于 EXTERNAL FUNCTION 的创建。EXTERNAL FUNCTION 的使用如下过程

用户开通云上的函数计算服务（如阿里云的函数计算FC）和对象存储服务
将函数执行代码 & 可执行文件、依赖的库、模型和数据文件，打包上传至对象存储
并且授予云器 Lakehouse 操作上述服务和访问函数文件的权限
用户在云器 Lakehouse SQL 语句中调用 EXTERNAL FUNCTION
云器 Lakehouse 根据提供的服务地址和认证信息发送 http 请求调用运行函数
云器 Lakehouse 获取响应信息返回结果因此你必须开通函数计算服务和对象存储服务。并且授权给云器 Lakehouse 权限

阿里云创建 API CONNECTION

环境准备 EXTERNAL FUNCTION 依赖阿里云的 "对象存储" 和 "函数计算" 服务, 请确保相关服务已开通。
步骤1: 开通函数计算 FC 和对象存储 OSS 服务。保持与云器 Lakehouse 实例同地域（如
```
cn-shanghai
```
cn-shanghai
）。
步骤2: 获取 OSS Bucket + AccessKey。
- 进入 OSS 控制台 → 创建 Bucket（与 FC 同地域）。
- 进入 RAM 用户管理 → 创建 AccessKey，记录 AccessKey ID 和 AccessKey Secret。
步骤3: 编辑 AliyunFCFullAccess 权限策略（补充 ram:PassRole 权限）。
- 访问 RAM 策略控制台 → 搜索 AliyunFCFullAccess → 编辑，添加
```
ram:PassRole
```
  ram:PassRole
  部分：
{ "Version": "1", "Statement": [ { "Action": "fc:*", "Resource": "*", "Effect": "Allow" }, { "Action": "ram:PassRole", "Resource": "*", "Effect": "Allow", "Condition": { "StringEquals": { "acs:Service": "fc.aliyuncs.com" } } } ] }
步骤4: 创建自定义权限策略 CzUdfOssAccess。
- 访问 RAM 策略控制台 → 创建权限策略 → 脚本编辑。
- 将
```
bucket_name_1
```
  bucket_name_1
  等替换为实际的 OSS bucket 名称。注意：相同的 bucket 需要同时有
```
bucket_name
```
  bucket_name
  和
```
bucket_name/*
```
  bucket_name/*
  两条 Resource 条目：
{ "Version": "1", "Statement": [ { "Effect": "Allow", "Action": [ "oss:GetObject", "oss:ListObjects", "oss:PutObject", "oss:DeleteObject" ], "Resource": [ "acs:oss:*:*:bucket_name_1", "acs:oss:*:*:bucket_name_1/*" ] } ] }
- 点击下一步，填写策略名称 CzUdfOssAccess，点击完成。
步骤5: 创建 RAM 角色并授权。
- 进入 RAM 角色控制台 → 创建角色：
- 角色类型：阿里云账号 → 其他云账号
- 账号 ID 填
```
1384322691904283
```
  1384322691904283
  （云器 Lakehouse 的主账号），点击下一步
- 在选择权限中，分别勾选系统策略 AliyunFCFullAccess 和自定义策略 CzUdfOssAccess
- 点击下一步，填写角色名称（如
```
CzUDFRole
```
  CzUDFRole
  ），点击确定
- 创建成功后进入角色详情页，获取 角色 ARN：
```
acs:ram::你的账号ID:role/CzUDFRole
```
  acs:ram::你的账号ID:role/CzUDFRole
步骤6: 执行 SQL 创建 API CONNECTION。
CREATE API CONNECTION my_funciton_connection TYPE CLOUD_FUNCTION PROVIDER = 'aliyun' REGION = 'cn-shanghai' ROLE_ARN = 'acs:ram::1757168149572678:role/CzUDFRole' CODE_BUCKET = 'function-compute-my1';
步骤7 (可选): 配置 External ID。

创建成功后执行以下命令获取 External ID：
DESC CONNECTION my_funciton_connection;

预览

回到阿里云 RAM 角色 →
```
CzUDFRole
```
CzUDFRole
→ 信任策略 → 编辑，将
```
sts:ExternalId
```
sts:ExternalId
的值替换为 DESC 结果中的值：
{ "Statement": [ { "Action": "sts:AssumeRole", "Condition": { "StringEquals": { "sts:ExternalId": "替换为DESC结果中的ExternalId" } }, "Effect": "Allow", "Principal": { "RAM": [ "acs:ram::1384322691904283:root" ] } } ], "Version": "1" }
信任策略中的
```
1384322691904283
```
1384322691904283
是云器主账号，不可修改。

腾讯云创建 API CONNECTION

环境准备 EXTERNAL FUNCTION 依赖腾讯云的 "对象存储" 和 "云函数" 服务, 请确保相关服务已开通.

对象存储：需要在云器 Lakehouse 部署地域 (例如 ap-shanghai) 用于存放函数基础代码;
云函数：云函数 服务开通后, 建议使用模板创建功能手动创建一个函数, 推荐使用Flask 框架模板等带有WebFunc标签的模板; 在此过程中, 腾讯云控制台会引导用户完成一些初始化配置, 例如开通日志服务 (CLS) 等依赖服务, 创建必要访问控制 (CAM) 角色, 授予必要访问控制 (CAM) 权限等.
步骤1: 开通腾讯云的云函数（SCF）服务。云函数 region 保持和云器 Lakehouse 开服区域一致。
预览
步骤2: 开通 COS 并创建存储桶。
- 进入 COS 控制台 → 创建存储桶（与 SCF 同地域，例如
```
ap-shanghai
```
  ap-shanghai
  ）。
- 创建后在存储桶列表中可看到完整名称为
```
Bucket名-APP_ID
```
  Bucket名-APP_ID
  （如
```
myfunction-1310000503
```
  myfunction-1310000503
  ）。记录 Bucket 名和 APP_ID，后续配置需要分别使用。
步骤3: 获取 API 密钥。
- 进入访问管理 → 创建密钥，记录 SecretId 和 SecretKey。
步骤4: 创建 CAM 自定义策略 (LakehouseAccess)。
- 登录腾讯云，进入访问管理产品控制台
- 在访问管理页面左侧导航栏进入策略，选择 新建自定义策略 → 按策略语法创建 → 选择 空白模板，粘贴以下 JSON（将
```
<region>
```
  <region>
  、
```
<APP_ID>
```
  <APP_ID>
  、
```
<bucket>
```
  <bucket>
  替换为实际值）：
{ "statement": [ { "action": ["scf:*"], "effect": "allow", "resource": ["*"] }, { "action": ["cos:*"], "effect": "allow", "resource": [ "qcs::cos:<region>:uid/<APP_ID>:<bucket>-<APP_ID>/*" ] } ], "version": "2.0" }
例如：
```
qcs::cos:ap-shanghai:uid/1253896122:qiliang-external-function-1253896122/*
```
qcs::cos:ap-shanghai:uid/1253896122:qiliang-external-function-1253896122/*
- 点击下一步，策略名称填 LakehouseAccess
  LakehouseAccess
  （必须这个名字），点击完成。
⚠️ 策略必须同时包含
```
scf:*
```
scf:*
和
```
cos:*
```
cos:*
两条规则。缺了 COS 权限会导致部署阶段
```
CREATE FUNCTION
```
CREATE FUNCTION
时报
```
AccessDenied (Status Code: 403)
```
AccessDenied (Status Code: 403)
。COS Resource 格式为
```
qcs::cos:<region>:uid/<APP_ID>:<bucket>-<APP_ID>/*
```
qcs::cos:<region>:uid/<APP_ID>:<bucket>-<APP_ID>/*
，末尾必须带
```
/*
```
/*
。
步骤5: 创建 CAM 角色 (LakehouseRole)。
- 进入访问管理 → 新建角色：
- 角色载体：腾讯云账户 → 其他主账号
- 账号 ID 填
```
100029595716
```
  100029595716
  （云器的腾讯云主账号），点击下一步
- 勾选刚创建的
```
LakehouseAccess
```
  LakehouseAccess
  策略，点击下一步
- 角色名称填 LakehouseRole
  LakehouseRole
  （必须这个名字），点击完成
- 创建成功后，进入角色详情页，获取角色 ARN：
```
qcs::cam::uin/你的账号ID:roleName/LakehouseRole
```
  qcs::cam::uin/你的账号ID:roleName/LakehouseRole
⚠️ 角色名必须为
```
LakehouseRole
```
LakehouseRole
。角色载体必须选「其他主账号」并信任云器账号
```
100029595716
```
100029595716
，不是「腾讯云产品服务」。
步骤6: 执行 SQL 创建 API CONNECTION。
CREATE API CONNECTION my_funciton_connection TYPE CLOUD_FUNCTION PROVIDER = 'tencent' REGION = 'ap-shanghai' ROLE_ARN = 'qcs::cam::uin/你的账号ID:roleName/LakehouseRole' NAMESPACE = 'default' CODE_BUCKET = 'myfunction-1310000503';
⚠️
```
CODE_BUCKET
```
CODE_BUCKET
格式为
```
Bucket名-APP_ID
```
Bucket名-APP_ID
（不能只填 Bucket 名）。
```
NAMESPACE
```
NAMESPACE
在腾讯云为必填项，通常为
```
default
```
default
。
步骤7 (可选): 配置 External ID。
⚠️ 注意：为了防止 ROLE_ARN 被第三方获取进行未授权的数据访问，可以使用
```
 EXTERNAL ID
```
EXTERNAL ID
作为一种额外的验证层，确保只有当请求中包含了预设的
```
EXTERNAL ID
```
EXTERNAL ID
时，这一访问才会被允许。这意味着即使第三方知道了其他一些访问信息（如角色ARN），没有正确的
```
EXTERNAL ID
```
EXTERNAL ID
也无法访问资源。
在 API CONNECTION 创建成功后，执行以下命令获取 External ID：
DESC CONNECTION my_funciton_connection;

预览
- 客户侧：进入腾讯云访问管理控制台中，角色 → LakehouseRole → 角色载体 → 管理载体，选择 添加账户 → 选择当前主账号，并填写主账号ID
```
100029595716
```
  100029595716
  （云器的腾讯云主账号），并勾选开启校验，输入刚才 DESC 结果中的 EXTERNAL_ID，点击确定 → 更新。

AWS 创建 API CONNECTION

环境准备 EXTERNAL FUNCTION 依赖AWS的 "对象存储" 和 "Lambda函数" 服务, 请确保相关服务已开通。
- 中国区请使用北京区控制台；国际区请使用对应区域控制台。
步骤1: 开通 Lambda 和 S3 服务。
- 进入 Lambda 控制台和 S3 控制台，确认服务已开通。
步骤2: 创建 S3 存储桶。
- 进入 S3 控制台 → 创建存储桶（与 Lambda 同地域，例如
```
ap-southeast-1
```
  ap-southeast-1
  ）。
- 记录 Bucket 名，后续 SQL 中需要用到。
步骤3: 创建 IAM 用户并获取 AccessKey。
- 进入 IAM 用户 → 创建用户：
- 用户名随意（如
```
qiliang-udf
```
  qiliang-udf
  ），不勾选「提供用户访问 AWS 管理控制台」
- 直接附加策略：搜索勾选
```
AmazonS3FullAccess
```
  AmazonS3FullAccess
- 创建完毕后，进入该用户 → 安全凭证 → 创建访问密钥
- 选择 命令行接口 (CLI) → 创建 → 保存 Access Key ID 和 Secret Access Key
步骤4: 创建 IAM 权限策略。
- 登录AWS 云平台，进入身份与访问管理(IAM) 产品控制台。
- 在 IAM 页面左侧导航栏进入策略，选择 创建策略 → JSON 方式，粘贴以下策略（替换
```
<bucket>
```
  <bucket>
  为步骤2的 Bucket 名）：
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "s3:GetObject", "s3:GetObjectVersion", "s3:PutObject", "s3:ListBucket" ], "Resource": [ "arn:aws:s3:::<bucket>", "arn:aws:s3:::<bucket>/*" ] }, { "Effect": "Allow", "Action": "lambda:*", "Resource": "*" } ] }
⚠️ S3 必须包含
```
PutObject
```
PutObject
（平台需将代码包写入 S3）。Lambda 使用
```
lambda:*
```
lambda:*
避免逐个列出操作导致遗漏。
- 点击下一步，策略名称填
```
LakehouseAccess
```
  LakehouseAccess
  ，点击创建策略。
步骤5: 创建 IAM 角色。
- 进入 IAM 角色 → 创建角色：
- 信任实体类型：AWS 服务 → 使用案例：Lambda
- 权限策略：勾选刚创建的
```
LakehouseAccess
```
  LakehouseAccess
  和 AWS 内置的
```
AWSLambdaBasicExecutionRole
```
  AWSLambdaBasicExecutionRole
- 点击下一步，角色名称填
```
Lambda-S3-Role
```
  Lambda-S3-Role
  ，点击创建角色
- 创建成功后进入角色详情页，复制 Role ARN：
```
arn:aws:iam::你的AWS账号ID:role/Lambda-S3-Role
```
  arn:aws:iam::你的AWS账号ID:role/Lambda-S3-Role
步骤6: 编辑信任策略（添加云器账号的 AssumeRole 权限）。
- 角色详情页 → Trust relationships → 编辑信任策略，将 Lambda 服务 + 云器账号都加入：
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "lambda.amazonaws.com" }, "Action": "sts:AssumeRole" }, { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::014617434350:root" }, "Action": "sts:AssumeRole" } ] }
⚠️
```
014617434350
```
014617434350
是云器国际站 AWS 账号；中国站使用
```
028022243208
```
028022243208
。缺少云器账号的信任关系会报
```
AccessDenied: sts:AssumeRole
```
AccessDenied: sts:AssumeRole
。
⚠️ 这是信任策略（Trust relationships），不是权限策略（Permissions）。别把权限策略的 JSON 贴到这里——两个是不同页面。
步骤7: 执行 SQL 创建 API CONNECTION。
CREATE API CONNECTION udf_noah TYPE CLOUD_FUNCTION PROVIDER = 'aws' REGION = 'ap-southeast-1' ROLE_ARN = 'arn:aws:iam::928925945197:role/Lambda-S3-Role' CODE_BUCKET = 'qiliang-udf-code';
国际区 endpoint 格式为
```
s3.<region>.amazonaws.com
```
s3.<region>.amazonaws.com
，中国区为
```
s3.<region>.amazonaws.com.cn
```
s3.<region>.amazonaws.com.cn
。
步骤8 (可选): 配置 External ID。在 API CONNECTION 创建成功后，执行以下命令获取 External ID：
DESC CONNECTION udf_noah;

预览

回到 IAM 角色 →
```
Lambda-S3-Role
```
Lambda-S3-Role
→ Trust relationships → 编辑信任策略，在云器账号的
```
Statement
```
Statement
里添加
```
Condition
```
Condition
：
{ "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::014617434350:root" }, "Action": "sts:AssumeRole", "Condition": { "StringEquals": { "sts:ExternalId": "DESC结果中的ExternalId值" } } }

后续：

在完成 API CONNECTION 的创建之后，就可以继续创建外部函数，支持用 Python、Java 脚本处理云器 Lakehouse 中的数据。请参考: 创建外部函数

联系我们