Operações básicas para livros contábeis da Amazon QLDB - Banco de dados Amazon Quantum Ledger (AmazonQLDB)
Criar um ledgerDescrever um ledgerAtualizar um ledgerAtualizar o modo de permissões de um ledgerExcluir um ledgerListar ledgers

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Operações básicas para livros contábeis da Amazon QLDB

Importante

Aviso de fim do suporte: os clientes existentes poderão usar a Amazon QLDB até o final do suporte em 31/07/2025. Para obter mais detalhes, consulte Migrar um Amazon QLDB Ledger para o Amazon Aurora Postgre. SQL

Você pode usar o QLDB API ou o AWS Command Line Interface (AWS CLI) para criar, atualizar e excluir livros contábeis na Amazon. QLDB Você também pode listar todos os ledgers da sua conta ou obter informações sobre um ledger específico.

Os tópicos a seguir fornecem exemplos de códigos curtos que mostram etapas comuns para operações contábeis usando o AWS SDK for Java e o. AWS CLI

Para exemplos de código que demonstram essas operações em um aplicativo de amostra completo, consulte os seguintes Conceitos básicos do driver tutoriais e GitHub repositórios:

Criar um ledger

Use a operação CreateLedger para criar um ledger no Conta da AWS. Você deve fornecer as seguintes informações:

  • Nome do ledgers: o nome do ledger que você deseja criar em sua conta. O nome deve ser exclusivo entre todos os seus ledgers na Região da AWS atual.

    Restrições de nomenclatura para nomes de ledgers são definidas em Cotas e limites na Amazon QLDB.

  • Modo de permissões: o modo de permissões a ser atribuído ao ledger. Escolha uma das seguintes opções:

    • Permitir tudo — Um modo de permissões antigo que permite o controle de acesso com granularidade API de nível para livros contábeis.

      Esse modo permite que os usuários que têm SendCommand API permissão para esse registro executem todos os comandos do PartiQL (portantoALLOW_ALL,) em qualquer tabela no livro contábil especificado. Esse modo ignora qualquer política de IAM permissões em nível de tabela ou de comando que você cria para o livro contábil.

    • Padrão - (Recomendado) Um modo de permissões que permite o controle do acesso com granularidade mais fina para ledgers, tabelas e comandos PartiQL. Recomendamos o uso deste modo de permissões para maximizar a segurança dos dados do seu ledger.

      Por padrão, esse modo nega todas as solicitações de execução de comandos do PartiQL em qualquer tabela nesse ledger. Para permitir comandos do PartiQL, você deve criar políticas de IAM permissões para recursos específicos da tabela e ações do PartiQL, além da SendCommand API permissão para o livro contábil. Para obter mais informações, consulte Introdução ao modo de permissões padrão na Amazon QLDB.

  • Proteção contra exclusão: (opcional) o sinalizador que impede que um ledger seja excluído por qualquer usuário. Se você não especificar na criação do ledger, esse atributo estará habilitado (true) por padrão.

    Se a proteção contra exclusão estiver ativada, você deverá desabilitá-la antes de excluir o ledger. Você pode desabilitá-la usando a operação UpdateLedger para definir o sinalizador como false.

  • AWS KMS key: (opcional) a chave em AWS Key Management Service (AWS KMS) a ser usada para criptografia de dados em repouso. Escolha um dos seguintes tipos de AWS KMS keys:

    • AWS KMSchave de propriedade — Use uma KMS chave de propriedade e gerenciada AWS em seu nome.

      Se você não definir esse parâmetro durante a criação do ledger, ele usará esse tipo de chave por padrão. Você também pode usar a string AWS_OWNED_KMS_KEY para especificar esse tipo de chave. Essa opção não requer configuração adicional.

    • KMSChave gerenciada pelo cliente — use uma KMS chave de criptografia simétrica em sua conta que você cria, possui e gerencia. QLDBnão suporta chaves assimétricas.

      Essa opção exige que você crie uma KMS chave ou use uma chave existente na sua conta. Para obter instruções sobre como criar uma chave gerenciada pelo cliente, consulte Criação de KMS chaves de criptografia simétricas no Guia do AWS Key Management Service desenvolvedor.

      Você pode especificar uma KMS chave gerenciada pelo cliente usando um ID, alias ou Amazon Resource Name (ARN). Para saber mais, consulte Identificadores de chave (KeyId) no Guia do AWS Key Management Service desenvolvedor.

      nota

      Chaves entre regiões não são compatíveis. A KMS chave especificada deve estar na Região da AWS mesma do seu livro contábil.

    Para ter mais informações, consulte Criptografia em repouso na Amazon QLDB.

  • Tags: (optional) adicionar metadados à função anexando etiquetas como pares de chave-valor. Você pode adicionar tags ao seu ledger para ajudar a organizá-lo e identificá-lo. Para ter mais informações, consulte Marcação de recursos da Amazon QLDB.

