alibabacloud-pai-feature-store-featuredb-usage-query

PAI-FeatureStore FeatureDB 使用情况查询与分析

架构：PAI-FeatureStore 实例 → FeatureDB 数据源 → 特征视图 → 使用情况统计

主要功能

1. 总使用情况分析：查询日期范围内（最多 30 天）的每日读写总量
2. 特征视图详情：查询指定日期的特定特征视图使用情况，并按读写次数排序
3. 项目级分析：查询特定项目的每日读写总量（最多 30 天）
4. 特征视图趋势：查询特定特征视图的每日读写趋势（最多 30 天）
5. 成本计算：根据不同区域的官方定价层级计算成本

支持的区域

cn-beijing、cn-hangzhou、cn-shanghai、cn-shenzhen、cn-hongkong、ap-southeast-1、ap-southeast-5、us-west-1、eu-central-1

---

安装

预检查：需要 Aliyun CLI >= 3.3.3

运行 aliyun version 验证版本是否 >= 3.3.3。如果尚未安装或版本过低， 运行 curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash 进行更新， 或查看 references/cli-installation-guide.md 获取安装说明。

然后**[必须]**运行 aliyun configure set --auto-plugin-install true，以启用自动安装插件。 **[必须]**运行 aliyun plugin update，确保本地计算机上已有的插件始终为最新版本。

[必须] CLI User-Agent — 每次调用 aliyun CLI 命令都必须包含： --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-feature-store-featuredb-usage-query

如果启用了自动安装插件，首次使用时会自动安装 PAI-FeatureStore CLI 插件。

超时：默认的 10s 足以完成所有 API 调用。

---

身份验证

预检查：需要 Alibaba Cloud 凭据

安全规则：

• 绝不要读取、回显或打印 AK/SK 值（例如，禁止使用 echo $ALIBABA_CLOUD_ACCESS_KEY_ID）
• 绝不要要求用户在对话或命令行中直接输入 AK/SK
• 绝不要使用包含明文凭据值的 aliyun configure set
• 绝不要输出任何类似密钥的字符串（例如，LTAI5t***、AccessKeyId: xxx、ak-***）
• 只能使用 aliyun configure list 检查凭据状态

aliyun configure list

检查输出中是否存在有效配置（AK、STS 或 OAuth 身份）。

如果不存在有效配置，请在此处停止。

---

必需参数

重要：参数确认 — 执行任何命令或 API 调用前，必须与用户确认所有可由用户自定义的参数（例如 RegionId、实例名称、CIDR 块、密码、域名、资源规格等）。未经用户明确同意，不得假定或使用默认值。

参数名称	必需/可选	描述	默认值
RegionId	必需	Alibaba Cloud 区域 ID。必须是上文列出的支持区域之一。	无
WorkspaceId	可选*	PAI 工作空间 ID（数字，例如 12345）。如果未提供 DatasourceId，则此项必需。	无
DatasourceId	可选*	FeatureDB 数据源 ID（数字，例如 67890）。如果未提供 WorkspaceId，则此项必需。	无
StartDate	可选	查询开始日期，格式为 yyyy-MM-dd。	30 天前（总使用情况）或 7 天前（项目/特征视图）
EndDate	可选	查询结束日期，格式为 yyyy-MM-dd。	昨天
ProjectName	可选	项目名称（项目级和特征视图查询必需）。	无
FeatureViewName	可选	特征视图名称（特征视图趋势查询必需）。	无
SortBy	可选	排序字段：ReadCount 或 WriteCount	ReadCount
Order	可选	排序顺序：ASC 或 DESC	DESC

注意： 必须提供 WorkspaceId 或 DatasourceId。如果两者都未提供，此工具将列出所有可用的 FeatureDB 数据源，供用户选择。

---

RAM 权限

此技能需要以下 RAM 权限。有关详细的策略配置，请参阅 references/ram-policies.md。

所需操作：

• paifeaturestore:ListInstances
• paifeaturestore:GetDatasource
• paifeaturestore:ListDatasources
• paifeaturestore:ListDatasourceFeatureViews

---

核心工作流

功能范围（必须首先检查）

此技能仅支持查询 FeatureDB 读写用量统计。 任何不属于“查询历史读写次数或成本”的请求均不在支持范围内，必须礼貌地拒绝，并列出支持的功能。

[MUST] 如果请求超出支持范围，请礼貌地拒绝并列出支持的功能：

“抱歉，此技能仅支持查询 FeatureDB 读写用量统计，不支持[用户请求]。支持的功能：1）每日读写总量 2）特征视图详情 3）用量趋势 4）成本计算”

功能选择逻辑

要执行哪些功能取决于用户的请求：

