# Trabalhar com dados de chave-valor
Este tópico descreve como adicionar pares de chave-valor a um armazenamento de chave-valor existente. Para incluir pares de chave-valor ao criar inicialmente armazenamentos de chave-valor, consulte [Criar um armazenamento de chave-valor](kvs-with-functions-create.md).
**Topics**
+ [Trabalhar com pares de chave-valor (console)](#kvs-with-functions-kvp-using-console)
+ [Sobre o KeyValueStore do CloudFront](#kvs-with-functions-api-describe)
+ [Trabalhar com pares de chave-valor (AWS CLI)](#work-with-kvs-cli-keys)
+ [Trabalhar com pares de chave-valor (API)](#kvs-with-functions-kvp-using-api)
## Trabalhar com pares de chave-valor (console)
É possível usar o console do CloudFront para trabalhar com os seus pares de chave-valor.
**Como trabalhar com pares de chave-valor**
1. Faça login no Console de gerenciamento da AWS e abra a página **Functions** (Funções) no console do CloudFront em [https://console.aws.amazon.com/cloudfront/v4/home#/functions](https://console.aws.amazon.com/cloudfront/v4/home#/functions).
1. Selecione a guia **KeyValueStores**.
1. Selecione o armazenamento de chave-valor que deseja alterar.
1. Na seção **Pares de chave-valor**, selecione **Editar**.
1. É possível adicionar um par de chave-valor, excluir um par de chave-valor ou alterar o valor de um par existente.
1. Ao concluir, escolha **Salvar alterações**.
## Sobre o KeyValueStore do CloudFront
**dica**
A API KeyValueStore do CloudFront é um serviço global que usa o Signature Version 4A (SigV4A) para autenticação. O uso de credenciais temporárias com o SigV4A requer tokens de sessão da versão 2. Para obter mais informações, consulte [Usar credenciais temporárias com a API KeyValueStore do CloudFront](cloudfront-function-restrictions.md#regional-endpoint-for-key-value-store).
Se você estiver usando a AWS Command Line Interface (AWS CLI) ou seu próprio código para chamar a API KeyValueStore do CloudFront, consulte as seções a seguir.
Quando você trabalha com um armazenamento de chave-valor e seus pares de chave-valor, o serviço que você chama depende do seu caso de uso:
+ Para trabalhar com pares de chave-valor em um armazenamento de chave-valor *existente*, use o serviço KeyValueStore do CloudFront.
+ Para incluir pares de chave-valor no armazenamento de chave-valor ao criá-lo *inicialmente*, use o serviço CloudFront.
Tanto a API do CloudFront quanto a API KeyValueStore do CloudFront têm uma operação `DescribeKeyValueStore`. Você pode chamá-los por diferentes motivos. Para entender as diferenças, consulte a tabela a seguir.
| | API DescribeKeyValueStore do CloudFront | API KeyValueStore DescribeKeyValueStore do CloudFront |
| --- | --- | --- |
| Dados sobre o armazenamento de chave-valor | Retorna dados, como o status e a data em que o próprio armazenamento de chave-valor foi modificado pela última vez. | Retorna dados sobre o *conteúdo* do recurso de armazenamento: os pares de chave-valor no armazenamento e o tamanho do conteúdo. |
| Dados que identificam o armazenamento de chave-valor | Exibe uma `ETag`, o UUID e o ARN do armazenamento de chave-valor. | Exibe uma `ETag` e o ARN do armazenamento de chave-valor. |
**Observações**
Cada operação DescribeKeyValueStore exibe uma `ETag` *diferente*. As `ETags` não são intercambiáveis.
Ao chamar uma operação de API para concluir uma ação, é necessário especificar a `ETag` da API apropriada. Por exemplo, na operação [DeleteKey](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_kvs_DeleteKey.html) do KeyValueStore do CloudFront, é possível especificar a `ETag` exibida da operação [https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_kvs_DescribeKeyValueStore.html](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_kvs_DescribeKeyValueStore.html) do KeyValueStore do CloudFront.
Quando você invoca CloudFront Functions usando o KeyValueStore do CloudFront, os valores no armazenamento de chave-valor não são atualizados nem alterados durante a invocação da função. As atualizações são processadas entre as invocações de uma função.
## Trabalhar com pares de chave-valor (AWS CLI)
É possível executar os comandos da AWS Command Line Interface a seguir no KeyValueStore do CloudFront.
**Contents**
+ [Listar pares de chave-valor](#kvs-cli-list-keys)
+ [Obter pares de chave-valor](#kvs-cli-get-keys)
+ [Descrever um armazenamento de chave-valor](#kvs-cli-describe-keys)
+ [Criar um par de chave-valor](#kvs-cli-create-keys)
+ [Excluir um par de chave-valor](#kvs-cli-delete-keys)
+ [Atualizar pares de chave-valor](#kvs-cli-update-key)
### Listar pares de chave-valor
Para listar pares de chave-valor no armazenamento de chave-valor, execute o comando a seguir.
```
aws cloudfront-keyvaluestore list-keys \
--kvs-arn=arn:aws:cloudfront::123456789012:key-value-store/37435e19-c205-4271-9e5c-example
```
**Resposta**
```
{
"Items": [
{
"Key": "key1",
"Value": "value1"
}
]
}
```
### Obter pares de chave-valor
Para obter um par de chave-valor no armazenamento de chave-valor, execute o comando a seguir.
```
aws cloudfront-keyvaluestore get-key \
--key=key1 \
--kvs-arn=arn:aws:cloudfront::123456789012:key-value-store/37435e19-c205-4271-9e5c-example
```
**Resposta**
```
{
"Key": "key1",
"Value": "value1",
"ItemCount": 1,
"TotalSizeInBytes": 11
}
```
### Descrever um armazenamento de chave-valor
Para descrever um armazenamento de chave-valor, execute o comando a seguir.
```
aws cloudfront-keyvaluestore describe-key-value-store \
--kvs-arn=arn:aws:cloudfront::123456789012:key-value-store/37435e19-c205-4271-9e5c-example
```
**Resposta**
```
{
"ETag": "KV1F83G8C2ARO7P",
"ItemCount": 1,
"TotalSizeInBytes": 11,
"KvsARN": "arn:aws:cloudfront::123456789012:key-value-store/37435e19-c205-4271-9e5c-example",
"Created": "2024-05-08T07:48:45.381000-07:00",
"LastModified": "2024-08-05T13:50:58.843000-07:00",
"Status": "READY"
}
```
### Criar um par de chave-valor
Para criar um par de chave-valor no armazenamento de chave-valor, execute o comando a seguir.
```
aws cloudfront-keyvaluestore put-key \
--if-match=KV1PA6795UKMFR9 \
--key=key2 \
--value=value2 \
--kvs-arn=arn:aws:cloudfront::123456789012:key-value-store/37435e19-c205-4271-9e5c-example
```
**Resposta**
```
{
"ETag": "KV13V1IB3VIYZZH",
"ItemCount": 3,
"TotalSizeInBytes": 31
}
```
### Excluir um par de chave-valor
Para excluir um par de chave-valor, execute o comando a seguir.
```
aws cloudfront-keyvaluestore delete-key \
--if-match=KV13V1IB3VIYZZH \
--key=key1 \
--kvs-arn=arn:aws:cloudfront::123456789012:key-value-store/37435e19-c205-4271-9e5c-example
```
**Output**
```
{
"ETag": "KV1VC38T7YXB528",
"ItemCount": 2,
"TotalSizeInBytes": 22
}
```
### Atualizar pares de chave-valor
É possível usar o comando `update-keys` para atualizar mais de um par de chave-valor. Por exemplo, para excluir um par de chave-valor e criar outro, execute o comando a seguir.
```
aws cloudfront-keyvaluestore update-keys \
--if-match=KV2EUQ1WTGCTBG2 \
--kvs-arn=arn:aws:cloudfront::123456789012:key-value-store/37435e19-c205-4271-9e5c-example \
--deletes '[{"Key":"key2"}]' \
--puts '[{"Key":"key3","Value":"value3"}]'
```
**Resposta**
```
{
"ETag": "KV3AEGXETSR30VB",
"ItemCount": 3,
"TotalSizeInBytes": 28
}
```
## Trabalhar com pares de chave-valor (API)
Siga esta seção para trabalhar com os pares de chave-valor de forma programática.
**Contents**
+ [Obter uma referência a um armazenamento de chave-valor](#kvs-with-functions-api-ref)
+ [Alterar pares de chave-valor em um armazenamento de chave-valor](#kvs-with-functions-api-actions)
+ [Exemplo de código de KeyValueStore do CloudFront](#example-code-key-value-store)
### Obter uma referência a um armazenamento de chave-valor
Ao usar a API KeyValueStore do CloudFront para chamar uma operação de gravação, é necessário especificar o ARN e a `ETag` do armazenamento de chave-valor. Para obter esses dados, faça o seguinte:
**Como obter uma referência a um armazenamento de chave-valor**
1. Use a operação de API [https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_ListKeyValueStores.html](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_ListKeyValueStores.html) para obter uma lista de armazenamentos de chave-valor. Encontre o armazenamento de chave-valor que deseja alterar.
1. Use a [operação de API CloudFrontKeyValueStore DescribeKeyValueStore](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_kvs_DescribeKeyValueStore.html) e especifique o armazenamento de chave-valor da etapa anterior.
A resposta inclui o ARN e a `ETag` do armazenamento de chave-valor.
+ O ARN inclui o número da Conta da AWS, o `key-value-store` constante e o UUID, como o seguinte exemplo:
`arn:aws:cloudfront::123456789012:key-value-store/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111`
+ Uma `ETag` que se parece com o seguinte exemplo:
`ETVABCEXAMPLE2`
### Alterar pares de chave-valor em um armazenamento de chave-valor
É possível especificar o armazenamento de chave-valor que contém o par de chave-valor que você deseja atualizar.
Veja as seguintes operações da API KeyValueStore do CloudFront:
+ [CloudFrontKeyValueStore DeleteKey](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_kvs_DeleteKey.html): exclui um par de chave-valor
+ [CloudFrontKeyValueStore GetKey](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_kvs_GetKey.html): retorna um par de chave-valor
+ [CloudFrontKeyValueStore ListKeys](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_kvs_ListKeys.html): retorna uma lista de pares de chave-valor
+ [CloudFrontKeyValueStore PutKey](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_kvs_PutKey.html): é possível realizar as seguintes tarefar:
+ Criar um par de chave-valor em um armazenamento de chave-valor especificando um novo nome e valor da chave.
+ Defina um valor diferente em um par de chave-valor especificando um nome de chave existente e um novo valor de chave.
+ [CloudFrontKeyValueStore UpdateKeys](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_kvs_UpdateKeys.html): é possível executar uma ou mais das seguintes ações em uma operação de tudo ou nada:
+ Excluir um ou mais pares de chave-valor.
+ Criar um ou mais pares de chave-valor.
+ Definir um valor diferente em um ou mais pares de chave-valor existentes.
### Exemplo de código de KeyValueStore do CloudFront
**Example**
O código a seguir mostra como chamar a operação de API `DescribeKeyValueStore` para um armazenamento de chave-valor.
```
const {
CloudFrontKeyValueStoreClient,
DescribeKeyValueStoreCommand,
} = require("@aws-sdk/client-cloudfront-keyvaluestore");
require("@aws-sdk/signature-v4-crt");
(async () => {
try {
const client = new CloudFrontKeyValueStoreClient({
region: "us-east-1"
});
const input = {
KvsARN: "arn:aws:cloudfront::123456789012:key-value-store/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
};
const command = new DescribeKeyValueStoreCommand(input);
const response = await client.send(command);
} catch (e) {
console.log(e);
}
})();
```