Operaciones básicas de libros mayores de Amazon QLDB - Amazon Quantum Ledger Database (Amazon QLDB)

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Operaciones básicas de libros mayores de Amazon QLDB

importante

Aviso de fin del soporte: los clientes actuales podrán utilizar Amazon QLDB hasta que finalice el soporte, el 31 de julio de 2025. Para obtener más información, consulte Migración de un registro de Amazon QLDB a Amazon Aurora PostgreSQL.

Puede usar la API de QLDB o AWS Command Line Interface AWS CLI() para crear, actualizar y eliminar libros de contabilidad en Amazon QLDB. También puede enumerar todos los libros mayores de su cuenta u obtener información sobre uno concreto.

En los siguientes temas se proporcionan ejemplos de código breves que muestran los pasos comunes de las operaciones contables que utilizan el y el. AWS SDK para Java AWS CLI

Para ver ejemplos de código que muestran estas operaciones en una aplicación de muestra completa, consulte los siguientes Introducción al controlador tutoriales y GitHub repositorios:

Creación de un libro mayor

Use la operación CreateLedger para crear un libro mayor en su Cuenta de AWS. Debe proporcionar la siguiente información:

  • Nombre de libro mayor: el nombre del libro mayor que desea crear en su cuenta. El nombre debe ser único entre todos los libros mayores de la Región de AWS actual.

    Las restricciones de nomenclatura de libros mayores se definen en Cuotas y límites de Amazon QLDB.

  • Modo de permisos: el modo de permisos que se va a asignar al libro mayor. Seleccione una de las siguientes opciones:

    • Permitir todo: un modo de permisos heredado que habilita el control de acceso con granularidad de la API para los libros mayores.

      Este modo permite a los usuarios que tengan el permiso de API SendCommand para este libro mayor poner en marcha todos los comandos de PartiQL (por lo tanto, ALLOW_ALL) en cualquier tabla del libro mayor especificado. Este modo no tendrá en cuenta las políticas de permisos de IAM de la tabla o comando que cree para el libro mayor.

    • Estándar: (recomendado) un modo de permisos que habilita el control de acceso con granularidad más precisa para libros mayores, tablas y comandos de PartiQL. Recomendamos encarecidamente usar este modo de permisos para maximizar la seguridad de los datos del libro mayor.

      De forma predeterminada, este modo deniega todas las solicitudes para poner en marcha cualquier comando de PartiQL en tablas de este libro mayor. Para permitir los comandos de PartiQL, debe crear políticas de permisos de IAM para recursos de tablas y acciones de PartiQL específicos, además del permiso de API SendCommand para el libro mayor. Para obtener más información, consulte Introducción al modo de permisos estándar en Amazon QLDB.

  • Protección de eliminación: (opcional) la marca que impide que un usuario elimine un libro mayor. Si no lo especifica al crear el libro mayor, esta característica estará habilitada (true) de forma predeterminada.

    Si la protección contra eliminación está habilitada, primero debe desactivarla para poder eliminar el libro mayor. Puede deshabilitarlo utilizando la operación UpdateLedger para establecer la marca en false.

  • AWS KMS key: (opcional) la clave de AWS Key Management Service (AWS KMS) que se usará para cifrar los datos en reposo. Elija uno de los siguientes tipos de AWS KMS keys:

    • AWS clave de KMS propia: utilice una clave de KMS que sea de su propiedad y que AWS administre en su nombre.

      Si no define este parámetro durante la creación del libro mayor, se usará este tipo de clave por defecto. También puede usar la cadena AWS_OWNED_KMS_KEY para especificar el tipo de clave. Esta opción no requiere ninguna configuración adicional.

    • Clave KMS administrada por el cliente: utilice una clave KMS de cifrado simétrico en la cuenta que ha creado, que posee y que administra. QLDB no admite claves asimétricas.

      Esta opción requiere que cree una clave KMS o use una clave existente en su cuenta. Para obtener instrucciones sobre cómo crear una clave administrada, consulte Creating symmetric encryption KMS keys en la Guía para desarrolladores de AWS Key Management Service .

      Puede especificar una clave KMS administrada por el cliente utilizando un ID, un alias o el Nombre de recurso de Amazon (ARN). Para obtener más información, consulta los identificadores clave (KeyId) en la Guía para AWS Key Management Service desarrolladores.

      nota

      No se admiten claves entre regiones. La clave KMS especificada debe estar en la misma Región de AWS que el libro mayor.

    Para obtener más información, consulte Cifrado en reposo en Amazon QLDB.

  • Etiquetas: (opcional) agregue metadatos al libro mayor asociando etiquetas como pares de clave-valor. Puede añadir etiquetas a su libro mayor para ayudar en su organización e identificación. Para obtener más información, consulte Etiquetado de recursos de Amazon QLDB.

