domo-data-api

用途

该技能是 Domo 数据访问的高层入口，用于在 Domo App Platform 中读取数据集。其核心原则是“工具包/查询优先”（toolkit/query-first），即优先使用 @domoinc/query 进行数据集读取，并将详细的查询工作路由到 domo-dataset-query。旧的“端点优先”指引已被归档到 archive/legacy-rules/domo-data-api.md。

主要能力

使用 @domoinc/query 对数据集进行查询，支持 select、groupBy、orderBy 等操作。
在需要时使用 SQL（SqlClient）作为例外手段。
通过 manifest.json 的 datasetsMapping 声明数据集。
本地开发时使用 @domoinc/ryuu-proxy 进行本地 API 路由，并通过 domo login 进行认证。

使用方式

1. 使用 @domoinc/query 进行数据集查询

安装命令：

yarn add @domoinc/query

示例代码：

import Query from '@domoinc/query';

const salesByRegion = await new Query() .select(['region', 'Sales_Amount']) .groupBy('region', { Sales_Amount: 'sum' }) .orderBy('Sales_Amount', 'descending') .fetch('sales');

2. SQL 仅作为例外

如果使用 SQL（SqlClient），需注意它不会自动遵循仪表板中的页面筛选器。

示例代码：

import { SqlClient } from '@domoinc/toolkit';

const sqlClient = new SqlClient(); const result = await sqlClient.get( 'sales', 'SELECT region, SUM(Sales_Amount) AS total FROM sales GROUP BY region' ); const rows = result.body.rows;

3. 必需的 Manifest 配置

每个数据集仍必须在 manifest.json 的 datasetsMapping 下声明。

示例：

{ "datasetsMapping": [ { "alias": "sales", "dataSetId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "fields": [] } ] }

关键注意事项：fields 必须存在（可以为 []），以避免 manifest 解析错误。

4. 本地开发

使用 @domoinc/ryuu-proxy 进行本地 API 路由。

使用 domo login 进行认证。

适用场景

适用于在 Domo App Platform 中构建应用并需要读取数据集的场景，尤其是希望通过 @domoinc/query 以声明式方式完成查询、聚合和排序的开发者。

限制与注意事项

SQL（SqlClient）不会自动遵循仪表板中的页面筛选器。
manifest.json 中的 datasetsMapping 必须配置有效的别名，且 fields 字段必须存在（可以为空数组）。
聚合操作应使用实际的数据集字段名。
不应使用 .aggregate()。
默认情况下不应使用原始 /data/v1 端点。

检查清单

datasetsMapping 别名已配置且有效。
查询使用 Query 实现（默认不使用原始 /data/v1）。
聚合使用实际的数据集字段名。
未使用 .aggregate()。

技能介绍

用途