本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 定义自定义元数据架构
<a name="registry-custom-metadata-schema"></a>

**迁移现已开放**  
 Amazon 代理注册表已在新`agent-registry`命名空间下启动。2026 年 10 月 30 日将停止对公共预览版`bedrock-agentcore`命名空间的支持。有关迁移说明，请参阅[注册表迁移综合指南](registry-faq.md)。

使用自定义元数据将您自己的字段添加到注册表中的记录中，例如所属团队、审核状态或数据分类。您只需在注册表上定义字段。然后，在创建或编辑记录时，将其填入。

您可以定义两种字段：
+  **常用属性** — 适用于每种记录类型的记录的字段，这些字段在默认架构中定义（`defaultSchema`在 API 中）。记录是否必须有值取决于该字段的 “**必填**” 设置。
+  **记录类型字段** — 一种记录类型的额外字段，例如模型上下文协议 (MCP) 服务器或代理。有关记录类型的列表，请参阅[支持的记录类型和描述符](registry-supported-record-types.md)。

记录可以带有公共属性以及与其记录类型对应的字段。对于要在所有记录中筛选或报告的任何内容，请使用通用属性。

## 示例
<a name="registry-custom-metadata-schema-example"></a>

此注册表中的每条记录都需要一个所有者，并且可以进行数据分类。代理记录还需要模型族和分类，可以归类为`restricted`。

常见属性：

```
{
  "type": "object",
  "properties": {
    "owner": {"type": "string"},
    "dataClassification": {"type": "string", "enum": ["public", "internal", "confidential"]}
  },
  "required": ["owner"]
}
```

字段为`AGENT`：

```
{
  "type": "object",
  "properties": {
    "modelFamily": {"type": "string"},
    "dataClassification": {"type": "string", "enum": ["public", "internal", "confidential", "restricted"]}
  },
  "required": ["modelFamily", "dataClassification"]
}
```

然后，记录可以携带：


| 记录类型 | 字段 | 必填 | 的允许值 `dataClassification`  | 
| --- | --- | --- | --- | 
| 座席 |  `owner`, `modelFamily`, `dataClassification`  | 全部三个 |  `public`, `internal`, `confidential`, `restricted`  | 
| 所有其他类型 |  `owner`, `dataClassification`  |  `owner`  |  `public`, `internal`, `confidential`  | 

代理字段不会重复`owner`，因为每种记录类型都已获得通用属性。他们确实会重复`dataClassification`。这使得该字段成为代理的必填字段，并允许附加值`restricted`。要像这样更改一种记录类型的通用属性，请将其包含在该记录类型的字段中，其类型和所有允许值都相同。您可以添加允许的值并将其设为必填值。

## 定义架构
<a name="registry-custom-metadata-schema-define"></a>

### 控制台
<a name="registry-custom-metadata-schema-define-console"></a>