El libro mayor no está listo para usarse hasta que QLDB lo haya creado y haya establecido su estado en ACTIVE.

Para crear un libro mayor mediante el AWS SDK para Java
  1. Cree una instancia de la clase AmazonQLDB.

  2. Cree una instancia de la clase CreateLedgerRequest para proporcionar la información de solicitud.

    Debe proporcionar el nombre del libro mayor y un modo de permisos.

  3. Ejecute el método createLedger proporcionando el objeto de solicitud como parámetro.

La solicitud createLedger devuelve un objeto CreateLedgerResult que contiene información sobre el libro mayor. Consulte la siguiente sección para ver un ejemplo del uso de la operación DescribeLedger para comprobar el estado del libro mayor después de su creación.

Los siguientes ejemplos demuestran los pasos anteriores.

ejemplo – Use los ajustes de configuración predeterminados
AmazonQLDB client = AmazonQLDBClientBuilder.standard().build(); CreateLedgerRequest request = new CreateLedgerRequest() .withName(ledgerName) .withPermissionsMode(PermissionsMode.STANDARD); CreateLedgerResult result = client.createLedger(request);
nota

El libro mayor emplea los siguientes parámetros por defecto si no los especifica:

  • Protección de eliminaciones: habilitada (true).

  • Clave KMS: clave AWS KMS propia.

ejemplo – Desactive la protección contra la eliminación, use una clave KMS administrada por el cliente y adjunte 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);

Cree un nuevo libro mayor denominado vehicle-registration usando los parámetros de configuración predeterminados.

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

El libro mayor emplea los siguientes parámetros por defecto si no los especifica:

  • Protección de eliminaciones: habilitada (true).

  • Clave KMS: AWS clave KMS propia.

O bien cree un nuevo libro mayor denominado vehicle-registration con la protección de eliminación deshabilitada, una clave KMS administrada por el cliente y etiquetas específicas.

ejemplo
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

También puede usar una plantilla de AWS CloudFormation para crear libros mayores. Para obtener más información, consulte el AWS::QLDB::Ledgerrecurso de la Guía del AWS CloudFormation usuario.

Descripción de un libro mayor

Utilice la operación DescribeLedger para ver información detallada sobre un libro mayor. Debe proporcionar el nombre del libro mayor. El resultado de DescribeLedger tiene el mismo formato que el de CreateLedger; Contiene la información siguiente:

  • Nombre de libro mayor: el nombre del libro mayor que desea describir.

  • ARN: el Nombre de recurso de Amazon (ARN) para el libro mayor en el siguiente formato.

    arn:aws:qldb:aws-region:account-id:ledger/ledger-name
  • Protección contra la eliminación: marca que indica si la característica de protección contra la eliminación está habilitada.

  • Fecha y hora de creación: la fecha y la hora, en formato de tiempo epoch, en que se creó el libro mayor.

  • Estado: estado actual del libro mayor. Puede ser uno de los valores siguientes:

    • CREATING

    • ACTIVE

    • DELETING

    • DELETED

  • Modo de permisos: el modo de permisos que se ha asignado al libro mayor. Puede ser uno de los valores siguientes:

    • ALLOW_ALL: un modo de permisos heredado que habilita el control de acceso con granularidad a nivel de la API para libros mayores.

    • STANDARD: un modo de permisos que habilita el control de acceso con granularidad más precisa para libros mayores, tablas y comandos de PartiQL.

  • Descripción del cifrado: información sobre el cifrado de los datos en reposo del libro mayor. Estas incluyen las siguientes elementos:

    • AWS KMS key ARN: el ARN de la clave KMS administrada por el cliente que el libro mayor utiliza para el cifrado en reposo. Si no está definido, el libro mayor utiliza una clave KMS propia para el cifrado AWS .

    • Estado de cifrado: estado actual del cifrado en reposo del libro mayor. Puede ser uno de los valores siguientes:

      • ENABLED: el cifrado está totalmente activado con la clave especificada.

      • UPDATING: el cambio de la clave especificada se está procesando activamente.

        Los cambios de clave en QLDB son asíncronos. Mientras se procesa el cambio de clave, el registro es totalmente accesible sin ningún impacto en el rendimiento. El tiempo que tarda en actualizarse una clave varía según el tamaño del libro mayor.

      • KMS_KEY_INACCESSIBLE: no se puede acceder a la clave KMS administrada por el cliente, y el libro mayor está dañado. La clave se ha deshabilitado o eliminado, o bien se han revocado las concesiones de la clave. Cuando un libro mayor está dañado, no es accesible y no acepta solicitudes de lectura ni escritura.

        Un libro mayor dañado vuelve automáticamente a su estado activo después de restablecer las concesiones de la clave o de volver a activar la clave que estaba desactivada. Sin embargo, la eliminación de una clave KMS administrada por el cliente es irreversible. Una vez que se elimina una clave, ya no puede acceder a los libros mayores que están protegidos con ella y los datos se vuelven irrecuperables permanentemente.

    • Inaccesible AWS KMS key: la fecha y la hora, en formato de época, en las que la clave KMS quedó inaccesible por primera vez, en caso de error.

      Si se puede acceder a la clave KMS, este valor no aparece definido.

    Para obtener más información, consulte Cifrado en reposo en Amazon QLDB.

