Referências de snapshots

As referências snapshot são chaves de valor especiais que apontam para um snapshot específico num repositório de configuração de aplicações. Permitem combinar a segurança da configuração imutável (snapshots) com a flexibilidade de alterar dinamicamente qual snapshot uma aplicação consome em tempo de execução.

Com o uso direto de snapshots, uma aplicação seleciona um snapshot pelo nome em código. Alterar o snapshot alvo requer uma nova implementação ou alteração de configuração no caminho do código que constrói a configuração. As referências snapshot removem essa restrição: carrega-se uma referência-chave-valor uma vez e, se o nome do snapshot alvo mudar mais tarde, os fornecedores de configuração recarregam automaticamente a configuração para o novo conjunto imutável.

Porque é que usar referências de snapshot?

As referências snapshot fornecem:

• Atualizações fáceis: Atualize o snapshot referenciado sem tocar no código da aplicação, mesmo durante a execução.
• Conjuntos de configuração imutáveis: Cada snapshot permanece inalterado, preservando garantias de auditabilidade e rollback.

Como funcionam

Uma referência de snapshot é armazenada como um valor-chave cujo valor contém o nome do snapshot a consumir. Quando um fornecedor de configuração carrega valores-chave, quaisquer referências de snapshots entre os itens selecionados são automaticamente resolvidas. Os valores-chave do snapshot referenciado são fundidos na configuração da aplicação. Se a referência mudar para apontar para um snapshot diferente, a atualização do fornecedor de configuração faz com que o novo conteúdo do snapshot seja carregado.

Criação de uma referência instantânea

1. Abra sua loja de Configuração de Aplicativo no portal do Azure.
2. Selecione Configuration Explorer.
3. Selecione Criar.
4. Selecione Referência instantânea.
5. Insere uma chave para a referência. Opcionalmente, define uma etiqueta.
6. Escolhe o nome do snapshot alvo da lista (ou insere-o).
7. Selecione Criar.

Uma vez criada, a referência snapshot aparece juntamente com outros valores-chave no Explorador de Configuração.

Consumo de referências instantâneas

Não é necessário código novo para usar uma referência de snapshot. Se a chave para uma referência de snapshot fizer parte dos valores-chave selecionados ao construir a configuração, o fornecedor resolve e carrega automaticamente os valores-chave do snapshot referenciado. Compare isto com o uso direto de snapshots, onde se chama explicitamente uma API, como SelectSnapshot("SnapshotName"), fixando a escolha do snapshot no arranque, o que faz com que qualquer alteração posterior exija uma mudança de código ou reimplantação.

Comportamento de atualização

Quando a atualização está configurada, alterar o nome do snapshot de destino dentro de uma referência de snapshot faz a aplicação usar o novo snapshot de forma fluida:

1. A aplicação inicia.
2. O fornecedor de configuração obtém valores-chave selecionados, incluindo uma referência instantânea.
3. O fornecedor de configuração resolve a referência em snapshot Snapshot_A e carrega os seus valores-chave.
4. A referência do snapshot é atualizada para apontar para Snapshot_B (ainda imutável).
5. O fornecedor de configuração deteta que a chave-valor da referência do instantâneo foi alterada.
6. O fornecedor de configuração resolve novamente. Os valores-chave de Snapshot_A são removidos. A recarga da configuração produz os valores-chave de Snapshot_B.

Exemplo de referência de instantâneo

O exemplo seguinte demonstra uma referência de snapshot

{
    "key": "app1/snapshot-reference",
    "value": "{\"snapshot_name\":\"referenced-snapshot\"}",
    "content_type": "application/json; profile=\"https://azconfig.io/mime-profiles/snapshot-ref\"; charset=utf-8",
    "tags": {}
}

Como mencionado, uma referência snapshot é um valor-chave normal com algumas restrições adicionais. Os fornecedores de configuração identificam referências de instantâneos pelo seu tipo de conteúdo específico. O valor de uma referência de snapshot é um objeto JSON com uma propriedade de nome que aponta para o snapshot alvo.

Tipo de conteúdo de referência instantânea: application/json; profile="https://azconfig.io/mime-profiles/snapshot-ref"; charset=utf-8

Resolução de conflitos chave

Os snapshots referenciados podem conter chaves que entram em conflito com os valores-chave normais (aqueles fora de um snapshot). Os fornecedores de configuração resolvem estes conflitos utilizando o valor da última chave vista. No caso dos snapshots, uma vez que são resolvidos imediatamente após serem vistos, a ordenação lexicográfica da chave de referência snapshot é um detalhe importante ao considerar o valor final de uma dada chave quando existem conflitos.

Exemplo simplificado

Assuma que a sua loja tem estes valores-chave normais:

key: message
value: hello-world

key: request-limit
value: 100

E uma captura de imagem contendo:

key: message
value: bye

key: request-limit
value: 8000

Se for adicionada uma referência de instantâneo que aponta para o instantâneo mencionado, então a configuração final efetiva depende da posição lexicográfica da chave de referência de instantâneo.

Considerações e casos excepcionais

• Snapshot alvo em falta: Se a referência apontar para um nome de snapshot que não existe ou foi arquivado fora do prazo de retenção, o fornecedor ignora a referência.
• Sem resolução transitiva: Se um snapshot referenciado contiver um valor-chave que é ele próprio uma referência snapshot, essa referência interna não é resolvida.
• Controlo de acesso: Ler um snapshot através de uma referência requer permissões de leitura de snapshot, de forma semelhante a ler um snapshot diretamente.
• Retenção/arquivamento: Tenha cuidado ao consultar snapshots arquivados, pois quando o snapshot expirar, a aplicação deixará de conseguir aceder à configuração contida.

Disponibilidade do idioma

Próximos passos

Para um contexto mais profundo, veja a visão geral dos Snapshots.