huawei-cloud-functiongraph-trigger-create

概述

此技能支持为华为云 FunctionGraph 函数创建和配置定时触发器（TIMER 类型），并支持 Quartz Cron 表达式格式，以便灵活配置调度。

该触发器可按指定时间间隔自动执行无服务器函数，适用于：

• 周期性数据处理任务
• 定时备份操作
• 定期监控和运行状况检查
• 基于时间的通知系统

先决条件

使用此技能前，请确保满足以下要求：

1. Python 环境：已安装 Python 3.9+
2. SDK 安装：安装 FunctionGraph SDK：pip install huaweicloudsdkfunctiongraph
3. 环境变量：配置以下环境变量：
   • HUAWEI_AK：华为云访问密钥
   • HUAWEI_SK：华为云秘密密钥
   • HUAWEI_REGION：目标区域（例如，cn-north-4）
   • HUAWEI_PROJECT_ID：项目 ID
4. FunctionGraph 函数：目标函数必须已存在于指定区域
5. 网络访问：与华为云 API 终端节点之间的网络连接稳定

工作流

创建定时 TIMER 触发器的完整工作流包括以下步骤：

步骤 1：加载环境变量并进行身份验证（加载环境变量/鉴权）

脚本启动时会读取以下环境变量：

• HUAWEI_AK：华为云访问密钥（必需）
• HUAWEI_SK：华为云秘密密钥（必需）
• HUAWEI_REGION：目标区域，默认为 cn-north-4
• HUAWEI_PROJECT_ID：项目 ID

如果缺少 HUAWEI_AK 或 HUAWEI_SK，脚本会打印 Config error: Please set environment variables HUAWEI_AK and HUAWEI_SK，并在调用任何 API 之前退出。

步骤 2：确认目标函数 URN（确认 function_urn）

通过 --function-urn 传入目标函数 URN，例如 urn:fss:cn-north-4:project_id:function:default:my-function:latest。创建触发器前，脚本会调用 ShowFunctionConfig 验证函数是否存在。如果找不到该函数，则返回 FunctionNotFound 并停止，不会创建任何内容。

步骤 3：确认触发器配置（确认触发配置）

验证触发器参数（参见参数确认）：

• --name：触发器名称，长度为 1–64 个字符
• --schedule：Cron 类型使用 Quartz Cron 表达式（6–7 个字段），Rate 类型使用 5m 这样的频率值
• --schedule-type：Cron（默认）或 Rate
• --status：ACTIVE（默认）或 DISABLED
• --user-event：可选的其他用户事件数据

调用 API 前，脚本会验证所有参数（必填字段、Cron 语法、名称长度、状态值）。

步骤 4：执行创建脚本（执行 create_trigger.py）

在技能目录中运行：

python3 scripts/create_trigger.py \
    --function-urn "urn:fss:cn-north-4:project_id:function:default:my-function:latest" \
    --name "daily-trigger" \
    --schedule "0 0 2 * * ?" \
    --schedule-type "Cron" \
    --status "ACTIVE"

步骤 5：验证结果（验证结果）

• 成功时，脚本会打印包含 status: "success" 的 JSON 响应，其中包括创建的 trigger_id、trigger_name、trigger_type（TIMER）、schedule 和 enable_status。
• 失败时，脚本会打印 status: "failed"，并包含 error_code（InvalidParameter、FunctionNotFound、TriggerAlreadyExists、TriggerLimitExceeded、InternalError），然后以非零代码退出。请修正相应参数并重新运行脚本。
• 你也可以在 FunctionGraph 控制台中确认结果：函数详情 → 触发器选项卡，新建的 TIMER 触发器应显示为 Active 状态。

用法

基本命令结构

python3 scripts/create_trigger.py \
    --function-urn "urn:fss:cn-north-4:project_id:function:default:my-function:latest" \
    --name "daily-trigger" \
    --schedule "0 0 2 * * ?" \
    --schedule-type "Cron" \
    --status "ACTIVE"

示例

Cron 表达式触发器

python3 scripts/create_trigger.py \
    --function-urn "urn:fss:cn-north-4:project_id:function:default:my-function:latest" \
    --name "hourly-report" \
    --schedule "0 0 8 * * ?" \
    --schedule-type "Cron"

固定频率触发器

python3 scripts/create_trigger.py \
    --function-urn "urn:fss:cn-north-4:project_id:function:default:my-function:latest" \
    --name "every-5min" \
    --schedule "5m" \
    --schedule-type "Rate"

Cron 表达式格式

FunctionGraph 使用包含 6 或 7 个字段的 Quartz Cron 格式（第 7 个字段 year 为可选项）：