nota

Tras crear un libro mayor de QLDB, estará listo para su uso cuando su estado pase de CREATING a ACTIVE.

Para describir un libro mayor utilizando el AWS SDK para Java
  1. Cree una instancia de la clase AmazonQLDB. También puede usar la misma instancia del cliente de AmazonQLDB instanciada para la solicitud CreateLedger.

  2. Cree una instancia de la clase DescribeLedgerRequest y proporcione el nombre del libro mayor que desea describir.

  3. Ejecute el método describeLedger proporcionando el objeto de solicitud como parámetro.

  4. La solicitud describeLedger devuelve un objeto DescribeLedgerResult que contiene información actual sobre el libro mayor.

En el siguiente ejemplo de código se ponen en práctica los pasos anteriores. Puede llamar al método describeLedger del cliente para obtener información sobre el libro mayor en cualquier momento.

ejemplo
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());

Descripción del libro mayor vehicle-registration que acaba de crear.

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

Actualización de un libro mayor

Actualmente, la operación UpdateLedger permite cambiar los siguientes parámetros de configuración de un libro mayor existente:

  • Protección de eliminación: la marca que impide que un usuario elimine un libro mayor. Si esta característica está habilitada, deberá deshabilitarla antes configurando el indicador como false para poder eliminar el libro mayor.

    Si no define este parámetro, no se efectuarán cambios en la configuración de protección contra eliminación del libro mayor.

  • AWS KMS key— La clave in AWS Key Management Service (AWS KMS) que se utilizará para cifrar los datos en reposo. Si no define este parámetro, no se efectuarán cambios en la clave KMS del libro mayor.

    nota

    Amazon QLDB lanzó el soporte para la AWS KMS keys gestión de clientes el 22 de julio de 2021. Todos los libros de contabilidad que se hayan creado antes del lanzamiento están protegidos de forma Claves propiedad de AWS predeterminada, pero actualmente no son aptos para el cifrado en reposo con claves administradas por el cliente.

    Puede ver la hora de creación de su libro mayor en la consola de QLDB.

    Utilice una de las siguientes opciones:

    • AWS clave KMS propia: usa una clave KMS que sea de tu propiedad y que gestione AWS en tu nombre. Para usar este tipo de clave, especifique la cadena AWS_OWNED_KMS_KEY de este parámetro. Esta opción no requiere ninguna configuración adicional.

    • Clave KMS administrada por el cliente: utilice una clave KMS de cifrado simétrico en la cuenta que ha creado, que posee y que administra. QLDB no admite claves asimétricas.

      Esta opción requiere que cree una clave KMS o use una clave existente en su cuenta. Para obtener instrucciones sobre cómo crear una clave administrada, consulte Creating symmetric encryption KMS keys en la Guía para desarrolladores de AWS Key Management Service .

      Puede especificar una clave KMS administrada por el cliente utilizando un ID, un alias o el Nombre de recurso de Amazon (ARN). Para obtener más información, consulta los identificadores clave (KeyId) en la Guía para AWS Key Management Service desarrolladores.

      nota

      No se admiten claves entre regiones. La clave KMS especificada debe estar en la misma Región de AWS que el libro mayor.

    Los cambios de clave en QLDB son asíncronos. Mientras se procesa el cambio de clave, el registro es totalmente accesible sin ningún impacto en el rendimiento.

    Puede alternar claves con tanta frecuencia como sea necesario, pero la cantidad de tiempo que tarda en actualizarse una clave varía dependiendo del tamaño del libro mayor. Puede usar la operación DescribeLedger para comprobar el estado del cifrado en reposo.

    Para obtener más información, consulte Cifrado en reposo en Amazon QLDB.