O livro não está pronto para uso até que seja QLDB criado e definido seu status comoACTIVE.

Para criar um livro contábil usando o AWS SDK for Java

  1. Crie uma instância da classe AmazonQLDB.

  2. Crie uma instância da classe CreateLedgerRequest para fornecer as informações solicitadas.

    Você deve fornecer o nome do ledger e um modo de permissões.

  3. Execute o método createLedger fornecendo o objeto de solicitação como um parâmetro.

A solicitação createLedger retorna um objeto CreateLedgerResult que tem informações sobre o ledger. Consulte a próxima seção para obter um exemplo de como usar a operação DescribeLedger para verificar o status do seu ledger depois de criá-lo.

O exemplo a seguir demonstra as etapas anteriores.

exemplo — Use as configurações padrão
AmazonQLDB client = AmazonQLDBClientBuilder.standard().build();
CreateLedgerRequest request = new CreateLedgerRequest()
        .withName(ledgerName)
        .withPermissionsMode(PermissionsMode.STANDARD);
CreateLedgerResult result = client.createLedger(request);
nota

O ledger usa as seguintes configurações padrão se você não as especificar:

  • Proteção contra exclusão – ativada (true).

  • KMSchave — KMS chave AWS de propriedade.

exemplo — Desative a proteção contra exclusão, use uma KMS chave gerenciada pelo cliente e anexe etiquetas
AmazonQLDB client = AmazonQLDBClientBuilder.standard().build();

Map<String, String> tags = new HashMap<>();
tags.put("IsTest", "true");
tags.put("Domain", "Test");

CreateLedgerRequest request = new CreateLedgerRequest()
        .withName(ledgerName)
        .withPermissionsMode(PermissionsMode.STANDARD)
        .withDeletionProtection(false)
        .withKmsKey("arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab")
        .withTags(tags);
CreateLedgerResult result = client.createLedger(request);

Crie um novo ledger chamado vehicle-registration usando as configurações padrão.

exemplo 
aws qldb create-ledger --name vehicle-registration --permissions-mode STANDARD
nota

O ledger usa as seguintes configurações padrão se você não as especificar:

  • Proteção contra exclusão – ativada (true).

  • KMSchave — KMS chave AWS de propriedade.

Ou crie um novo livro contábil chamado vehicle-registration com a proteção de exclusão desativada, com uma KMS chave gerenciada pelo cliente especificada e com tags especificadas.

exemplo 
aws qldb create-ledger \
    --name vehicle-registration \
    --no-deletion-protection \
    --permissions-mode STANDARD \
    --kms-key arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab \
    --tags IsTest=true,Domain=Test

Você também pode usar um modelo AWS CloudFormation para criar ledgers. Para obter mais informações, consulte o recurso AWS::QLDB: :Ledger no Guia do AWS CloudFormation Usuário.

Descrever um ledger