1. 在 [Amazon Agent Registry 控制台中打开注册表](https://console.amazonaws.cn/agent-registry/home?region=us-east-1#)详细信息页面。

1. 在**自定义元数据架构**部分中，选择**管理架构**。

1. 在 “**常用属性**” 下，为每条记录应有的每个字段选择 “**添加**字段”，然后输入：

   1.  **名称**-以字母开头。字母`_`、数字和`-`。最多 64 个字符。

   1.  **类型**-**文本**、**枚举**（允许值的列表）、**URL** 或**布尔值**。

   1.  **允许的值**-对于 E **num** 字段，输入记录可以使用的每个值：1 到 25 个值，每个值最多 64 个字符。

   1.  **必填项**-是否必须提供值。

1. 要为一种记录类型添加字段，请选择记录类型并选择**添加字段**。列出了常用属性以供参考。要为该记录类型设置一个必填值或允许更多值，请按原地对其进行编辑。

1. 选择**保存更改**。

要将架构编辑为 JSON，请从**表单**切换到 **JSON**。每个架构（公共属性或一种记录类型的字段）都是一个 JSON 架构文档，与[示例](#registry-custom-metadata-schema-example)中的文件类似。

### Amazon CLI
<a name="registry-custom-metadata-schema-define-cli"></a>

在 API 中，常用属性是`defaultSchema`，每种记录类型的字段都是中的一个条目`recordTypeSchemaOverrides`。每个架构都是一个 JSON 字符串。

将[示例](#registry-custom-metadata-schema-example)中的两个架构另存为`common.json`和`agent.json`，然后创建注册表：

```
jq -n --rawfile common common.json --rawfile agent agent.json \
  '{defaultSchema: $common, recordTypeSchemaOverrides: [{recordType: "AGENT", schema: $agent}]}' \
  > schema-config.json

aws agent-registry-control create-registry \
  --name "my-registry" \
  --custom-metadata-schema-configuration file://schema-config.json \
  --region us-east-1
```

要稍后更改架构，请编辑架构文件，重新生成配置，然后将其封装后发送`optionalValue`。此示例向常用属性添加了一个`team`字段：

```
jq '.properties.team = {"type": "string"}' common.json > common.tmp && mv common.tmp common.json

jq -n --rawfile common common.json --rawfile agent agent.json \
  '{optionalValue: {defaultSchema: $common, recordTypeSchemaOverrides: [{recordType: "AGENT", schema: $agent}]}}' \
  > schema-update.json

aws agent-registry-control update-registry \
  --registry-id "<registryId>" \
  --custom-metadata-schema-configuration file://schema-update.json \
  --region us-east-1
```

### Amazon SDK
<a name="registry-custom-metadata-schema-define-sdk"></a>

```
import boto3
import json

client = boto3.client('agent-registry-control')

common_attributes = {
    "type": "object",
    "properties": {
        "owner": {"type": "string"},
        "dataClassification": {"type": "string", "enum": ["public", "internal", "confidential"]}
    },
    "required": ["owner"]
}

agent_fields = {
    "type": "object",
    "properties": {
        "modelFamily": {"type": "string"},
        "dataClassification": {
            "type": "string",
            "enum": ["public", "internal", "confidential", "restricted"]
        }
    },
    "required": ["modelFamily", "dataClassification"]
}

response = client.create_registry(
    name='my-registry',
    customMetadataSchemaConfiguration={
        'defaultSchema': json.dumps(common_attributes),
        'recordTypeSchemaOverrides': [
            {'recordType': 'AGENT', 'schema': json.dumps(agent_fields)}
        ]
    }
)
print(f"Registry ARN: {response['registryArn']}")
```

要稍后更改架构，请发送包含以下内容的完整新配置`optionalValue`：

```
common_attributes["properties"]["team"] = {"type": "string"}

client.update_registry(
    registryId='<registryId>',
    customMetadataSchemaConfiguration={
        'optionalValue': {
            'defaultSchema': json.dumps(common_attributes),
            'recordTypeSchemaOverrides': [
                {'recordType': 'AGENT', 'schema': json.dumps(agent_fields)}
            ]
        }
    }
)
```

## 更改架构
<a name="registry-custom-metadata-schema-change"></a>

更新会替换整个架构，因此请包括要保留的每个字段和记录类型。

您可以随时进行以下更改：
+ 向常用属性或记录类型添加字段。
+ 向 Enum 字段添加允许的值。如果您在记录类型重复的公共属性中添加一个属性，则也可以在同一个更新中将其添加到该记录类型中。
+ 将可选字段设为必填字段。
+ 将字段从记录类型移到公共属性中，这些属性具有相同的类型、至少相同的允许值和相同的必需设置。然后，该字段适用于每种记录类型，如果需要，则每种记录类型都必须有一个值。如果记录类型没有自己的左侧字段，则可以将其删除。

您无法进行以下更改：
+ 重命名字段。
+ 移除字段。唯一的例外是将记录类型的字段移到公共属性中。
+ 更改字段的类型，例如从 “文本” 更改为 “枚举”。
+ 移除允许的值。
+ 将必填字段设为可选。
+ 移除常用属性。
+ 从注册表中移除自定义元数据架构。一旦注册表有了架构，它就会保留一个架构。

更新架构时，现有记录不会更改。如果记录不再与之匹配，例如因为您设置了必填字段，则会报告为`NON_COMPLIANT`中`customMetadataSchemaComplianceStatus`并保持其批准状态。在下次提交其自定义元数据以供批准之前，请对其进行更新。

## 查看架构
<a name="registry-custom-metadata-schema-view"></a>

 **控制台**-在注册表详细信息页面上，“**自定义元数据架构**” 部分为每种记录类型都有一个选项卡，其中包含其记录可以包含的字段。

 ** Amazon CLI** 

```
aws agent-registry-control get-registry \
  --registry-id "<registryId>" \
  --region us-east-1 \
  --output json | jq '.customMetadataSchemaConfiguration'
```

 ** Amazon SDK** 

```
import boto3

client = boto3.client('agent-registry-control')

registry = client.get_registry(registryId='<registryId>')
print(registry['customMetadataSchemaConfiguration'])
```

## 架构规则和限制
<a name="registry-custom-metadata-schema-constraints"></a>
+ 每个字段都是文本 (`{"type":"string"}`)、枚举 (`{"type":"string","enum":[…​]}`)、URL (`{"type":"string","format":"uri"}`) 或布尔值 (`{"type":"boolean"}`)。字段不能嵌套或使用其他关键字，例如`default`或`pattern`。
+ 一个字段在架构中的任何地方都具有相同的字段类型（文本、枚举、URL 或布尔值）。其允许值可能因记录类型而异。
+ 字段名称不能仅在大小写上有所不同，例如`owner`和`Owner`。
+ 每个架构都是一个 JSON 对象`"type": "object"`，其中至少有一个字段`properties`。它也可以有`required``title`、和`description`，但不是`$schema`。
+ 架构的`required`列表只能命名同一架构中的字段。要要求一种记录类型使用通用属性，请在该记录类型的字段中重复该字段。

下表列出了架构限制。


| 限制 | 值 | 
| --- | --- | 
| 记录类型可以携带的字段，包括常用属性（重复字段计数一次） | 30 | 
| 通用 属性 | 30 个字段 | 
| 每个 Enum 字段允许的值数 | 1 - 25 | 
| 允许的值长度 | 64 个字符 | 
| 字段名长度 | 64 个字符 | 
| 架构 `title`  | 64 个字符 | 
| 架构 `description`  | 256 个字符 | 
| 一个架构（常用属性或一种记录类型的字段） | 16384 个字符 | 
| 整个架构配置 | 128 KB | 
| 每种记录类型的架构 | 1 | 

有关值的限制，请参阅为[记录设置自定义元数据值](registry-custom-metadata-values.md)中的[约束条件](registry-custom-metadata-values.md#registry-custom-metadata-values-constraints)。

## 相关信息
<a name="registry-custom-metadata-schema-related"></a>
+  [为记录设置自定义元数据值](registry-custom-metadata-values.md) 
+  [搜索注册表记录](registry-search-records.md)-按自定义元数据值筛选结果
+  [支持的记录类型和描述符](registry-supported-record-types.md) 
+  [创建和管理注册表](registry-create-manage.md)