┌───────────── second (0-59)
│ ┌───────────── minute (0-59)
│ │ ┌───────────── hour (0-23)
│ │ │ ┌───────────── day of month (1-31)
│ │ │ │ ┌───────────── month (1-12)
│ │ │ │ │ ┌───────────── day of week (1-7, 1=Sunday)
│ │ │ │ │ │ ┌───────────── year (optional, e.g. 2026)
│ │ │ │ │ │ │
* * * * * ? *

有关特殊字符和常见示例的 Cron 表达式详细参考，请参见 Cron 表达式参考。

参数确认

创建触发器前，请确认以下参数：

参数	CLI 参数	必填	描述	示例
function_urn	--function-urn	是	目标函数 URN	urn:fss:cn-north-4:xxx:function:default:my-func:latest
trigger_name	--name	是	触发器名称（1-64 个字符）	daily-trigger
schedule	--schedule	是	Cron 表达式或 Rate 值	0 0 2 * * ? 或 5m
schedule_type	--schedule-type	否	Cron（默认）或 Rate	Cron
enable_status	--status	否	ACTIVE（默认）或 DISABLED	ACTIVE
user_event	--user-event	否	其他用户事件数据	optional info

确认清单

• 函数 URN 正确且函数存在
• 已验证 Cron 表达式
• 触发器名称符合命名规范
• IAM 权限充足
• 区域与函数所在位置一致

输出格式

成功响应

{
    "status": "success",
    "trigger_id": "timer-xxx-xxx-xxx",
    "trigger_name": "daily-trigger",
    "trigger_type": "TIMER",
    "schedule": "0 0 2 * * ?",
    "enable_status": "ACTIVE",
    "message": "Trigger created successfully"
}

错误响应

{
    "status": "failed",
    "error_code": "TriggerAlreadyExists",
    "message": "Trigger with the same name already exists"
}

如需完整的错误代码和故障排查信息，请参阅 Cron 表达式参考。

验证方法

创建触发器后，请验证其配置：

1. 列出函数触发器

前往 FunctionGraph 控制台 → 函数详情 → 触发器选项卡，查看所有触发器

2. 检查触发器详情

前往 FunctionGraph 控制台 → 函数详情 → 触发器 → 查看触发器详情

3. 监控触发器执行情况

前往 FunctionGraph 控制台 → 函数详情 → 触发器 → 查看执行历史

预期指标：

• 触发器状态：Active
• 下次执行时间：计算正确
• 执行历史：没有失败的调用

最佳实践

Cron 表达式最佳实践

1. 避免频繁执行：除非必要，否则使用 ≥ 5 分钟的间隔
2. 考虑时区：FunctionGraph 默认使用 UTC
3. 未使用的日期字段使用 ?：月中某天或周中某天应使用 ?
4. 创建前先验证：使用在线 Cron 验证器测试表达式

命名规范

• 使用描述性名称：daily-data-sync、hourly-health-check
• 遵循以下模式：[frequency]-[purpose]
• 最长 64 个字符
• 使用小写字母和连字符

安全注意事项

1. 最小权限：仅授予必要的 IAM 权限
2. 启用加密：对敏感函数输入使用 KMS
3. 监控执行情况：为失败设置 Cloud Eye 告警
4. 速率限制：配置适当的重试参数

运维建议

1. 测试时先将状态设为禁用
2. 在描述字段中记录触发器用途
3. 为瞬时故障设置适当的重试
4. 启用后监控首次执行

参考文档

如需详细信息，请参阅：

• SDK 安装指南
• IAM 策略
• 验证方法
• 验收标准
• Cron 表达式参考

重要说明

兼容性说明

此技能旨在适配 Huawei Cloud FunctionGraph API。tags 字段有助于发现和分类技能。

限制

1. 触发器上限：默认情况下，每个函数最多支持 10 个触发器
2. Cron 精度：秒级调度可能会有轻微延迟
3. 超时处理：函数超时时间应短于触发器间隔
4. 冷启动：首次执行可能会产生额外延迟

成本影响

• 配置触发器不产生额外费用
• 函数执行按调用次数计费
• 请考虑执行频率以优化成本

常见问题

1. 时区错误：请记住，FunctionGraph 使用 UTC
2. 计划重叠：多个触发器可能导致并发执行
3. 长时间运行的函数：确保函数在下一次触发前完成
4. Cron 语法错误：部署前验证表达式格式

如需故障排查和错误代码，请参阅 Cron 表达式参考。

---

相关技能：

• huawei-cloud-functiongraph-function-create
• huawei-cloud-functiongraph-deploy