场景	操作
请求超出支持范围或不受支持	拒绝并列出支持的功能（见上文）
用户指定了支持的功能	执行指定的功能
用户未指定任何功能	执行默认行为（见下文）

支持的功能

1. 查询 StartDate 至 EndDate 的每日 FeatureDB 读写总量并进行分析（最长跨度为 30 天）
2. 查询指定日期的每个特征视图读写次数，并进行排序和分析
3. 查询指定项目从 StartDate 至 EndDate 的每日 FeatureDB 读写总量并进行分析（最长跨度为 30 天）
4. 查询指定特征视图从 StartDate 至 EndDate 的每日 FeatureDB 读写趋势并进行分析（最长跨度为 30 天）
5. 根据官方定价和查询结果计算成本

面向用户的提示词

提示时请使用描述性名称，而非功能编号，因为对于未读过本文档的用户来说，“功能 3”毫无意义。

执行步骤

步骤 1：验证 PAI-FeatureStore 实例

aliyun paifeaturestore list-instances \
  --region <RegionId> \
  --status Running \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-feature-store-featuredb-usage-query

预期输出：包含正在运行的实例及其 InstanceId 的列表。

错误处理（未找到正在运行的实例时——停止，不要猜测 InstanceId）：

在此区域中未找到正在运行的 PAI-FeatureStore 实例。请确认：

1. RegionId 是否正确？
2. 是否需要切换到其他区域？
3. 要激活 PAI-FeatureStore，请访问控制台

步骤 2：识别 FeatureDB 数据源

情况 A：用户提供了 WorkspaceId

aliyun paifeaturestore list-datasources \
  --region <RegionId> \
  --instance-id <InstanceId> \
  --type FeatureDB \
  --workspace-id <WorkspaceId> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-feature-store-featuredb-usage-query

情况 B：用户提供了 DatasourceId

[MUST] 用户提供 DatasourceId 时，必须调用 GetDatasource 或 ListDatasources 来验证数据源类型是否为 FeatureDB。不要跳过此验证步骤。

aliyun paifeaturestore get-datasource \
  --region <RegionId> \
  --instance-id <InstanceId> \
  --datasource-id <DatasourceId> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-feature-store-featuredb-usage-query

验证：检查响应中的 Type 字段。如果 Type 不是 FeatureDB，请停止并告知用户该数据源不是 FeatureDB 数据源。

情况 C：用户既未提供 WorkspaceId，也未提供 DatasourceId

aliyun paifeaturestore list-datasources \
  --region <RegionId> \
  --instance-id <InstanceId> \
  --type FeatureDB \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-feature-store-featuredb-usage-query

注意：此 API 使用分页。根据 TotalCount 和 PageSize 计算总页数，然后获取所有页面。

分页逻辑示例：

# First call to get TotalCount
FIRST_RESPONSE=$(aliyun paifeaturestore list-datasources \
  --region <RegionId> \
  --instance-id <InstanceId> \
  --type FeatureDB \
  --page-number 1 \
  --page-size 10 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-feature-store-featuredb-usage-query)

# Extract TotalCount and calculate total pages
# Then iterate through all pages
for page in {1..total_pages}; do
  aliyun paifeaturestore list-datasources \
    --region <RegionId> \
    --instance-id <InstanceId> \
    --type FeatureDB \
    --page-number $page \
    --page-size 10 \
    --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-feature-store-featuredb-usage-query
done

向用户展示所有 FeatureDB 数据源。如果只有一个数据源，则直接使用该数据源。

存在多个数据源时，行为取决于查询类型：

查询类型	是否需要用户确认
总用量（功能 1）	询问：“查询所有 N 个数据源的汇总用量，还是选择一个特定数据源？”然后根据用户的选择继续。
特征视图详情／项目／趋势（功能 2/3/4）	必须选择一个数据源。这些查询针对特定数据源，不能跨多个数据源执行。

错误处理：

• 如果 WorkspaceId 或 DatasourceId 无效，则回退到情况 C 并列出所有可用数据源。

步骤 3：查询使用统计

日期验证（API 调用前）：

• 格式：必须为 yyyy-MM-dd（例如，2024-03-15）。如果用户提供了其他格式（例如，3/15、2024.03.15），请转换为正确格式。
• 范围：EndDate - StartDate 必须 ≤ 30 天。如果超出，请让用户缩小范围或拆分为多个查询。
• 边界：EndDate ≤ 今天；StartDate ≤ EndDate。

相对日期范围（“最近 7 天”“最近 30 天”）：计算 StartDate = N 天前，EndDate = 昨天。先单独运行 date 命令，然后在 --start-date/--end-date 中使用命令返回的字面值。绝不要在 CLI 命令中嵌入 $(...)。

根据用户需求执行查询：

功能 1：查询每日读写总使用量

查询从 StartDate 到 EndDate 的每日总量（默认：最近 30 天）。

