---
title: "更新机密信息元数据"
description: "更新机密信息的展示信息、责任人、标签、扩展元数据或启用状态，不修改机密值。"
---

> 文档索引
> 完整文档索引：http://127.0.0.1:4321/docs/llms.txt

# 更新机密信息元数据

更新机密信息的展示信息、责任人、标签、扩展元数据或启用状态，不修改机密值。

**PATCH /api/v1/secret/{resource_path...}**

- 模块：机密信息存储（Secret KV）
- 认证：使用 App Header 签名或 App Secret
- 系统状态：需要 unsealed

## 请求示例

```bash
curl --request PATCH \
  'http://127.0.0.1:7770/api/v1/secret/production/orders/database/metadata' \
  --header 'X-QK-AppID: $APP_ID' \
  --header 'X-QK-Timestamp: $TIMESTAMP' \
  --header 'X-QK-Nonce: $NONCE' \
  --header 'X-QK-Signature: $SIGNATURE' \
  --header 'Content-Type: application/json' \
  --data '{
  "contact_email": "owner@example.com",
  "contact_name": "张三",
  "contact_phone": "13800000000",
  "department": "平台工程部",
  "description": "生产订单服务连接数据库使用",
  "labels": {
    "environment": "production"
  },
  "metadata": {
    "ticket": "SEC-1001"
  },
  "name": "订单数据库凭据",
  "organization": "示例科技",
  "status": "active"
}'
```

## Path 参数

| 名称 | 类型 | 必填 | 敏感 | 默认值 | 说明 |
| --- | --- | --- | --- | --- | --- |
| `resource_path` | `string` | 是 | 否 | — | 机密信息路径，并在末尾追加 /metadata |

## Query 参数

无。

## Body 参数

| 名称 | 类型 | 必填 | 敏感 | 默认值 | 说明 |
| --- | --- | --- | --- | --- | --- |
| `contact_email` | `string` | 否 | 否 | — | 联系人邮箱 |
| `contact_name` | `string` | 否 | 否 | — | 联系人姓名 |
| `contact_phone` | `string` | 否 | 否 | — | 联系人电话 |
| `department` | `string` | 否 | 否 | — | 所属部门 |
| `description` | `string` | 否 | 否 | — | 用途说明 |
| `labels` | `object` | 否 | 否 | — | 用于检索和归类的标签 |
| `metadata` | `object` | 否 | 否 | — | 面向外部集成的非敏感扩展元数据 |
| `name` | `string` | 否 | 否 | — | 展示名称 |
| `organization` | `string` | 否 | 否 | — | 所属机构 |
| `status` | `string` | 否 | 否 | — | 资源状态：active 或 disabled |

## 成功响应

### HTTP 200

返回更新后的机密信息元数据

```json
{
  "data": {
    "item": {
      "contact_email": "owner@example.com",
      "contact_name": "张三",
      "contact_phone": "13800000000",
      "created_at": "2026-08-01T08:00:00Z",
      "created_by": "app_orders",
      "current_version": 3,
      "department": "平台工程部",
      "description": "生产订单服务连接数据库使用",
      "labels": {
        "environment": "production"
      },
      "metadata": {
        "ticket": "SEC-1001"
      },
      "name": "订单数据库凭据",
      "organization": "示例科技",
      "path": "production/orders/database",
      "status": "active",
      "updated_at": "2026-08-02T08:00:00Z",
      "updated_by": "app_orders",
      "version": 2
    }
  },
  "error": null,
  "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910"
}
```

## 失败响应

按 HTTP status 与 `error.code` 区分失败原因；响应始终使用统一 envelope。

### HTTP 400 · `invalid_request`

请求参数或 JSON 请求体无效

```json
{
  "data": null,
  "error": {
    "code": "invalid_request",
    "details": {},
    "message": "请求参数或 JSON 请求体无效"
  },
  "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910"
}
```

### HTTP 400 · `not_initialized`

系统尚未初始化

```json
{
  "data": null,
  "error": {
    "code": "not_initialized",
    "details": {},
    "message": "系统尚未初始化"
  },
  "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910"
}
```

### HTTP 401 · `replayed_request`

签名请求的 nonce 已被使用

```json
{
  "data": null,
  "error": {
    "code": "replayed_request",
    "details": {},
    "message": "签名请求的 nonce 已被使用"
  },
  "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910"
}
```

### HTTP 401 · `unauthorized`

App ID、App Secret 或签名无效，或者凭据已过期

```json
{
  "data": null,
  "error": {
    "code": "unauthorized",
    "details": {},
    "message": "App ID、App Secret 或签名无效，或者凭据已过期"
  },
  "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910"
}
```

### HTTP 403 · `forbidden`

App 没有访问目标资源所需的权限

```json
{
  "data": null,
  "error": {
    "code": "forbidden",
    "details": {},
    "message": "App 没有访问目标资源所需的权限"
  },
  "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910"
}
```

### HTTP 404 · `not_found`

机密信息不存在

```json
{
  "data": null,
  "error": {
    "code": "not_found",
    "details": {},
    "message": "机密信息不存在"
  },
  "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910"
}
```

### HTTP 409 · `conflict`

机密信息路径或当前状态发生冲突

```json
{
  "data": null,
  "error": {
    "code": "conflict",
    "details": {},
    "message": "机密信息路径或当前状态发生冲突"
  },
  "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910"
}
```

### HTTP 413 · `request_body_too_large`

请求体超过服务端限制

```json
{
  "data": null,
  "error": {
    "code": "request_body_too_large",
    "details": {},
    "message": "请求体超过服务端限制"
  },
  "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910"
}
```

### HTTP 423 · `sealed`

系统处于封印状态

```json
{
  "data": null,
  "error": {
    "code": "sealed",
    "details": {},
    "message": "系统处于封印状态"
  },
  "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910"
}
```

### HTTP 500 · `internal_error`

服务端无法完成请求

```json
{
  "data": null,
  "error": {
    "code": "internal_error",
    "details": {},
    "message": "服务端无法完成请求"
  },
  "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910"
}
```

### HTTP 503 · `leader_unavailable`

高可用集群的 Leader 暂不可用

```json
{
  "data": null,
  "error": {
    "code": "leader_unavailable",
    "details": {},
    "message": "高可用集群的 Leader 暂不可用"
  },
  "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910"
}
```

### HTTP 503 · `maintenance_mode`

系统处于维护模式

```json
{
  "data": null,
  "error": {
    "code": "maintenance_mode",
    "details": {},
    "message": "系统处于维护模式"
  },
  "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910"
}
```

Source: http://127.0.0.1:4321/docs/api/secret/patch-under-resource-path/