# Amazon CloudFront KeyValueStore
O KeyValueStore do CloudFront é um datastore de valor de chave seguro, global e de baixa latência que permite acesso de leitura por meio do [CloudFront Functions](cloudfront-functions.md), viabilizando uma lógica personalizada avançada nos locais da borda do CloudFront.
Com o KeyValueStore do CloudFront, você faz atualizações no código da função e nos dados associados a uma função, de modo independente uns dos outros. Essa separação simplifica o código da função e facilita a atualização dos dados sem a necessidade de implantar alterações no código.
**nota**
Para usar o CloudFront KeyValueStore, a função do CloudFront deve usar o [runtime 2.0 do JavaScript.](functions-javascript-runtime-20.md)
Veja a seguir o procedimento geral para usar pares de chave-valor:
+ Crie armazenamentos de chave-valor e preencha-os com um conjunto de pares de chave-valor. É possível adicionar seus armazenamentos de chave-valor a um bucket do Amazon S3 ou inseri-los manualmente.
+ Associe os armazenamentos de chave-valor ao CloudFront Functions.
+ No código da função, use o nome da chave para recuperar o valor associado a ela ou para avaliar se existe uma chave. Consulte mais informações sobre o uso de pares de chave-valor no código da função e sobre métodos auxiliares em [Métodos auxiliares para armazenamentos de chave-valor](functions-custom-methods.md).
## Casos de uso
É possível usar pares de chave-valor para os seguintes exemplos:
+ **Regravações ou redirecionamentos de URL**: o par de chave-valor pode conter os URLs regravados ou os URLs de redirecionamento.
+ **Testes A/B e sinalizadores de recursos**: é possível criar uma função para realizar experimentos atribuindo uma porcentagem do tráfego a uma versão específica do site.
+ **Autorização de acesso**: é possível implementar o controle de acesso para permitir ou negar solicitações com base nos critérios definidos e nos dados armazenados no armazenamento de chave-valor.
## Formatos compatíveis de valores
É possível armazenar o valor em um par de chave-valor em qualquer um dos seguintes formatos:
+ String
+ String codificada por bytes
+ JSON
## Segurança
O CloudFront Functions e todos os dados de armazenamento de chave-valor são tratados com segurança, da seguinte forma:
+ O CloudFront criptografa cada armazenamento de chave-valor em repouso e em trânsito (ao ler ou gravar no armazenamento de chave-valor) ao chamar as operações da API [KeyValueStore do CloudFront](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_Operations_Amazon_CloudFront_KeyValueStore.html).
+ Quando a função é executada, o CloudFront descriptografa cada par de chave-valor na memória nos locais da borda do CloudFront.
Para começar a usar o KeyValueStore do CloudFront, consulte os tópicos a seguir.
**Topics**
+ [Casos de uso](#key-value-store-use-cases)
+ [Formatos compatíveis de valores](#key-value-store-supported-formats)
+ [Segurança](#key-value-store-security)
+ [Trabalhar com o armazenamento de chave-valor](kvs-with-functions-kvs.md)
+ [Trabalhar com dados de chave-valor](kvs-with-functions-kvp.md)
+ Para ter mais informações sobre os conceitos básicos do KeyValueStore do CloudFront, consulte a postagem do blog [Apresentação do KeyValueStore do Amazon CloudFront.](https://aws.amazon.com/blogs/aws/introducing-amazon-cloudfront-keyvaluestore-a-low-latency-datastore-for-cloudfront-functions/)AWS
# Trabalhar com o armazenamento de chave-valor
É necessário criar um armazenamento de chave-valor para armazenar os pares de chave-valor que você deseja usar no CloudFront Functions.
Depois de criar os armazenamentos de chave-valor e adicionar os pares de chave-valor, você pode usar os elementos de chave-valor no código da função do CloudFront.
Para começar, consulte os seguintes tópicos:
**Topics**
+ [Criar um armazenamento de chave-valor](kvs-with-functions-create.md)
+ [Associar o armazenamento de chave-valor à função](kvs-with-functions-associate.md)
+ [Atualizar um armazenamento de chave-valor](kvs-with-functions-edit.md)
+ [Obter uma referência a um armazenamento de chave-valor](kvs-with-functions-get-reference.md)
+ [Excluir um armazenamento de chave-valor](kvs-with-functions-delete.md)
+ [Formato de arquivo para pares de chave-valor](kvs-with-functions-create-s3-kvp.md)
**nota**
O JavaScript runtime 2.0 inclui alguns métodos auxiliares para trabalhar com chave-valor no código da função. Para obter mais informações, consulte [Métodos auxiliares para armazenamentos de chave-valor](functions-custom-methods.md).
# Criar um armazenamento de chave-valor
Você pode criar um armazenamento de chave-valor e os pares de chave-valor ao mesmo tempo. Também é possível criar um armazenamento de chave-valor vazio e adicionar pares de chave-valor posteriormente.
**nota**
Se você especificar sua fonte de dados a partir de um bucket do Amazon S3, deverá ter as permissões `s3:GetObject` e `s3:GetBucketLocation` para esse bucket. Se você não tiver essas permissões, o CloudFront não poderá criar seu armazenamento de chave-valor com êxito.
Decida se deseja adicionar pares de chave-valor ao mesmo tempo em que cria o armazenamento de chave-valor. É possível importar os pares de chave-valor usando o console do CloudFront, a API do CloudFront ou os SDKs da AWS. No entanto, só é possível importar o arquivo de pares de chave-valor ao criar *inicialmente* o armazenamento de chave-valor.
Para criar um arquivo de pares de chave-valor, consulte [Formato de arquivo para pares de chave-valor](kvs-with-functions-create-s3-kvp.md).
------
#### [ Console ]
**Como criar um armazenamento 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. Escolha a guia **KeyValueStores** e selecione **Criar KeyValueStore**.
1. Informe um nome e uma descrição opcional para o armazenamento de valores de chave.
1. Preencha o **URI do S3**:
+ Se você tem um arquivo de pares de chave-valor, insira o caminho para o bucket do Amazon S3 no qual armazenou o arquivo.
+ Deixe esse campo em branco se planeja inserir os pares de chave-valor manualmente.
1. Escolha **Criar**. O armazenamento de chave-valor existe agora.
A página de detalhes do novo armazenamento de valores de chave é exibida. As informações na página incluem o ID e o ARN do armazenamento de valores de chave.
+ O ID é uma string de caracteres aleatória exclusiva na Conta da AWS.
+ O ARN tem esta sintaxe:
*Conta da AWS*`:key-value-store/`*o ID de armazenamentos de chave-valor*
1. Veja a seção **Pares de chave-valor**. Se você importou um arquivo, essa seção mostrará alguns pares de chave-valor. Você pode fazer o seguinte:
+ Se você importou um arquivo, também poderá adicionar mais valores manualmente.
+ Se você não importou um arquivo de um bucket do Amazon S3 e deseja adicionar pares de chave-valor agora, poderá concluir a próxima etapa.
+ É possível ignorar essa etapa e adicionar os pares de chave-valor posteriormente.
1. Como adicionar os pares agora:
1. Selecione **Adicionar pares de chave-valor**.
1. Selecione **Adicionar par** e insira um nome e um valor. Repita essa etapa para adicionar mais pares.
1. Ao terminar, selecione **Salvar alterações** para salvar todos os pares de chave-valor no armazenamento de valores de chave. Na caixa de diálogo exibida, selecione **Concluído**.
1. Para associar agora o armazenamento de valores de chave a uma função agora, preencha a seção **Funções associadas**. Para ter mais informações, consulte [Criar funções](create-function.md) ou [Atualizar funções](update-function.md).
Também é possível associar a função posteriormente, na página de detalhes do armazenamento de valores de chave ou na página de detalhes da função.
------
#### [ AWS CLI ]
**Como criar um armazenamento de chave-valor**
+ Execute o comando a seguir para criar um armazenamento de chave-valor e importar os pares de chave-valor de um bucket do Amazon S3.
```
aws cloudfront create-key-value-store \
--name=keyvaluestore1 \
--comment="This is my key value store file" \
--import-source=SourceType=S3,SourceARN=arn:aws:s3:::amzn-s3-demo-bucket1/kvs-input.json
```
**Resposta**
```
{
"ETag": "ETVABCEXAMPLE",
"Location": "https://cloudfront.amazonaws.com/2020-05-31/key-value-store/arn:aws:cloudfront::123456789012:key-value-store/8aa76c93-3198-462c-aaf6-example",
"KeyValueStore": {
"Name": "keyvaluestore1",
"Id": "8aa76c93-3198-462c-aaf6-example",
"Comment": "This is my key value store file",
"ARN": "arn:aws:cloudfront::123456789012:key-value-store/8aa76c93-3198-462c-aaf6-example",
"Status": "PROVISIONING",
"LastModifiedTime": "2024-08-06T22:19:10.813000+00:00"
}
}
```
------
#### [ API ]
**Como criar um armazenamento de chave-valor**
1. Use a operação [CreateKeyValueStore do CloudFront](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_CreateKeyValueStore.html). A operação usa vários parâmetros:
+ Um `name` do armazenamento de chave-valor.
+ Um parâmetro `comment` que inclua um comentário.
+ Um parâmetro `import-source` que permita importar pares de chave-valor de um arquivo armazenado em um bucket do Amazon S3. É possível importar de um arquivo somente durante a criação inicial do armazenamento de chave-valor. Para ter informações sobre a estrutura de arquivos, consulte [Formato de arquivo para pares de chave-valor](kvs-with-functions-create-s3-kvp.md).
A resposta da operação inclui as seguintes informações:
+ Os valores transmitidos na solicitação, incluindo o nome atribuído.
+ Dados, como o horário de criação.
+ Uma `ETag` (por exemplo, `ETVABCEXAMPLE`), o ARN que inclui o nome do armazenamento de chave-valor (por exemplo, `arn:aws:cloudfront::123456789012:key-value-store/keyvaluestore1`).
Você usará alguma combinação da `ETag`, do ARN e do nome para trabalhar com o armazenamento de chave-valor de forma programática.
------
## Status do armazenamento de chave-valor
Ao criar um armazenamento de chave-valor, o armazenamento de dados pode apresentar os seguintes valores de status.
****
| Valor | Descrição |
| --- | --- |
| **Provisionamento** | O armazenamento de chave-valor foi criado e o CloudFront está processando a fonte de dados especificada. |
| **Ready** | O armazenamento de chave-valor foi criado e o CloudFront processou com êxito a fonte de dados especificada. |
| **Falha na importação** | O CloudFront não conseguiu processar a fonte de dados especificada. Esse status pode aparecer se o formato do arquivo não for válido ou exceder o limite de tamanho. Para obter mais informações, consulte [Formato de arquivo para pares de chave-valor](kvs-with-functions-create-s3-kvp.md). |
# Associar o armazenamento de chave-valor à função
Depois de criar o armazenamento de chave-valor, é possível atualizar a função para associá-la a esse armazenamento. É necessário fazer essa associação para usar os pares de chave-valor desse armazenamento nessa função. As seguintes regras se aplicam:
+ Uma função pode ter apenas um armazenamento de chave-valor.
+ É possível associar o mesmo armazenamento de chave-valor a várias funções.
------
#### [ Console ]
**Como associar o armazenamento de chave-valor a uma função**
1. Faça login no console do CloudFront em [https://console.aws.amazon.com/cloudfront/v4/home#/functions](https://console.aws.amazon.com/cloudfront/v4/home#/functions) e selecione a página **Funções**.
1. Escolha o nome da função.
1. Acesse a seção **Associar KeyValueStore** e selecione **Associar KeyValueStore existente**.
1. Selecione o armazenamento de chave-valor que contém os pares de chave-valor na função e escolha **Associar KeyValueStore**.
O CloudFront associa imediatamente o armazenamento à função. Não é necessário salvar a função.
1. Para especificar um armazenamento de chave-valor diferente, escolha **Atualizar KeyValueStore associado**, selecione outro nome de armazenamento de chave-valor e escolha **Associar KeyValueStore**.
Para obter mais informações, consulte [Atualizar funções](update-function.md).
------
#### [ AWS CLI ]
**Como associar o armazenamento de chave-valor a uma função**
+ Execute o comando a seguir para atualizar a função `MaxAge` e associar um recurso de armazenamento de chave-valor.
```
aws cloudfront update-function \
--name MaxAge \
--function-config '{"Comment":"Max Age 2 years","Runtime":"cloudfront-js-2.0","KeyValueStoreAssociations":{"Quantity":1,"Items":[{"KeyValueStoreARN":"arn:aws:cloudfront::123456789012:key-value-store/8aa76c93-3198-462c-aaf6-example"}]}}' \
--function-code fileb://function-max-age-v1.js \
--if-match ETVABCEXAMPLE
```
+ Para associar um armazenamento de chave-valor a uma função, especifique o parâmetro `KeyValueStoreAssociations` e o ARN do armazenamento de chave-valor.
+ Para alterar a associação, especifique outro ARN de armazenamento de chave-valor.
+ Para remover a associação, remova o parâmetro `KeyValueStoreAssociations`.
Para obter mais informações, consulte [Atualizar funções](update-function.md).
------
#### [ API ]
**Como associar o armazenamento de chave-valor a uma função**
+ Use a operação de API [UpdateFunction](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_UpdateFunction.html). Para obter mais informações, consulte [Atualizar funções](update-function.md).
------
**Observações**
Se você modificar um armazenamento de chave-valor sem alterar os pares de chave-valor, ou se você modificar somente os pares de chave-valor no armazenamento de chave-valor, não será necessário associar esse armazenamento novamente. Você também não precisa republicar a função.
No entanto, recomendamos que você teste a função para verificar se ela funciona conforme o esperado. Para obter mais informações, consulte [Testar funções](test-function.md).
É possível visualizar todas as funções que usam armazenamentos de chave-valor específicos. No console do CloudFront, selecione a página de detalhes do armazenamento de chave-valor.
# Atualizar um armazenamento de chave-valor
Ao atualizar um armazenamento de chave-valor, é possível alterar os pares de chave-valor ou alterar a associação entre esse armazenamento e a função.
------
#### [ Console ]
**Como atualizar um armazenamento 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 atualizar.
+ Para atualizar os pares de chave-valor, selecione **Editar** na seção **Pares de chave-valor**. É possível adicionar ou excluir qualquer par de chave-valor. Também é possível alterar o valor de um par de chave-valor existente. Ao concluir, escolha **Salvar alterações**.
+ Para atualizar a associação desse armazenamento de chave-valor, selecione **Ir para funções**. Para obter mais informações, consulte [Associar o armazenamento de chave-valor à função](kvs-with-functions-associate.md).
------
#### [ AWS CLI ]
**Como atualizar um armazenamento de chave-valor**
1. **Alterar pares de chave-valor**: é possível adicionar mais pares de chave-valor, excluir um ou mais pares de chave-valor e alterar o valor de um par existente. Para obter mais informações, consulte [Trabalhar com dados de chave-valor](kvs-with-functions-kvp.md).
1. **Alterar a associação da função para o armazenamento de chave-valor**: para atualizar a associação da função para o armazenamento de chave-valor, consulte [Associar o armazenamento de chave-valor à função](kvs-with-functions-associate.md).
**dica**
Você precisará do ARN do armazenamento de valores de chave. Para obter mais informações, consulte [Obter uma referência a um armazenamento de chave-valor](kvs-with-functions-get-reference.md).
------
#### [ API ]
**Como atualizar um armazenamento de chave-valor**
1. **Alterar pares de chave-valor**: é possível adicionar mais pares de chave-valor, excluir um ou mais pares de chave-valor e alterar o valor de um par existente. Para obter mais informações, consulte [Trabalhar com dados de chave-valor](kvs-with-functions-kvp.md).
1. **Alterar a associação da função para o armazenamento de chave-valor**: para atualizar a associação da função para o armazenamento de chave-valor, use a operação de API [UpdateFunction](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_UpdateFunction.html). Para obter mais informações, consulte [Atualizar funções](update-function.md).
**dica**
Você precisará do ARN do armazenamento de valores de chave. Para obter mais informações, consulte [Obter uma referência a um armazenamento de chave-valor](kvs-with-functions-get-reference.md).
------
# Obter uma referência a um armazenamento de chave-valor
Para trabalhar com os armazenamentos de chave-valor de forma programática, é necessário ter a `ETag` e o nome do armazenamento de chave-valor.
Para ter os dois valores, é possível usar a AWS Command Line Interface (AWS CLI) ou a API do CloudFront.
------
#### [ AWS CLI ]
**Como obter uma referência do armazenamento de chave-valor**
1. Para exibir uma lista de armazenamentos de chave-valor, execute o comando para encontrar o nome do armazenamento de chave-valor que deseja alterar.
```
aws cloudfront list-key-value-stores
```
1. Na resposta, encontre o nome do armazenamento de chave-valor desejado.
**Resposta**
```
{
"KeyValueStoreList": {
"Items": [
{
"Name": "keyvaluestore3",
"Id": "37435e19-c205-4271-9e5c-example3",
"ARN": "arn:aws:cloudfront::123456789012:key-value-store/37435e19-c205-4271-9e5c-example3",
"Status": "READY",
"LastModifiedTime": "2024-05-08T14:50:18.876000+00:00"
},
{
"Name": "keyvaluestore2",
"Id": "47970d59-6408-474d-b850-example2",
"ARN": "arn:aws:cloudfront::123456789012:key-value-store/47970d59-6408-474d-b850-example2",
"Status": "READY",
"LastModifiedTime": "2024-05-30T21:06:22.113000+00:00"
},
{
"Name": "keyvaluestore1",
"Id": "8aa76c93-3198-462c-aaf6-example",
"ARN": "arn:aws:cloudfront::123456789012:key-value-store/8aa76c93-3198-462c-aaf6-example",
"Status": "READY",
"LastModifiedTime": "2024-08-06T22:19:30.510000+00:00"
}
]
}
}
```
1. Execute o comando a seguir para exibir a `ETag` do armazenamento de chave-valor especificado.
```
aws cloudfront describe-key-value-store \
--name=keyvaluestore1
```
**Resposta**
```
{
"ETag": "E3UN6WX5RRO2AG",
"KeyValueStore": {
"Name": "keyvaluestore1",
"Id": "8aa76c93-3198-462c-aaf6-example",
"Comment": "This is an example KVS",
"ARN": "arn:aws:cloudfront::123456789012:key-value-store/8aa76c93-3198-462c-aaf6-example",
"Status": "READY",
"LastModifiedTime": "2024-08-06T22:19:30.510000+00:00"
}
}
```
------
#### [ API ]
**Como obter uma referência do 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 retornar uma lista de armazenamentos de valores-chave. Encontre o nome do armazenamento de chave-valor que deseja alterar.
1. Use a operação de API [https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_DescribeKeyValueStore.html](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_DescribeKeyValueStore.html) e especifique o nome do armazenamento de chave-valor que você retornou da etapa anterior.
------
A resposta inclui um UUID, o ARN do armazenamento de chave-valor e a `ETag` do armazenamento de chave-valor.
+ Uma `ETag`, como `E3UN6WX5RRO2AG`.
+ O UUID tem 128 bits, como `8aa76c93-3198-462c-aaf6-example`.
+ 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/8aa76c93-3198-462c-aaf6-example`
Consulte mais informações sobre a operação `DescribeKeyValueStore` em [Sobre o KeyValueStore do CloudFront](kvs-with-functions-kvp.md#kvs-with-functions-api-describe).
# Excluir um armazenamento de chave-valor
É possível excluir o armazenamento de chave-valor usando a API ou o console do Amazon CloudFront.
------
#### [ Console ]
**Como excluir um armazenamento 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. Escolha o nome da função.
1. Na seção **KeyValueStore associado**, verifique se um armazenamento de chave-valor está associado à função. Se estiver, remova a associação escolhendo **Dissociar KeyValueStore** e selecione **Remover associação**.
1. No painel de navegação, selecione a página **Funções** e escolha a guia **KeyValueStores**.
1. Selecione o armazenamento de chave-valor que deseja excluir e selecione **Excluir**.
------
#### [ AWS CLI ]
**Como excluir um armazenamento de chave-valor**
1. Obtenha a `ETag` e o nome dos armazenamentos de chave-valor. Para obter mais informações, consulte [Obter uma referência a um armazenamento de chave-valor](kvs-with-functions-get-reference.md).
1. Verifique se os armazenamentos de chave-valor estão associados a uma função. Se estiver, remova a associação. Para obter mais informações sobre essas duas etapas, consulte [Atualizar funções](update-function.md).
1. Depois que você tiver o nome e a `ETag` do armazenamento de chave-valor e ele não estiver mais associado a uma função, você poderá excluí-lo.
Execute o comando a seguir para excluir o armazenamento de chave-valor especificado.
```
aws cloudfront delete-key-value-store \
--name=keyvaluestore1 \
--if-match=E3UN6WX5RRO2AG
```
------
#### [ API ]
**Como excluir um armazenamento de chave-valor**
1. Obtenha a `ETag` e o nome dos armazenamentos de chave-valor. Para obter mais informações, consulte [Obter uma referência a um armazenamento de chave-valor](kvs-with-functions-get-reference.md).
1. Verifique se os armazenamentos de chave-valor estão associados a uma função. Se estiver, remova a associação. Para obter mais informações sobre essas duas etapas, consulte [Atualizar funções](update-function.md).
1. Para excluir o armazenamento de chave-valor, use a operação de API [https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_DeleteKeyValueStore.html](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_DeleteKeyValueStore.html) do CloudFront.
------
# Formato de arquivo para pares de chave-valor
Ao criar um arquivo codificado em UTF-8, use o seguinte formato JSON:
```
{
"data":[
{
"key":"key1",
"value":"value"
},
{
"key":"key2",
"value":"value"
}
]
}
```
Seu arquivo não pode incluir chaves duplicadas. Se você especificou um arquivo inválido em seu bucket do Amazon S3, é possível atualizar o arquivo para remover quaisquer duplicatas e, em seguida, tentar criar seu armazenamento de chave-valor novamente.
Para obter mais informações, consulte [Criar um armazenamento de chave-valor](kvs-with-functions-create.md).
**nota**
O arquivo da fonte de dados e os pares de chave-valor têm os seguintes limites:
Tamanho do arquivo: 5 MB
Tamanho da chave: 512 caracteres
Tamanho da chave: 1.024 caracteres
# 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);
}
})();
```