aliyun paifeaturestore list-datasource-feature-views \
  --region <RegionId> \
  --instance-id <InstanceId> \
  --datasource-id <DatasourceId> \
  --start-date <StartDate> \
  --end-date <EndDate> \
  --verbose false \
  --show-storage-usage false \
  --page-size 1 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-feature-store-featuredb-usage-query

输出：从响应中提取 TotalUsageStatistics。

功能 2：查询特定日期的各功能视图使用量

查询特定日期所有功能视图的读写次数，并进行排序。

aliyun paifeaturestore list-datasource-feature-views \
  --region <RegionId> \
  --instance-id <InstanceId> \
  --datasource-id <DatasourceId> \
  --start-date <TargetDate> \
  --end-date <TargetDate> \
  --verbose true \
  --show-storage-usage false \
  --all true \
  --sort-by <ReadCount|WriteCount> \
  --order <ASC|DESC> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-feature-store-featuredb-usage-query

输出：从响应中提取 FeatureViews 数组。

功能 3：查询特定项目的每日使用量

查询从 StartDate 到 EndDate 的特定项目每日总量（默认：最近 7 天）。

aliyun paifeaturestore list-datasource-feature-views \
  --region <RegionId> \
  --instance-id <InstanceId> \
  --datasource-id <DatasourceId> \
  --start-date <StartDate> \
  --end-date <EndDate> \
  --verbose false \
  --show-storage-usage false \
  --page-size 1 \
  --project-name <ProjectName> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-feature-store-featuredb-usage-query

输出：从响应中提取 TotalUsageStatistics。

错误处理：

• 如果 API 返回的错误表明项目不存在，建议先查询功能 2，获取可查询项目的完整列表（按项目名称去重）。

功能 4：查询特定功能视图的每日使用量

查询从 StartDate 到 EndDate 的特定功能视图每日趋势（默认：最近 7 天）。

aliyun paifeaturestore list-datasource-feature-views \
  --region <RegionId> \
  --instance-id <InstanceId> \
  --datasource-id <DatasourceId> \
  --start-date <StartDate> \
  --end-date <EndDate> \
  --verbose true \
  --show-storage-usage false \
  --all true \
  --project-name <ProjectName> \
  --name <FeatureViewName> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-feature-store-featuredb-usage-query

输出：从 FeatureViews 数组中提取匹配的功能视图。

错误处理：

• 如果响应中没有找到匹配的功能视图，则该功能视图不存在。建议先查询功能 2，获取可查询功能视图的完整列表。

步骤 4：分析结果并计算费用

根据用户需求：

1. 分析使用趋势，基于查询结果
2. 计算费用 官方定价（每 10,000 次请求）：

地区	写入费用	读取费用
北京、上海、杭州、深圳	¥0.151	¥0.0755
香港、新加坡、硅谷、法兰克福、雅加达	¥0.2651	¥0.1326

3. 提供分析结果：

   • 找出高流量功能视图
   • 突出显示使用模式（峰值、趋势）
   • 在适用时提供费用明细和优化建议

4. 提供后续步骤：

   • 询问用户是否希望深入查看特定项目或功能视图
   • 如果尚未计算费用，可提出进行计算
   • 建议进一步的分析选项

---

成功验证

满足以下条件即表示技能执行成功：

1. ✅ 找到有效的 PAI-FeatureStore 实例
2. ✅ 已识别或选定 FeatureDB 数据源
3. ✅ 已成功获取使用统计数据
4. ✅ 已清晰地分析并呈现结果
5. ✅ 费用计算准确（如有请求）
6. ✅ 响应语言与用户提问的语言一致

详细的验证步骤请参阅 references/verification-method.md。

---

清理

此技能执行只读操作，不会创建任何资源。无需清理。

---

最佳实践

1. 执行任何命令前，务必与用户确认 RegionId
2. 列出数据源时正确使用分页，确保获取所有结果
3. 在分析中提供背景信息：不要只展示数字，还要解释趋势和模式
4. 提供可操作的见解：建议进一步调查哪些功能视图或项目
5. 妥善处理错误：如果项目或功能视图不存在，先引导用户列出所有可用选项
6. 准确计算费用：根据区域使用正确的定价层级
7. 保持用户参与：展示结果后，询问用户是否想要深入了解或分析特定方面
8. 礼貌拒绝范围之外的请求：如果请求与查询使用统计数据无关，请礼貌拒绝并列出支持的功能

---

参考文档

参考资料	描述
RAM Policies	所需的 RAM 权限和策略配置
Related APIs	使用的 API 和 CLI 命令完整列表
Verification Method	各项操作的详细验证步骤
CLI Installation Guide	Aliyun CLI 安装和设置说明
Acceptance Criteria	测试模式和验证标准