Para visualizar detalhes sobre um ledger, use a operação DescribeLedger. Você deve fornecer o nome do ledger. A saída de DescribeLedger está no mesmo formato de CreateLedger. Isso inclui as informações a seguir:

  • Nome do ledger: o nome do ledger que você deseja descrever.

  • ARN— O Amazon Resource Name (ARN) para o livro contábil no seguinte formato.

    arn:aws:qldb:aws-region:account-id:ledger/ledger-name

  • Proteção contra exclusão: o sinalizador que indica se o atributo de proteção contra exclusão está ativado.

  • Data e hora da criação: a data e a hora, em formato epoch time, quando o ledger foi criado.

  • Estado: o status atual do ledger. Pode ter um dos valores a seguir:

    • CREATING

    • ACTIVE

    • DELETING

    • DELETED

  • Modo de permissões: o modo de permissões atribuído ao ledger. Pode ter um dos valores a seguir:

    • ALLOW_ALL— Um modo de permissões antigo que permite o controle de acesso com granularidade API de nível para livros contábeis.

    • STANDARD: um modo de permissões que permite o controle do acesso com granularidade mais fina para ledgers, tabelas e comandos PartiQL.

  • Descrição da criptografia: informações sobre a criptografia de dados em repouso no ledger. Isso inclui os seguintes itens:

    • AWS KMS key ARN— A ARN KMS chave gerenciada pelo cliente que o livro contábil usa para criptografia em repouso. Se isso for indefinido, o livro contábil usa uma KMS chave AWS própria para criptografia.

    • Status da criptografia: o status atual da criptografia em repouso para o ledger. Pode ter um dos valores a seguir:

      • ENABLED: a criptografia é totalmente ativada usando a chave especificada.

      • UPDATING: a alteração de chave especificada está sendo processada ativamente.

        As principais alterações QLDB são assíncronas. O ledger é totalmente acessível sem nenhum impacto no desempenho enquanto a alteração da chave está sendo processada. O tempo necessário para atualizar uma chave varia dependendo do tamanho do ledger.

      • KMS_KEY_INACCESSIBLE— A KMS chave gerenciada pelo cliente especificada não está acessível e o livro contábil está danificado. Ou a chave foi desativada ou excluída, ou as concessões da chave foram revogadas. Quando um ledger está danificado, ele não está acessível e não aceita nenhuma solicitação de leitura ou gravação.

        Um ledger danificado retorna automaticamente ao estado ativo depois que você restaura as concessões na chave ou depois de reativar a chave que foi desativada. No entanto, a exclusão de uma KMS chave gerenciada pelo cliente é irreversível. Depois que uma chave é excluída, não é mais possível acessar os ledgers que estão protegidos com ela, e os dados ficam irrecuperáveis permanentemente.

    • Inacessível AWS KMS key — A data e a hora, no formato de época, quando a KMS chave ficou inacessível pela primeira vez, no caso de um erro.

      Isso é indefinido se a KMS chave estiver acessível.

    Para ter mais informações, consulte Criptografia em repouso na Amazon QLDB.

nota

Depois de criar um QLDB livro contábil, ele fica pronto para uso quando seu status muda de CREATING paraACTIVE.

Para descrever um livro contábil usando o AWS SDK for Java

  1. Crie uma instância da classe AmazonQLDB. Ou você pode usar a mesma instância do cliente AmazonQLDB que você instanciou para a solicitação CreateLedger.

  2. Crie uma instância da classe DescribeLedgerRequest e forneça o nome do ledger que deseja excluir.

  3. Execute o método describeLedger fornecendo o objeto de solicitação como um parâmetro.

  4. A solicitação describeLedger retorna um objeto DescribeLedgerResult que tem informações sobre o ledger.

O exemplo de código a seguir demonstra as etapas anteriores. Você pode chamar o método describeLedger do cliente para obter informações do ledger a qualquer momento.

exemplo 
AmazonQLDB client = AmazonQLDBClientBuilder.standard().build();
DescribeLedgerRequest request = new DescribeLedgerRequest().withName(ledgerName);
DescribeLedgerResult result = client.describeLedger(request);
System.out.printf("%s: ARN: %s \t State: %s \t CreationDateTime: %s \t DeletionProtection: %s
                   \t PermissionsMode: %s \t EncryptionDescription: %s",
        result.getName(),
        result.getArn(),
        result.getState(),
        result.getCreationDateTime(),
        result.getDeletionProtection(),
        result.getPermissionsMode(),
        result.getEncryptionDescription());