El resultado de UpdateLedger tiene el mismo formato que el de CreateLedger;

Para actualizar un libro mayor mediante el AWS SDK para Java
  1. Cree una instancia de la clase AmazonQLDB.

  2. Cree una instancia de la clase UpdateLedgerRequest para proporcionar la información de solicitud.

    Debe proporcionar el nombre del libro mayor junto con un nuevo valor booleano para protegerlo de la eliminación, o bien un nuevo valor de cadena para la clave KMS.

  3. Ejecute el método updateLedger proporcionando el objeto de solicitud como parámetro.

En el siguiente ejemplo de código se ponen en práctica los pasos anteriores. La solicitud updateLedger devuelve un objeto UpdateLedgerResult que contiene información actualizada sobre el libro mayor.

ejemplo – Deshabilitar la protección contra la eliminación
AmazonQLDB client = AmazonQLDBClientBuilder.standard().build(); UpdateLedgerRequest request = new UpdateLedgerRequest() .withName(ledgerName) .withDeletionProtection(false); UpdateLedgerResult result = client.updateLedger(request);
ejemplo – Utilizar una clave KMS administrada por el 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);
ejemplo — Utilice una clave AWS KMS propia
AmazonQLDB client = AmazonQLDBClientBuilder.standard().build(); UpdateLedgerRequest request = new UpdateLedgerRequest() .withName(ledgerName) .withKmsKey("AWS_OWNED_KMS_KEY") UpdateLedgerResult result = client.updateLedger(request);

Si su libro mayor de vehicle-registration tiene la protección contra eliminación habilitada, primero debe desactivarla para poder eliminarlo.

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

También puede cambiar la configuración de cifrado en reposo del libro mayor para usar una clave KMS gestionada por el cliente.

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

O bien, puede cambiar la configuración de cifrado en reposo para usar una clave AWS KMS propia.

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

Actualización del modo de permisos de un libro mayor

La operación UpdateLedgerPermissionsMode permite cambiar el modo de permisos de un libro mayor existente. Seleccione una de las siguientes opciones:

  • Permitir todo: un modo de permisos heredado que habilita el control de acceso con granularidad de la API para los libros mayores.

    Este modo permite a los usuarios que tengan el permiso de API SendCommand para este libro mayor poner en marcha todos los comandos de PartiQL (por lo tanto, ALLOW_ALL) en cualquier tabla del libro mayor especificado. Este modo no tendrá en cuenta las políticas de permisos de IAM de la tabla o comando que cree para el libro mayor.

  • Estándar: (recomendado) un modo de permisos que habilita el control de acceso con granularidad más precisa para libros mayores, tablas y comandos de PartiQL. Recomendamos encarecidamente usar este modo de permisos para maximizar la seguridad de los datos del libro mayor.

    De forma predeterminada, este modo deniega todas las solicitudes para poner en marcha cualquier comando de PartiQL en tablas de este libro mayor. Para permitir los comandos de PartiQL, debe crear políticas de permisos de IAM para recursos de tablas y acciones de PartiQL específicos, además del permiso de API SendCommand para el libro mayor. Para obtener más información, consulte Introducción al modo de permisos estándar en Amazon QLDB.

importante

Antes de cambiar al modo de permisos STANDARD, deberá crear todas las políticas de IAM y etiquetas de tabla necesarias para evitar interrupciones en el trabajo de los usuarios. Para obtener más información, consulte Migración al modo de permisos estándar.

Para actualizar el modo de permisos de un libro mayor mediante el AWS SDK para Java
  1. Cree una instancia de la clase AmazonQLDB.

  2. Cree una instancia de la clase UpdateLedgerPermissionsModeRequest para proporcionar la información de solicitud.

    Debe proporcionar el nombre del libro mayor junto con un nuevo valor de cadena para el modo de permisos.

  3. Ejecute el método updateLedgerPermissionsMode proporcionando el objeto de solicitud como parámetro.

