# Gerenciamento de anotações
<a name="annotations-managing"></a>

Você pode adicionar, recuperar e excluir anotações em objetos do Amazon S3 usando os SDKs do Console de gerenciamento da AWS, da AWS CLI ou da AWS. As seções a seguir descrevem como realizar cada operação.

## Adição ou atualização de uma anotação
<a name="annotations-managing-add"></a>

Você pode adicionar uma nova anotação a um objeto ou atualizar uma anotação existente substituindo a carga útil.

### Usar o console do S3
<a name="annotations-managing-add-console"></a>

**Para adicionar uma anotação a um objeto**

1. Faça login no Console de gerenciamento da AWS e abra o console do Amazon S3 em [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/).

1. Na lista **Buckets**, escolha o nome do bucket que contém o objeto.

1. Na lista **Objetos**, escolha o nome do objeto que você deseja anotar.

1. Escolha a guia **Properties (Propriedades)**.

1. Role até a seção **Anotações** e escolha **Adicionar anotação**.

1. Em **Nome**, insira um nome para a anotação (por exemplo, `ml.sentiment`). Os nomes devem ter de 1 a 512 bytes e podem conter letras, dígitos, sublinhados, pontos e hífens Unicode. Os nomes não podem começar com `aws` ou `s3`.

1. Selecione **Escolher arquivo** para carregar o conteúdo da anotação. O arquivo deve ser codificável em UTF-8 e ter até 1 MB de tamanho.

**Para concluir a anotação**

1. (Opcional) Em **Somas de verificação**, escolha um algoritmo de soma de verificação.

1. Escolha **Adicionar anotação**.

**nota**  
Para visualizar o conteúdo de uma anotação após a criação, faça o download da anotação. O console do S3 não exibe conteúdo de anotação em linha.

### Como usar o AWS CLI
<a name="annotations-managing-add-cli"></a>

Para adicionar ou atualizar uma anotação em um objeto, use o comando `put-object-annotation`. O parâmetro `--annotation-payload` aceita um caminho de arquivo.

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

Para gravar a anotação somente se o objeto não tiver sido substituído desde a última leitura, especifique o parâmetro `--object-if-match` com a ETag atual do objeto.

```
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\""
```

### Usar SDKs da AWS
<a name="annotations-managing-add-sdk"></a>

O exemplo a seguir usa o SDK da AWS para Python (Boto3) para adicionar uma anotação a um objeto.

```
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')
)
```

## Recuperação de anotações
<a name="annotations-managing-get"></a>

Você pode recuperar uma anotação específica ou listar todas as anotações em um objeto.

### Usar o console do S3
<a name="annotations-managing-get-console"></a>

**Para recuperar uma anotação**

1. Faça login no Console de gerenciamento da AWS e abra o console do Amazon S3 em [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/).

1. Na lista **Buckets**, escolha o nome do bucket que contém o objeto.

1. Na lista **Objetos** , escolha o nome do objeto.

1. Escolha a guia **Propriedades** e vá até a seção **Anotações**.

1. Para visualizar o conteúdo da anotação, escolha **Download** ao lado do nome da anotação.

### Como usar o AWS CLI
<a name="annotations-managing-get-cli"></a>

Para recuperar uma anotação específica, use o comando `get-object-annotation`.

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

Para listar todas as anotações em um objeto, use o comando `list-object-annotations`.

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

### Usar SDKs da AWS
<a name="annotations-managing-get-sdk"></a>

O exemplo a seguir usa o SDK da AWS para Python (Boto3) para recuperar e listar anotações.

```
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")
```

## Exclusão de anotações
<a name="annotations-managing-delete"></a>

Você pode excluir uma anotação específica de um objeto. A exclusão de anotações é permanente e não pode ser desfeita.

### Usar o console do S3
<a name="annotations-managing-delete-console"></a>

**Para excluir uma anotação**

1. Faça login no Console de gerenciamento da AWS e abra o console do Amazon S3 em [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/).

1. Na lista **Buckets**, escolha o nome do bucket que contém o objeto.

1. Na lista **Objetos** , escolha o nome do objeto.

1. Escolha a guia **Propriedades** e vá até a seção **Anotações**.

1. Selecione a anotação que você deseja excluir.

1. Escolha **Excluir** e confirme a exclusão.

### Como usar o AWS CLI
<a name="annotations-managing-delete-cli"></a>

Para excluir uma anotação específica, use o comando `delete-object-annotation`.

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

### Usar SDKs da AWS
<a name="annotations-managing-delete-sdk"></a>

O exemplo a seguir usa o SDK da AWS para Python (Boto3) para excluir uma anotação.

```
import boto3

s3 = boto3.client('s3')

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