Descrever o ledger vehicle-registration que você acabou de criar.

exemplo 
aws qldb describe-ledger --name vehicle-registration

Atualizar um ledger

Atualmente, a operação UpdateLedger permite que você altere as seguintes configurações para um ledger existente:

  • Proteção contra exclusão: o sinalizador que impede que um ledger seja excluído por qualquer usuário. Se esse atributo estiver habilitado, você deverá primeiro desabilitá-lo definindo o sinalizador como false antes de excluir o ledger.

    Se você não definir esse parâmetro, nenhuma alteração será feita na configuração de proteção contra exclusão do ledger.

  • AWS KMS key— A chave in AWS Key Management Service (AWS KMS) a ser usada para criptografia de dados em repouso. Se você não definir esse parâmetro, nenhuma alteração será feita na KMS chave do livro contábil.

    nota

    A Amazon QLDB lançou o suporte para gerenciamento de clientes AWS KMS keys em 22 de julho de 2021. Todos os livros contábeis criados antes do lançamento são protegidos Chaves pertencentes à AWS por padrão, mas atualmente não estão qualificados para criptografia em repouso usando chaves gerenciadas pelo cliente.

    Você pode ver a hora de criação do seu livro contábil no QLDB console.

    Use uma das seguintes opções:

    • AWS KMSchave de propriedade — Use uma KMS chave de propriedade e gerenciada AWS em seu nome. Para usar esse tipo de chave, especifique a string AWS_OWNED_KMS_KEY desse parâmetro. Essa opção não requer configuração adicional.

    • KMSChave gerenciada pelo cliente — use uma KMS chave de criptografia simétrica em sua conta que você cria, possui e gerencia. QLDBnão suporta chaves assimétricas.

      Essa opção exige que você crie uma KMS chave ou use uma chave existente na sua conta. Para obter instruções sobre como criar uma chave gerenciada pelo cliente, consulte Criação de KMS chaves de criptografia simétricas no Guia do AWS Key Management Service desenvolvedor.

      Você pode especificar uma KMS chave gerenciada pelo cliente usando um ID, alias ou Amazon Resource Name (ARN). Para saber mais, consulte Identificadores de chave (KeyId) no Guia do AWS Key Management Service desenvolvedor.

      nota

      Chaves entre regiões não são compatíveis. A KMS chave especificada deve estar na Região da AWS mesma do seu livro contábil.

    As principais alterações QLDB são assíncronas. O ledger é totalmente acessível sem nenhum impacto no desempenho enquanto a alteração da chave está sendo processada.

    Você pode trocar de chaves tantas vezes quantas precisar, mas o tempo necessário para atualizar uma chave varia dependendo do tamanho do ledger. Você pode usar a operação DescribeLedger para verificar o status da criptografia em repouso.

    Para ter mais informações, consulte Criptografia em repouso na Amazon QLDB.

A saída de UpdateLedger está no mesmo formato de CreateLedger.

Para atualizar um livro contábil usando o AWS SDK for Java

  1. Crie uma instância da classe AmazonQLDB.

  2. Crie uma instância da classe UpdateLedgerRequest para fornecer as informações solicitadas.

    Você deve fornecer o nome do livro contábil junto com um novo valor booleano para proteção contra exclusão ou um novo valor de cadeia de caracteres para a chave. KMS

  3. Execute o método updateLedger fornecendo o objeto de solicitação como um parâmetro.

O exemplo de código a seguir demonstra as etapas anteriores. A solicitação updateLedger retorna um objeto UpdateLedgerResult que tem informações atualizadas sobre o ledger.

exemplo – Habilitar proteção contra exclusão
AmazonQLDB client = AmazonQLDBClientBuilder.standard().build();
UpdateLedgerRequest request = new UpdateLedgerRequest()
        .withName(ledgerName)
        .withDeletionProtection(false);
UpdateLedgerResult result = client.updateLedger(request);
exemplo — Use uma KMS chave gerenciada pelo cliente
AmazonQLDB client = AmazonQLDBClientBuilder.standard().build();
UpdateLedgerRequest request = new UpdateLedgerRequest()
        .withName(ledgerName)
        .withKmsKey("arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab")
