# 更新图表

更新指定图表的查询、展示和刷新配置。

```text
PATCH https://moi.matrixorigin.cn/newmoi/data-dashboards/{dashboard_id}/charts/{chart_id}
```

## 调用前准备

准备有目标工作区访问权限的个人访问令牌和目标工作区 ID。

下方示例使用：

- `$AI_STUDIO_API_KEY`：实际个人访问令牌，通过 `X-API-Key` Header 传递。
- `$WORKSPACE_ID`：目标工作区 ID，通过 `X-Workspace-ID` Header 传递。

- `$DASHBOARD_ID`：要使用的 `dashboard_id`，通过请求路径指定目标资源。
- `$CHART_ID`：要使用的 `chart_id`，通过请求路径指定目标资源。

## 路径参数

| 参数 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `dashboard_id` | string | 是 | 数据看板 ID。 |
| `chart_id` | string | 是 | 图表 ID。 |
## 请求体

| 参数 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `name` | string | 是 | 图表名称。 |
| `chart_type` | string | 是 | 图表类型。 |
| `sql_text` | string | 是 | 图表 SQL。 |
| `chart_config` | string | 是 | 图表配置。 |
| `layout_config` | string | 是 | 布局配置。 |
| `refresh_interval` | string | 是 | 刷新周期。 |
| `alert_enabled` | boolean | 是 | 是否启用告警。 |
| `alert_config` | string | 是 | 告警配置。 |
## 请求示例

```bash
curl -X PATCH "https://moi.matrixorigin.cn/newmoi/data-dashboards/$DASHBOARD_ID/charts/$CHART_ID" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "每日订单数",
    "chart_type": "line",
    "sql_text": "SELECT 1",
    "chart_config": "{}",
    "layout_config": "{}",
    "refresh_interval": "manual",
    "alert_enabled": false,
    "alert_config": "{}"
  }'
```

## 成功响应

更新成功时返回更新后的图表和调度状态。

```json
{
  "code": 0,
  "data": {
    "ID": "0198ce79-2320-76aa-9d34-7f8e9d0c1b2a",
    "DashboardID": "0198ce73-3d20-7c12-9a11-1a2b3c4d5e6f",
    "Name": "每日订单数",
    "ChartType": "line",
    "SQLText": "SELECT 1",
    "DatabaseName": "analytics",
    "ChartConfig": "{}",
    "LayoutConfig": "{}",
    "RefreshInterval": "manual",
    "SchedulerTaskID": "",
    "ScheduleVersion": 2,
    "ScheduleStatus": "ready",
    "ScheduleError": "",
    "ScheduleOperationID": "operation-002",
    "AlertEnabled": false,
    "AlertConfig": "{}",
    "SnapshotEpochAt": "2026-08-21T07:10:00Z",
    "CreatedAt": "2026-08-21T07:00:00Z",
    "UpdatedAt": "2026-08-21T07:10:00Z"
  }
}
```

响应字段如下。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `data.ID` | string | 图表 ID。 |
| `data.DashboardID` | string | 所属数据看板 ID。 |
| `data.Name` | string | 图表名称。 |
| `data.ChartType` | string | 图表类型。 |
| `data.SQLText` | string | 图表 SQL。 |
| `data.DatabaseName` | string | 图表查询使用的数据库名称。 |
| `data.ChartConfig` | string | 图表配置。 |
| `data.LayoutConfig` | string | 布局配置。 |
| `data.RefreshInterval` | string | 刷新周期。 |
| `data.SchedulerTaskID` | string | 调度任务 ID；未创建调度任务时为空。 |
| `data.ScheduleVersion` | integer | 调度配置版本。 |
| `data.ScheduleStatus` | string | 调度状态。 |
| `data.ScheduleError` | string | 调度错误；没有错误时为空。 |
| `data.ScheduleOperationID` | string | 本次调度操作 ID。 |
| `data.AlertEnabled` | boolean | 是否启用告警。 |
| `data.AlertConfig` | string | 告警配置。 |
| `data.SnapshotEpochAt` | string | 结果快照起始时间。 |
| `data.CreatedAt` | string | 创建时间。 |
| `data.UpdatedAt` | string | 更新时间。 |

## 错误响应

```json
{
  "code": 2,
  "message": "invalid argument",
  "details": {
    "domain": "moi-core.catalog.data_dashboard",
    "reason": "DATA_DASHBOARD_INVALID_REQUEST"
  }
}
```

### 常见 HTTP 错误

```{list-table}
:header-rows: 1
:widths: 12 22 32 34

* - HTTP 状态码
  - 响应 `code`
  - 常见原因
  - 建议操作
* - `400`
  - `2`
  - 路径参数、查询参数或请求体无效。
  - 检查请求中的标识和字段。
* - `401`
  - `6`
  - 凭据缺失或无效。
  - 检查 API Key。
* - `403`
  - `5`
  - 当前身份没有目标资源的权限。
  - 使用有权限的凭据，或联系管理员授权。
* - `404`
  - `3`
  - 目标资源不存在，或当前工作区不可见。
  - 检查资源标识和工作区。
* - `409`
  - `4`
  - 资源正在执行其他操作，或调度状态发生冲突。
  - 重新查询资源状态后重试。
* - `500`
  - `1`
  - 服务端无法完成请求。
  - 记录请求时间和错误信息后重试。
* - `503`
  - `15`
  - 数据看板服务、调度服务或其依赖暂时不可用。
  - 稍后重试。
```