# 管理注释
<a name="annotations-managing"></a>

您可以使用 Amazon Web Services 管理控制台、Amazon CLI 或 Amazon SDK 在 Amazon S3 对象上添加、检索和删除注释。以下各节描述如何执行每个操作。

## 添加或更新注释
<a name="annotations-managing-add"></a>

您可以向对象添加新注释，也可以通过替换其有效载荷来更新现有注释。

### 使用 S3 控制台
<a name="annotations-managing-add-console"></a>

**向对象添加注释**

1. 登录到 Amazon Web Services 管理控制台，然后通过以下网址打开 Amazon S3 控制台：[https://console.aws.amazon.com/s3/](https://console.amazonaws.cn/s3/)。

1. 在 **Bucket（存储桶）**列表中，请选择包含对象的存储桶的名称。

1. 在**对象**列表中，选择要添加注释的对象的名称。

1. 选择**属性**选项卡。

1. 滚动到**注释**部分，然后选择**添加注释**。

1. 对于**名称**，输入注释的名称（例如 `ml.sentiment`）。名称必须为 1–512 字节，可以包含 Unicode 字母、数字、下划线、句点和连字符。名称不能以 `aws` 或 `s3` 开头。

1. 选择**选择文件**以上传注释内容。该文件必须可进行 UTF-8 编码且大小不超过 1 MB。

**完成注释**

1. （可选）在**校验和**下，选择校验和算法。

1. 选择**添加注释**。

**注意**  
要在创建注释后查看其内容，必须下载注释。S3 控制台不以内联方式显示注释内容。

### 使用 Amazon CLI
<a name="annotations-managing-add-cli"></a>

要在对象上添加或更新注释，请使用 `put-object-annotation` 命令。`--annotation-payload` 参数接受文件路径。

```
aws s3api put-object-annotation \
    --bucket amzn-s3-demo-bucket \
    --key myDocument.pdf \
    --annotation-name "ml.sentiment" \
    --annotation-payload /tmp/sentiment.json
```

要仅在自上次读取对象以来对象未被覆盖的情况下编写注释，请使用该对象的当前 ETag 指定 `--object-if-match` 参数。

```
aws s3api put-object-annotation \
    --bucket amzn-s3-demo-bucket \
    --key myDocument.pdf \
    --annotation-name "ml.sentiment" \
    --annotation-payload /tmp/sentiment.json \
    --object-if-match "\"d6eb32081c822ed572b70567826d9d9d\""
```

### 使用 Amazon SDK
<a name="annotations-managing-add-sdk"></a>

以下示例使用适用于 Python 的 Amazon SDK（Boto3）向对象添加注释。

```
import boto3
import json

s3 = boto3.client('s3')

s3.put_object_annotation(
    Bucket='amzn-s3-demo-bucket',
    Key='myDocument.pdf',
    AnnotationName='ml.sentiment',
    AnnotationPayload=json.dumps({
        'score': 0.95,
        'label': 'positive',
        'model': 'sentiment-v3'
    }).encode('utf-8')
)
```

## 检索注释
<a name="annotations-managing-get"></a>

您可以检索特定的注释或列出对象上的所有注释。

### 使用 S3 控制台
<a name="annotations-managing-get-console"></a>

**检索注释**

1. 登录到 Amazon Web Services 管理控制台，然后通过以下网址打开 Amazon S3 控制台：[https://console.aws.amazon.com/s3/](https://console.amazonaws.cn/s3/)。

1. 在**存储桶**列表中，请选择包含对象的存储桶的名称。

1. 在 **Objects**（对象）列表中，请选择对象的名称。

1. 选择**属性**选项卡，然后滚动到**注释**部分。

1. 要查看注释内容，请选择注释名称旁边的**下载**。

### 使用 Amazon CLI
<a name="annotations-managing-get-cli"></a>

要检索特定的注释，请使用 `get-object-annotation` 命令。

```
aws s3api get-object-annotation \
    --bucket amzn-s3-demo-bucket \
    --key myDocument.pdf \
    --annotation-name "ml.sentiment" \
    output.json
```

要列出对象上的所有注释，请使用 `list-object-annotations` 命令。

```
aws s3api list-object-annotations \
    --bucket amzn-s3-demo-bucket \
    --key myDocument.pdf
```

### 使用 Amazon SDK
<a name="annotations-managing-get-sdk"></a>

以下示例使用适用于 Python 的 Amazon SDK（Boto3）来检索和列出注释。

```
import boto3
import json

s3 = boto3.client('s3')

# Retrieve a specific annotation
response = s3.get_object_annotation(
    Bucket='amzn-s3-demo-bucket',
    Key='myDocument.pdf',
    AnnotationName='ml.sentiment'
)
content = json.loads(response['AnnotationPayload'].read())

# List all annotations on an object
response = s3.list_object_annotations(
    Bucket='amzn-s3-demo-bucket',
    Key='myDocument.pdf'
)
for annotation in response['Annotations']:
    print(f"{annotation['AnnotationName']} - {annotation['Size']} bytes")
```

## 删除注释
<a name="annotations-managing-delete"></a>

您可以从对象中删除特定的注释。注释删除是永久性的，无法撤消。

### 使用 S3 控制台
<a name="annotations-managing-delete-console"></a>

**删除注释**

1. 登录到 Amazon Web Services 管理控制台，然后通过以下网址打开 Amazon S3 控制台：[https://console.aws.amazon.com/s3/](https://console.amazonaws.cn/s3/)。

1. 在**存储桶**列表中，请选择包含对象的存储桶的名称。

1. 在 **Objects**（对象）列表中，请选择对象的名称。

1. 选择**属性**选项卡，然后滚动到**注释**部分。

1. 选择要删除的注释。

1. 选择**删除**，然后确认删除。

### 使用 Amazon CLI
<a name="annotations-managing-delete-cli"></a>

要删除特定的注释，请使用 `delete-object-annotation` 命令。

```
aws s3api delete-object-annotation \
    --bucket amzn-s3-demo-bucket \
    --key myDocument.pdf \
    --annotation-name "ml.sentiment"
```

### 使用 Amazon SDK
<a name="annotations-managing-delete-sdk"></a>

以下示例使用适用于 Python 的 Amazon SDK（Boto3）来删除注释。

```
import boto3

s3 = boto3.client('s3')

s3.delete_object_annotation(
    Bucket='amzn-s3-demo-bucket',
    Key='myDocument.pdf',
    AnnotationName='ml.sentiment'
)
```