UpdateLedgerResult result = client.updateLedger(request);
exemplo — Use uma AWS KMS chave própria
AmazonQLDB client = AmazonQLDBClientBuilder.standard().build();
UpdateLedgerRequest request = new UpdateLedgerRequest()
        .withName(ledgerName)
        .withKmsKey("AWS_OWNED_KMS_KEY")
UpdateLedgerResult result = client.updateLedger(request);

Se a proteção contra exclusão de seu ledger vehicle-registration estiver habilitada, você deverá desabilitá-la antes de excluir o ledger.

exemplo 
aws qldb update-ledger --name vehicle-registration --no-deletion-protection

Você também pode alterar as configurações de criptografia em repouso do livro contábil para usar uma KMS chave gerenciada pelo cliente.

exemplo 
aws qldb update-ledger --name vehicle-registration --kms-key arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab

Ou você pode alterar as configurações de criptografia em repouso para usar uma AWS KMS chave própria.

exemplo 
aws qldb update-ledger --name vehicle-registration --kms-key AWS_OWNED_KMS_KEY

Atualizar o modo de permissões de um ledger

A operação UpdateLedgerPermissionsMode permite que você altere o modo de permissões de um ledger existente. Escolha uma das seguintes opções:

  • Permitir tudo — Um modo de permissões antigo que permite o controle de acesso com granularidade API de nível para livros contábeis.

    Esse modo permite que os usuários que têm SendCommand API permissão para esse registro executem todos os comandos do PartiQL (portantoALLOW_ALL,) em qualquer tabela no livro contábil especificado. Esse modo ignora qualquer política de IAM permissões em nível de tabela ou de comando que você cria para o livro contábil.

  • Padrão - (Recomendado) Um modo de permissões que permite o controle do acesso com granularidade mais fina para ledgers, tabelas e comandos PartiQL. Recomendamos o uso deste modo de permissões para maximizar a segurança dos dados do seu ledger.

    Por padrão, esse modo nega todas as solicitações de execução de comandos do PartiQL em qualquer tabela nesse ledger. Para permitir comandos do PartiQL, você deve criar políticas de IAM permissões para recursos específicos da tabela e ações do PartiQL, além da SendCommand API permissão para o livro contábil. Para obter mais informações, consulte Introdução ao modo de permissões padrão na Amazon QLDB.

Importante

Antes de mudar para o modo de STANDARD permissões, você deve primeiro criar todas as IAM políticas e tags de tabela necessárias para evitar interrupções para seus usuários. Para saber mais, vá para Migrar para o modo de permissões padrão.

Para atualizar um modo de permissões contábeis usando o AWS SDK for Java

  1. Crie uma instância da classe AmazonQLDB.

  2. Crie uma instância da classe UpdateLedgerPermissionsModeRequest para fornecer as informações solicitadas.

    Você deve fornecer o nome do ledger junto com um novo valor de string para o modo de permissões.

  3. Execute o método updateLedgerPermissionsMode fornecendo o objeto de solicitação como um parâmetro.

O exemplo de código a seguir demonstra as etapas anteriores. A solicitação updateLedgerPermissionsMode retorna um objeto UpdateLedgerPermissionsModeResult que tem informações atualizadas sobre o ledger.

exemplo — Atribuir o modo de permissões padrão
AmazonQLDB client = AmazonQLDBClientBuilder.standard().build();
UpdateLedgerPermissionsModeRequest request = new UpdateLedgerPermissionsModeRequest()
        .withName(ledgerName)
        .withPermissionsMode(PermissionsMode.STANDARD);
UpdateLedgerPermissionsModeResult result = client.updateLedgerPermissionsMode(request);

Atribui o modo de permissões STANDARD ao seu ledger vehicle-registration.

exemplo 
aws qldb update-ledger-permissions-mode --name vehicle-registration --permissions-mode STANDARD

Migrar para o modo de permissões padrão

