Data App 配置文件
本文档描述了 TiDB Cloud 中 Data App 的配置文件。
如果你已经将你的 Data App 连接到 GitHub，你可以在 GitHub 上的指定目录中找到你的 Data App 的配置文件，如下所示：
├── <你的 Data App 目录>
│ ├── data_sources
│ │ └── cluster.json
│ ├── dataapp_config.json
│ ├── http_endpoints
│ │ ├── config.json
│ │ └── sql
│ │ ├── <method>-<endpoint-path1>.sql
│ │ ├── <method>-<endpoint-path2>.sql
│ │ └── <method>-<endpoint-path3>.sql
数据源配置
Data App 的数据源来自其链接的 TiDB 集群。你可以在 data_sources/cluster.json 中找到数据源配置。
├── <你的 Data App 目录>
│ ├── data_sources
│ │ └── cluster.json
对于每个 Data App，你可以链接一个或多个 TiDB 集群。
以下是 cluster.json 的示例配置。在此示例中，此 Data App 有两个链接的集群。
[
{
"cluster_id": <集群 ID1>
},
{
"cluster_id": <集群 ID2>
}
]
字段说明如下：
Data App 配置
Data App 的属性包含 App ID、名称和类型。你可以在 dataapp_config.json 文件中找到这些属性。
├── <你的 Data App 目录>
│ ├── dataapp_config.json
以下是 dataapp_config.json 的示例配置。
{
"app_id": "<Data App ID>",
"app_name": "<Data App 名称>",
"app_type": "dataapi",
"app_version": "<Data App 版本>",
"description": "<Data App 描述>"
}
每个字段的说明如下：
HTTP 端点配置
在你的 Data App 目录中，你可以在 http_endpoints/config.json 中找到端点配置，在 http_endpoints/sql/<method>-<endpoint-name>.sql 中找到 SQL 文件。
├── <你的 Data App 目录>
│ ├── http_endpoints
│ │ ├── config.json
│ │ └── sql
│ │ ├── <method>-<endpoint-path1>.sql
│ │ ├── <method>-<endpoint-path2>.sql
│ │ └── <method>-<endpoint-path3>.sql
端点配置
对于每个 Data App，可以有一个或多个端点。你可以在 http_endpoints/config.json 中找到 Data App 的所有端点的配置。
以下是 config.json 的示例配置。在此示例中，此 Data App 有两个端点。
[
{
"name": "<端点名称1>",
"description": "<端点描述1>",
"method": "<HTTP 方法1>",
"endpoint": "<端点路径1>",
"data_source": {
"cluster_id": <集群 ID1>
},
"params": [],
"settings": {
"timeout": <端点超时时间>,
"row_limit": <最大行数>,
"enable_pagination": <0 | 1>,
"cache_enabled": <0 | 1>,
"cache_ttl": <生存时间周期>
},
"tag": "Default",
"batch_operation": <0 | 1>,
"sql_file": "<SQL 文件目录1>",
"type": "sql_endpoint",
"return_type": "json"
},
{
"name": "<端点名称2>",
"description": "<端点描述2>",
"method": "<HTTP 方法2>",
"endpoint": "<端点路径2>",
"data_source": {
"cluster_id": <集群 ID2>
},
"params": [
{
"name": "<参数名称>",
"type": "<参数类型>",
"required": <0 | 1>,
"default": "<参数默认值>",
"description": "<参数描述>",
"is_path_parameter": <true | false>
}
],
"settings": {
"timeout": <端点超时时间>,
"row_limit": <最大行数>,
"enable_pagination": <0 | 1>,
"cache_enabled": <0 | 1>,
"cache_ttl": <生存时间周期>
},
"tag": "Default",
"batch_operation": <0 | 1>,
"sql_file": "<SQL 文件目录2>",
"type": "sql_endpoint",
"return_type": "json"
}
]
每个字段的说明如下：
SQL 文件配置
端点的 SQL 文件指定了通过端点查询数据的 SQL 语句。你可以在 http_endpoints/sql/ 目录中找到 Data App 的端点 SQL 文件。每个端点都应该有一个对应的 SQL 文件。
SQL 文件的名称格式为 <method>-<endpoint-path>.sql，其中 <method> 和 <endpoint-path> 必须与 http_endpoints/config.json 中的 method 和 endpoint 配置匹配。
在 SQL 文件中，你可以编写表连接查询、复杂查询和聚合函数等语句。以下是一个示例 SQL 文件。
/* 入门：
在输入 SQL 语句之前，输入 "USE {database};"。
输入 "--你的问题" + Enter 可以在 TiDB Cloud 控制台中尝试 AI 生成的 SQL 查询。
声明参数的格式为 "Where id = ${arg}"。
*/
USE sample_data;
SELECT
rank,
company_name,
FROM
global_fortune_500_2018_2022
WHERE
country = ${country};
编写 SQL 文件时，请注意以下事项：
在 SQL 文件的开头，你需要在 SQL 语句中指定数据库。例如，
USE database_name;。要定义端点的参数，你可以将其作为变量占位符（如
${variable-name}）插入到 SQL 语句中。在上述示例中，
${country}用作端点的参数。使用此参数，你可以在端点 curl 命令中指定所需的国家/地区进行查询。