/configure-quality-rule

name: configure-quality-rule
description: |-
  通过 Dataphin OpenAPI 完成数据质量规则的全生命周期管理：创建监控对象、配置质量规则、设置调度与告警、试跑验证、启停规则、查看执行结果。

  当用户场景涉及为某张表/字段配置质量校验、设置质量调度或告警、试跑质量规则、查看质量结果时进入。

  触发场景：
  - 「给 X 表 Y 字段配非空/唯一/值域/枚举校验」
  - 「质量规则要不要试跑 / 质量试跑失败排查」
  - 「质量规则挂调度 / 质量告警通知负责人」

  触发词：质量监控、质量规则、数据质量校验、质量告警、质量试跑、质量调度、监控对象、validateCondition、upsert-quality-rule。

  关键限制 / 类型分支：监控对象类型必须先确认；监控对象名称不可让用户填写；templateId 必须用 list-quality-templates 实测获取；模板级 formProperties 必填项以界面和模板定义为准；validateCondition 无后端默认必须显式传；分区表试跑必须钉单分区；归档模式/计分方式/质量分权重 OpenAPI 不可配。

配置数据质量规则（创建 → 调度告警 → 试跑 → 监控）

1. Scenario Description

通过 Dataphin OpenAPI 完成一条质量规则从「监控对象 → 规则 → 调度/告警 → 试跑 → 启停 → 看板」的完整闭环。

> **核心原则**：本 skill 通过 OpenAPI 配置，但目的是让用户在**界面上看到的结果与手工配置一致、且能正常运行**。因此： > 1. **必填项以界面为准**，不能因 API 允许省略就擅自省略——先与用户确认（见 §6）。 > 2. **监控对象类型必须先确认**：`TABLE` / `DATASOURCE_TABLE` / `DATASOURCE` / `INDEX` / `REALTIME_LOGICAL_TABLE` 会决定对象定位方式、创建参数、可用模板和调度边界；不能仅凭对象名猜类型。 > 3. **监控对象名称（WatchName/tableName）不是用户配置项**，禁止让用户填写或选择；由 skill 根据目标对象元数据自动生成/回查校验。 > 4. **模板级必填项以模板和界面为准**，不能因为 `SaveQualityRule.formProperties` 顶层标为非必填就传空；例如 `TABLE_SCHEMA_CHECK`/2600 必须先选校验表并传 `dataSourceTable`。 > 5. **API 无法指定的项**（异常归档表、计分方式、质量分权重）必须**主动向用户说明默认值**。 > 7. **规则模版的必填项都不能为空**：`template-config-catalog.json` 中 `required=true` 的配置项必须全部有值。处理方式二选一： > - **有合理默认值** → 自动补上（如 `timeTolerance` 默认 `>0天 且 <1天`，`validateCondition` 默认 `ERROR_NUMBER=0`） > - **无合理默认值** → 必须询问用户（如 `validateField` 校验字段、`doubleTableCompareTable` 比较表、`customSql` 自定义SQL） > - **CLI 无法安全传值** → 创建规则后主动告知用户需到界面手工补充 > 8. **调度、告警由独立命令实现**，创建规则前必须**分别询问是否需要**，不默认配也不默认跳过。

**Architecture**：`Dataphin Tenant + QualityWatch（监控对象） + QualityRule（规则） + QualitySchedule（调度） + QualityAlert（告警）`。

2. Installation

> 仅**公共云（A）走 CLI** 时需要安装插件；**独立部署（B）直调 OpenAPI（见 §3 执行通道）无需安装 CLI 插件**。

aliyun plugin install --names aliyun-cli-dataphin-public

（详见 [`references/cli-installation-guide.md`](references/cli-installation-guide.md)）

3. Environment Variables

> 凭证与环境变量由父 skill `alibabacloud-dataphin-skills` 统一声明并预检（父 §3 + §4 Authentication + §8 Step 0，先于路由到本 skill 执行）；本 skill 不重复声明。