Para migrar para o modo de STANDARD permissões, recomendamos analisar seus padrões de QLDB acesso e adicionar IAM políticas que concedam aos usuários as permissões apropriadas para acessar seus recursos.

Antes de mudar para o modo de STANDARD permissões, você deve primeiro criar todas as IAM políticas e tags de tabela necessárias. Caso contrário, alternar o modo de permissões pode atrapalhar os usuários até que você crie as IAM políticas corretas ou reverta o modo de permissões. ALLOW_ALL Para obter informações sobre como criar essas políticas, consulte Introdução ao modo de permissões padrão na Amazon QLDB.

Você também pode usar uma política AWS gerenciada para conceder acesso total a todos os QLDB recursos. As políticas AmazonQLDBFullAccess AmazonQLDBConsoleFullAccess gerenciadas incluem todas as QLDB ações, incluindo todas as ações do PartiQL. Anexar uma dessas políticas a uma entidade principal é equivalente ao modo de ALLOW_ALL permissões dessa entidade principal. Para ter mais informações, consulte AWS políticas gerenciadas para a Amazon QLDB.

Excluir um ledger

Use a operação DeleteLedger para excluir um ledger e todo o seu conteúdo. Excluir um ledger é uma operação irrecuperável.

Se a proteção contra exclusão estiver habilitada para o seu ledger, você deverá desabilitá-la antes de excluir o ledger.

Quando você emite uma solicitação DeleteLedger, o status do ledger muda de ACTIVE para DELETING. Pode demorar um pouco para excluir o ledger, dependendo da quantidade de armazenamento que ele usa. Quando a DeleteLedger operação é concluída, o livro não existe mais em. QLDB

Para excluir um livro contábil usando o AWS SDK for Java

  1. Crie uma instância da classe AmazonQLDB.

  2. Crie uma instância da classe DeleteLedgerRequest e forneça o nome do ledger que deseja excluir.

  3. Execute o método deleteLedger fornecendo o objeto de solicitação como um parâmetro.

O exemplo de código a seguir demonstra as etapas anteriores.

exemplo 
AmazonQLDB client = AmazonQLDBClientBuilder.standard().build();
DeleteLedgerRequest request = new DeleteLedgerRequest().withName(ledgerName);
DeleteLedgerResult result = client.deleteLedger(request);

Exclua seu ledger vehicle-registration.

exemplo 
aws qldb delete-ledger --name vehicle-registration

Listar ledgers

A ListLedgers operação retorna informações resumidas de todos os QLDB livros contábeis do atual Conta da AWS e da região.

Para listar livros contábeis em sua conta usando o AWS SDK for Java

  1. Crie uma instância da classe AmazonQLDB.

  2. Crie uma instância da classe ListLedgersRequest.

    Se você recebeu um valor para NextToken na resposta de uma chamada ListLedgers anterior, deverá fornecer esse valor nessa solicitação para obter a próxima página de resultados.

  3. Execute o método listLedgers fornecendo o objeto de solicitação como um parâmetro.

  4. A solicitação listLedgers retorna um objeto ListLedgersResult. Esse objeto tem uma lista de objetos LedgerSummary e um token de paginação que indica se há mais resultados disponíveis:

    • Se NextToken estiver vazio, a última página de resultados foi processada e não há mais resultados.

    • Se NextToken não estiver vazio, há mais resultados disponíveis. Para recuperar a próxima página de resultados, use o valor de NextToken em uma chamada ListLedgers subsequente.

O exemplo de código a seguir demonstra as etapas anteriores.

exemplo 
AmazonQLDB client = AmazonQLDBClientBuilder.standard().build();
List<LedgerSummary> ledgerSummaries = new ArrayList<>();
String nextToken = null;
do {
    ListLedgersRequest request = new ListLedgersRequest().withNextToken(nextToken);
    ListLedgersResult result = client.listLedgers(request);
    ledgerSummaries.addAll(result.getLedgers());
    nextToken = result.getNextToken();
} while (nextToken != null);

Liste todos os livros contábeis no atual Conta da AWS e na região.

exemplo 
aws qldb list-ledgers