Operaciones básicas para los libros de QLDB contabilidad de Amazon - Base de datos Amazon Quantum Ledger (AmazonQLDB)

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 para los libros de QLDB contabilidad de Amazon

importante

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

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

En los temas siguientes se proporcionan ejemplos breves de código que muestran los pasos habituales de las operaciones contables que utilizan el AWS SDK for Java y el. 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 en 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 permite el control de acceso con una granularidad de API nivel de detalle para los libros de contabilidad.

      Este modo permite a los usuarios que tienen SendCommand API permiso para este libro mayor ejecutar todos los comandos PartiQL (por lo tantoALLOW_ALL,) en cualquier tabla del libro mayor especificado. Este modo ignora las políticas de IAM permisos a nivel de tabla o de comando que se creen 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 PartiQL, debes crear políticas de IAM permisos para recursos de tabla y acciones PartiQL específicos, además del SendCommand API permiso para el libro mayor. Para obtener más información, consulte Cómo empezar con el 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 KMSclave propia: usa una KMS clave que sea de tu propiedad y que esté gestionada por ti AWS .

      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.

    • KMSClave gestionada por el cliente: utilice una KMS clave de cifrado simétrica en su cuenta que usted cree, posea y gestione. QLDBno admite claves asimétricas.

      Esta opción requiere que crees una KMS clave o utilices una clave existente en tu cuenta. Para obtener instrucciones sobre cómo crear una clave administrada por el cliente, consulte Creación de KMS claves de cifrado simétricas en la Guía para AWS Key Management Service desarrolladores.

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

      nota

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

    Para obtener más información, consulte El 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 los recursos de Amazon QLDB.

El libro mayor no estará listo para su uso hasta que lo QLDB cree y establezca su estado en. ACTIVE

Para crear un libro mayor mediante el AWS SDK for 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).

  • KMSclave: KMS clave AWS propia.

ejemplo — Desactive la protección contra la eliminación, utilice una KMS clave gestionada 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).

  • KMSclave: AWS KMS clave propia.

O bien, cree un nuevo libro mayor vehicle-registration con la protección de borrado desactivada, con una KMS clave específica gestionada por el cliente y con 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 recurso AWS:QLDB: :Ledger en 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 del recurso de Amazon (ARN) del 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 permite el control de acceso con una granularidad de API nivel de detalle para los libros de contabilidad.

    • 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— La ARN de la KMS clave gestionada por el cliente que el libro mayor utiliza para el cifrado en reposo. Si no está definido, el libro mayor utiliza una KMS clave propia para el AWS cifrado.

    • 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 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 KMS clave gestionada por el cliente especificada 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, eliminar una KMS clave gestionada 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 KMS clave quedó inaccesible por primera vez, en caso de error.

      Esto no está definido si se puede acceder a la KMS clave.

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

nota

Tras crear un QLDB libro mayor, estará listo para su uso cuando su estado cambie de aCREATING. ACTIVE

Para describir un libro mayor mediante el AWS SDK for 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 realizará ningún cambio en la KMS clave del libro mayor.

    nota

    Amazon QLDB lanzó el soporte para la gestión de clientes AWS KMS keys 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 gestionadas por el cliente.

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

    Utilice una de las siguientes opciones:

    • AWS KMSclave propia: utilice una KMS clave que sea de su propiedad y que esté AWS gestionada por usted. 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.

    • KMSClave gestionada por el cliente: utilice una KMS clave de cifrado simétrica en su cuenta que usted cree, posea y gestione. QLDBno admite claves asimétricas.

      Esta opción requiere que crees una KMS clave o utilices una clave existente en tu cuenta. Para obtener instrucciones sobre cómo crear una clave administrada por el cliente, consulte Creación de KMS claves de cifrado simétricas en la Guía para AWS Key Management Service desarrolladores.

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

      nota

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

    Los cambios clave 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 El 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 for 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 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 — Utilice una clave gestionada por el cliente KMS
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 AWS KMS clave 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 utilizar una KMS clave 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 utilizar una KMS clave AWS 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 permite controlar el acceso con una granularidad de API nivel de detalle para los libros de contabilidad.

    Este modo permite a los usuarios que tienen SendCommand API permiso para este libro mayor ejecutar todos los comandos PartiQL (por lo tantoALLOW_ALL,) en cualquier tabla del libro mayor especificado. Este modo ignora las políticas de IAM permisos a nivel de tabla o de comando que se creen 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 PartiQL, debes crear políticas de IAM permisos para recursos de tabla y acciones PartiQL específicos, además del SendCommand API permiso para el libro mayor. Para obtener más información, consulte Cómo empezar con el modo de permisos estándar en Amazon QLDB.

importante

Antes de cambiar al modo de STANDARD permisos, primero debe crear todas IAM las políticas y etiquetas de tabla necesarias para evitar interrumpir a 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 for 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 STANDARD permisos, te recomendamos analizar tus patrones de QLDB acceso y añadir IAM políticas que concedan a los usuarios los permisos adecuados para acceder a sus recursos.

Antes de cambiar al modo de STANDARD permisos, primero debe crear todas IAM las políticas y etiquetas de tabla necesarias. De lo contrario, cambiar el modo de permisos puede interrumpir a los usuarios hasta que cree las IAM políticas correctas o restablezca el modo de permisos. ALLOW_ALL Para obtener información sobre la creación de estas políticas, consulte Cómo empezar con el modo de permisos estándar en Amazon QLDB.

También puedes usar una política AWS administrada para conceder acceso total a todos los QLDB recursos. Las políticas AmazonQLDBConsoleFullAccess gestionadas AmazonQLDBFullAccess y las políticas incluyen todas QLDB las acciones, incluidas todas las acciones 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 DeleteLedger operación finaliza, el libro mayor ya no existe en. QLDB

Para eliminar un libro mayor mediante el AWS SDK for 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 contabilidad actuales Cuenta de AWS y de la región.

Para incluir los libros de contabilidad de su cuenta, utilice el AWS SDK for 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