# 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