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

# 为记录设置自定义元数据值
<a name="registry-custom-metadata-values"></a>

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

当注册表具有自定义元数据架构时，您可以在创建或编辑记录时填写其字段。记录可以携带注册表的公共属性（在其默认架构中定义）以及为其记录类型定义的任何字段。要设置字段，请参阅[定义自定义元数据架构](registry-custom-metadata-schema.md)。

**注意**  
无需自定义元数据即可创建或更新记录。如果您输入任何内容，请填写每个必填字段。在提交记录以供批准之前，所有必填字段都必须有一个值。

## 设定值
<a name="registry-custom-metadata-values-set"></a>

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

1. 在[Amazon 代理](https://console.amazonaws.cn/agent-registry/home?region=us-east-1#)的 “**创建记录****” 或 “编辑记录**” 页面上，选择**记录类型**。如果注册表具有该记录类型的公共属性或字段，则会显示 “**自定义元数据**” 部分。

1. 选择如何输入值：

   1.  **表单**-使用与其类型相匹配的控件为每个字段输入值：文本框、**枚举**字段的下拉列表或**布尔**字段的切换开关。

   1.  **JSON**-直接以 JSON 格式输入值。编辑器会根据架构验证您的输入，并在您的内容旁边显示架构以供参考。

1. 如果您提供任何自定义元数据，请为每个标记为必填的字段输入一个值。文本和 URL 值最多可包含 128 个字符。

1. 选择**创建记录**或**保存更改**。

### Amazon CLI
<a name="registry-custom-metadata-values-set-cli"></a>

这些示例使用定义自定义元数据架构中[示例](registry-custom-metadata-schema.md#registry-custom-metadata-schema-example)中的架构。

```
aws agent-registry-control create-registry-record \
  --registry-id "<registryId>" \
  --name "my-mcp-server" \
  --record-type MCP \
  --descriptors '{"mcpServer": {"data": "{\"name\":\"my/mcp-server\",\"description\":\"My MCP server\",\"version\":\"1.0.0\"}", "dataSchemaVersion": "2025-12-11"}}' \
  --record-version "1.0" \
  --custom-metadata '{"owner": "search-team", "dataClassification": "internal"}' \
  --region us-east-1
```

要更改现有记录上的值，请使用`update-registry-record`。该`--custom-metadata`参数的工作原理如下：
+ 省略它以保留现有值。
+ `{"optionalValue": {…​}}`使用完整的值集通过。它们会替换所有现有值，而不是与它们合并。
+ 传递`{"optionalValue": {}}`以从记录中删除所有自定义元数据值。注册表的架构不会改变。

此示例替换了记录的值：

```
aws agent-registry-control update-registry-record \
  --registry-id "<registryId>" \
  --record-id "<recordId>" \
  --custom-metadata '{"optionalValue": {"owner": "search-team", "dataClassification": "confidential"}}' \
  --region us-east-1
```

### Amazon SDK
<a name="registry-custom-metadata-values-set-sdk"></a>

```
import boto3
import json

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

server_content = json.dumps({
    "name": "my/mcp-server",
    "description": "My MCP server",
    "version": "1.0.0"
})

response = client.create_registry_record(
    registryId='<registryId>',
    name='my-mcp-server',
    recordType='MCP',
    descriptors={
        'mcpServer': {
            'data': server_content,
            'dataSchemaVersion': '2025-12-11'
        }
    },
    recordVersion='1.0',
    customMetadata={'owner': 'search-team', 'dataClassification': 'internal'}
)
print(f"Record ARN: {response['recordArn']}")
```

要稍后更改这些值，请像使用 CLI 一样进行`customMetadata`封装传递。`optionalValue`省略`customMetadata`以保留现有值，或传递`{'optionalValue': {}}`以删除记录的值。

```
client.update_registry_record(
    registryId='<registryId>',
    recordId='<recordId>',
    customMetadata={'optionalValue': {'owner': 'search-team', 'dataClassification': 'confidential'}}
)
```

## 查看值
<a name="registry-custom-metadata-values-view"></a>

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

在记录详细信息页面上，“**自定义元数据**” 部分显示记录的值。布尔值显示为 “是” 或 “否”，URL 值显示为可点击的链接。

### Amazon CLI
<a name="registry-custom-metadata-values-view-cli"></a>

```
aws agent-registry-control get-registry-record \
  --registry-id "<registryId>" \
  --record-id "<recordId>" \
  --region us-east-1
```

### Amazon SDK
<a name="registry-custom-metadata-values-view-sdk"></a>

```
import boto3

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

record = client.get_registry_record(registryId='<registryId>', recordId='<recordId>')
print(record['customMetadata'])
```

## 约束
<a name="registry-custom-metadata-values-constraints"></a>
+ 值必须是字符串或本地布尔值 (`true`/`false`)。数字、数组、对象和 null 都被拒绝。
+ 文本和网址值最多可为 128 个字符。枚举值必须是该字段允许的值之一，每个值最多为 64 个字符。
+ 布尔字段需要原生 JSON 布尔值。字符串`"true"`被拒绝 — 没有类型转换。
+ 每个键都必须是记录可以携带的字段：公共属性或其记录类型的字段之一。其他密钥被拒绝。密钥区分大小写，因此与名为`owner`的字段`Owner`不匹配。
+ 枚举值必须是该字段的允许值之一。如果记录类型重新定义了该字段，则其自己的允许值列表适用。

有关架构本身的限制，请参阅[架构规则和限制](registry-custom-metadata-schema.md#registry-custom-metadata-schema-constraints)。

## 相关信息
<a name="registry-custom-metadata-values-related"></a>
+  [定义自定义元数据架构](registry-custom-metadata-schema.md) 
+  [创建和管理记录](registry-create-manage-records.md) 
+  [支持的记录类型和描述符](registry-supported-record-types.md)