Operaciones básicas de libros mayores de Amazon QLDB - Amazon Quantum Ledger Database (Amazon QLDB)
Creación de un libro mayorDescripción de un libro mayorActualización de un libro mayorActualizar el modo de permisos de un libro mayorEliminación de un libro mayorEnumerar libros mayores

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

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

Los siguientes temas incluyen ejemplos de código corto que muestran los pasos habituales de las operaciones de libro mayor en AWS SDK for Java y la AWS CLI.

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

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. Elija 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 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:

    • Clave KMS propiedad de AWS: utilice una clave KMS propiedad de AWS, que también la administra 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 la 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 Creación de claves KMS de cifrado simétrica 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, consulte Identificadores de clave (KeyId) en la Guía para desarrolladores de AWS Key Management Service.

      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 utilizando 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).

  • Clave KMS: clave KMS propiedad de AWS.

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: clave KMS propiedad de AWS.

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 recurso AWS::QLDB::Ledger en la Guía de usuario de AWS CloudFormation.

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 siguientes valores:

    • CREATING

    • ACTIVE

    • DELETING

    • DELETED

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

    • 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:

    • ARN de AWS KMS key: el ARN de la clave KMS administrada por el cliente que emplea el libro mayor para el cifrado en reposo. Si no se ha definido, el libro mayor emplea una clave KMS propiedad de AWS para el cifrado.

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

      • 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: en caso de error, la fecha y hora, en formato de valor de tiempo, en las que la clave KMS se ha vuelto inaccesible por primera vez.

      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 mediante 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 función 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 de AWS Key Management Service (AWS KMS) que se usará 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 AWS KMS keys administrado por el cliente el 22 de julio de 2021. Todos los libros mayores creados antes del lanzamiento están protegidos por Claves propiedad de AWS de forma predeterminada, pero actualmente no es posible cifrar sus datos 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:

    • Clave KMS propiedad de AWS: utilice una clave KMS propiedad de AWS, que también la administra en su 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 la 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 Creación de claves KMS de cifrado simétrica 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, consulte Identificadores de clave (KeyId) en la Guía para desarrolladores de AWS Key Management Service.

      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 utilizando 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 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 KSM 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 – Use una clave KMS propiedad de AWS
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 KMS propiedad de AWS.

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

Actualizar el modo de permisos de un libro mayor

La operación UpdateLedgerPermissionsMode permite cambiar el modo de permisos de un libro mayor existente. Elija 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 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 Migrar al modo de permisos estándar.

Para actualizar el modo de permisos de un libro mayor mediante 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

Migrar 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 la política administrada de AWS para conceder acceso completo a todos los recursos de 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 utilizando 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 operación ListLedgers devuelve información resumida de todos los libros de QLDB en la región y Cuenta de AWS actuales.

Para enumerar los libros mayores de su cuenta usando 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 mayores en la región y Cuenta de AWS actuales.

ejemplo 
aws qldb list-ledgers