En el siguiente ejemplo de código se ponen en práctica los pasos anteriores. La solicitud updateLedgerPermissionsMode devuelve un objeto UpdateLedgerPermissionsModeResult que contiene información actualizada sobre el libro mayor.

ejemplo – Asigne el modo de permisos estándar
AmazonQLDB client = AmazonQLDBClientBuilder.standard().build(); UpdateLedgerPermissionsModeRequest request = new UpdateLedgerPermissionsModeRequest() .withName(ledgerName) .withPermissionsMode(PermissionsMode.STANDARD); UpdateLedgerPermissionsModeResult result = client.updateLedgerPermissionsMode(request);

Asigne el modo de permisos STANDARD a su libro mayor vehicle-registration.

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

Migración al modo de permisos estándar

Para migrar al modo de permisos STANDARD, le recomendamos analizar sus patrones de acceso a QLDB y añadir políticas de IAM que concedan a los usuarios los permisos adecuados para acceder a sus recursos.

Antes de cambiar al modo de permisos STANDARD, deberá crear todas las políticas de IAM y etiquetas de tabla necesarias. De lo contrario, el cambio del modo de permisos podría interrumpir el trabajo de los usuarios hasta que cree las políticas de IAM correctas o restablezca el modo de permisos a ALLOW_ALL. Para obtener información sobre la creación de estas políticas, consulte Introducción al modo de permisos estándar en Amazon QLDB.

También puede utilizar una política AWS gestionada para conceder acceso total a todos los recursos de la QLDB. Las políticas gestionadas AmazonQLDBFullAccess y AmazonQLDBConsoleFullAccess incluyen todas las acciones de QLDB, incluidas todas las acciones de PartiQL. Adjuntar una de estas políticas a una entidad principal equivale a conceder el modo de permisos ALLOW_ALL a esa entidad principal. Para obtener más información, consulte AWS políticas gestionadas para Amazon QLDB.

Eliminación de un libro mayor

Use la operación DeleteLedger para eliminar un libro mayor y todo su contenido. La eliminación de un libro mayor es una operación irrecuperable.

Si la protección contra eliminación está habilitada para su libro mayor, primero debe desactivarla para poder eliminar el libro mayor.

Cuando se emite una solicitud DeleteLedger, el estado del libro mayor cambia de ACTIVE a DELETING. La eliminación del libro mayor puede tardar un tiempo, en función de la cantidad de almacenamiento utilizado. Cuando la operación DeleteLedger concluya, el libro mayor ya no existirá en QLDB.

Para eliminar un libro mayor mediante el AWS SDK para Java
  1. Cree una instancia de la clase AmazonQLDB.

  2. Cree una instancia de la clase DeleteLedgerRequest y proporcione el nombre del libro mayor que desea eliminar.

  3. Ejecute el método deleteLedger proporcionando el objeto de solicitud como parámetro.

En el siguiente ejemplo de código se ponen en práctica los pasos anteriores.

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

Elimine su libro mayor de vehicle-registration.

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

Enumerar libros mayores

La ListLedgers operación devuelve información resumida de todos los libros de QLDB para la región y la corriente. Cuenta de AWS

Para enumerar los libros de contabilidad de su cuenta, utilice el AWS SDK para Java
  1. Cree una instancia de la clase AmazonQLDB.

  2. Cree una instancia de la clase ListLedgersRequest.

    Si ha recibido un valor de NextToken en la respuesta de una llamada ListLedgers previa, debe proporcionarlo en esta solicitud para pasar a la siguiente página de resultados.

  3. Ejecute el método listLedgers proporcionando el objeto de solicitud como parámetro.

  4. La solicitud listLedgers devuelve un objeto ListLedgersResult. Este objeto tiene una lista de objetos LedgerSummary y un token de paginación que indica si hay más resultados disponibles:

    • Si NextToken está vacío, se ha procesado la última página de resultados y no hay más resultados.

    • Si NextToken no está vacío, hay más resultados disponibles. Para recuperar la siguiente página de resultados, use el valor de NextToken en una llamada posterior a ListLedgers.

En el siguiente ejemplo de código se ponen en práctica los pasos anteriores.

ejemplo
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);

Enumere todos los libros de contabilidad actuales Cuenta de AWS y de la región.

ejemplo
aws qldb list-ledgers