> **执行通道（按父 §4.1 自动判定的环境选择，★重要）**：本 skill 的 OpenAPI Action 与参数语义两套环境一致，但**调用通道按部署形态区分**，由父 skill `alibabacloud-dataphin-skills` 的 §4.1 环境自动判定（endpoint / AK 前缀 / 探测，运行时推断，不询问类型）结果决定： > - **A `public-cloud`（公共云）→ 默认用 CLI**：`aliyun dataphin-public <命令>`（下文各命令），默认 endpoint + `aliyun configure` 主/子账号 AK。 > - **B `standalone`（独立部署 / POC）→ 默认直接调 OpenAPI，不走 CLI**：独立部署环境下 `aliyun dataphin-public` 对 HTTPS endpoint 会直接报 `dial tcp ... connect: bad file descriptor`（Go CLI 已知网络层 bug，`curl` 能通、CLI 不通）。**遇到该环境不要再尝试/重试 CLI**，直接用阿里云 Python SDK（RPC 风格）调 OpenAPI，自签证书需关闭校验（`verify=False` / `ignore_ssl`）。 > - **Action 名（★POC 实测坑）**：真实 OpenAPI Action 名 = **对应 CLI kebab 命令的 PascalCase**（如 `list-quality-watches`→`ListQualityWatches`、`upsert-quality-rule`→`UpsertQualityRule`、`get-quality-watch-by-object-id`→`GetQualityWatchByObjectId`）。**不要猜、也不要沿用文档里可能残留的旧名**——`PagedQueryQualityWatches`/`SaveQualityWatch`/`RemoveQualityRules` 这类是旧裸 OpenAPI 命名，POC 直调会报 `Unknown API`。**拿不准就先用 `aliyun dataphin-public <command> --cli-dry-run` 导出真实 Action 名与参数再调**。参数名 kebab-case → camelCase（`--watch-type`→`WatchType`），`--tenant-id`→`OpTenantId`；复杂对象（`--table-info`/`--validate-condition-list` 等）作为 JSON string/list 传同名 camelCase 参数，值语义一致。 > - **Version / endpoint / 凭证**：`Version` 以环境实测为准（POC 独立部署实测 `2023-06-30`）；endpoint、AK/SK 从 profile / 环境变量获取。 > - **Python SDK 骨架 + 签名要点（★POC 实测坑）**：POC standalone 的 OpenAPI **要求全部业务参数放在 query string 里参与签名**；而 `aliyunsdkcore` 默认会把参数塞进 request body，body 参数不进签名串 → 始终 `SignatureDoesNotMatch`。**所有业务参数一律用 `add_query_param` 进 query string，禁止用 body（`add_body_params`）**；若用 SDK 仍签名不过，改为**手动签名 + query string 传参**（实测这样 `ListQualityWatches` 才能正常返回）。 > ```python > from aliyunsdkcore.client import AcsClient > from aliyunsdkcore.request import CommonRequest > import json, os > client = AcsClient(AK, SK, "cn-shanghai") # regionId 占位即可 > # UA 可观测（Principle 9）：SKILL_SESSION_ID 由 Agent 执行时内联注入（继承自父 skill） > _sid = os.environ.get("SKILL_SESSION_ID", "") > client.set_user_agent("AlibabaCloud-Agent-Skills/configure-quality-rule" + ("/" + _sid if _sid else "")) > req = CommonRequest() > req.set_domain(ENDPOINT) # 如 dataphin-openapi.poc.lydaas.com，不带 https:// > req.set_version("2023-06-30") # 以环境实测为准 > req.set_action_name("ListQualityWatches") # 真实 Action = CLI list-quality-watches 的 PascalCase；拿不准用 --cli-dry-run 导出 > req.set_method("POST"); req.set_protocol_type("https") > # ★所有业务参数必须用 add_query_param 进 query string 参与签名，禁用 body（add_body_params），否则 SignatureDoesNotMatch > req.add_query_param("OpTenantId", TENANT_ID) # --tenant-id → OpTenantId > req.add_query_param("Name", KEYWORD); req.add_query_param("PageNo", 1); req.add_query_param("PageSize", 100) > # 自签证书：对底层 requests/urllib3 关闭校验（verify=False / urllib3.disable_warnings） > resp = client.do_action_with_exception(req) > data = json.loads(resp) > ``` > > **SDK 仍报 `SignatureDoesNotMatch`（把参数落到 body）→ 手动签名**：把公共参数（`Action`/`Version`/`Format=JSON`/`AccessKeyId`/`SignatureMethod=HMAC-SHA1`/`SignatureVersion=1.0`/`SignatureNonce`/`Timestamp`）与全部业务参数一起放进 query，按 key 字典序排序拼成规范化 query 串，做 RPC 签名（`StringToSign = "POST&" + %2F + "&" + URLEncode(排序后query串)`，HMAC-SHA1 密钥为 `AccessKeySecret + "&"`，结果 base64 作 `Signature`），再把含 `Signature` 的完整 query string 发出（`requests`，`verify=False`）。 > - 环境（公共云 A / 独立部署 B）由父 §4.1 运行时自动判定，据此选通道，**不询问用户类型**。两套通道均带可观测标识：CLI 用 `--user-agent`；OpenAPI 直调把相同 UA 放进 header（如 `User-Agent`）。

4. Authentication

> **Pre-check: Alibaba Cloud Credentials Required** > > **Security Rules:** > - **NEVER** read, echo, or print AK/SK values > - **NEVER** ask the user to input AK/SK directly in the conversation or command line > - **NEVER** use `aliyun configure set` with literal credential values > - **ONLY** use `aliyun configure list` to check credential status >