Operaciones básicas para los 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 para los libros mayores de Amazon QLDB

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

En los temas siguientes se proporcionan ejemplos de códigos cortos que muestran pasos comunes para las operaciones de libro mayor mediante elAWS SDK for Javay laAWS CLI.

Para obtener ejemplos de código que demuestran estas operaciones en una aplicación de ejemplo completa, consulte lo siguienteIntroducción al conductorTutoriales de y GitHub repositorios:

Creación de un libro mayor

UsarCreateLedgerpara crear un libro mayor en suAWSaccount. Debe proporcionar la siguiente información:

  • Nombre de contabilidad— El nombre del libro mayor que desea crear en su cuenta. El nombre debe ser único entre todos los libros mayores delAWSRegión .

    Las restricciones de nomenclatura para nombres de libros mayores se definen enCuotas y límites de Amazon QLDB.

  • Modo 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 permite el control de acceso con granularidad a nivel de API para libros mayores.

      Este modo permite a los usuarios que tienen elSendCommandPermiso de API para que este libro mayor ejecute todos los comandos PartiQL (por lo tanto,ALLOW_ALL) en cualquier tabla del libro mayor especificado. Este modo no tiene en cuenta las políticas de permisos de IAM a nivel de tabla o de comandos que cree para el libro mayor.

    • estándar— (Recomendado) Un modo de permisos que permite el control de acceso con mayor granularidad para libros mayores, tablas y comandos PartiQL. Recomendamos encarecidamente utilizar este modo de permisos para maximizar la seguridad de los datos del libro mayor.

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

  • Deletion protection (Protección contra eliminación)— (Opcional) El indicador que impide que un usuario elimine un libro mayor. Si no lo especifica durante la creación del libro mayor, esta característica está habilitada (true) de forma predeterminada.

    Si la protección contra eliminación está habilitada, primero debe deshabilitarla para poder eliminar el libro mayor. Puede deshabilitarlo mediante laUpdateLedgerpara establecer la marca enfalse.

  • AWS KMS key— (Opcional) La clave enAWS Key Management Service(AWS KMS) para el cifrado de datos en reposo. Elija uno de los siguientes tipos deAWS KMS keys:

    • AWSClave KMS de propiedad— Utilice una clave KMS que posee y administraAWSen su nombre.

      Si no define este parámetro durante la creación del libro mayor, el libro mayor utiliza este tipo de clave de forma predeterminada. También puede utilizar la cadenaAWS_OWNED_KMS_KEYpara especificar este tipo de clave. Esta opción no requiere configuración adicional.

    • Clave KMS administrada por el cliente— Utilice una clave KMS de cifrado simétrica en su cuenta de, que usted ha creado, posee y administra. QLDB no admiteClaves asimétricas.

      Esta opción requiere que crees una clave KMS o uses una clave existente en tu cuenta. Para obtener instrucciones sobre cómo crear una clave administrada por el cliente, consulteCreación de claves KMS con cifrado simétricoen laAWS Key Management ServiceGuía para desarrolladores.

      Puede especificar una clave KMS administrada por el cliente mediante un ID, un alias o un nombre de recurso de Amazon (ARN). Para obtener más información, consulteIdentificadores de clave (KeyId)en laAWS Key Management ServiceGuía para desarrolladores.

      nota

      No se admiten claves entre regiones. La clave KMS especificada debe estar en la mismaAWSRegión como libro mayor.

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

  • Etiquetas— (Opcional) Añadir metadatos al libro mayor asociando las etiquetas como pares de clave-valor. Puede añadir etiquetas al libro mayor para organizarlas e identificarlas mejor. Para obtener más información, consulte Etiquetado de recursos de Amazon QLDB.

El libro mayor no estará listo para usarse hasta que QLDB lo haya creado y haya establecido su estado enACTIVE.

Para crear un libro de contabilidad mediante laAWS 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.

LacreateLedgerrequest devuelve unCreateLedgerResultobjeto que tiene información sobre el libro mayor. Consulte la siguiente sección para ver un ejemplo de cómo utilizar elDescribeLedgerpara comprobar el estado del libro mayor después de crearlo.

En los siguientes ejemplos se ponen en marcha los pasos anteriores.

ejemplo — Utilizar 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 utiliza la siguiente configuración predeterminada si no los especifica:

  • Protección contra eliminación: habilitada (true).

  • Clave KMS:AWSClave KMS de propiedad.

ejemplo — Desactiva la protección contra eliminación, usa una clave KMS administrada por el cliente y adjunta 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);

Crear un nuevo libro de contabilidad llamadovehicle-registrationutilizando los valores predeterminados de configuración.

ejemplo

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

El libro mayor utiliza la siguiente configuración predeterminada si no los especifica:

  • Protección contra eliminación: habilitada (true).

  • Clave KMS:AWSClave KMS de propiedad.

O bien, cree un nuevo libro mayor denominadovehicle-registrationcon la protección contra eliminación deshabilitada, con una clave KMS administrada por el cliente especificada y con etiquetas especificadas.

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 utilizar unaAWS CloudFormationplantilla para crear libros mayores. Para obtener más información, consulte laAWS::QLDB::Ledgerrecurso en elAWS CloudFormationGuía del usuario de.

Descripción de un libro de contabilidad

UsarDescribeLedgerpara ver detalles de 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 contabilidad— El nombre del libro mayor que desea describir.

  • ARN— El nombre de recurso de Amazon (ARN) del libro mayor en el siguiente formato.

    arn:aws:qldb:aws-region:account-id:ledger/ledger-name
  • Deletion protection (Protección contra eliminación): indicador que indica si la función de protección contra eliminación está habilitada.

  • Fecha y hora de creación— Es la fecha y la hora, en formato de tiempo de época, en que se creó el libro mayor.

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

    • CREATING

    • ACTIVE

    • DELETING

    • DELETED

  • Modo Permisos— El modo de permisos que se asigna al libro mayor. Puede ser uno de los siguientes valores:

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

    • STANDARD: modo de permisos que permite el control de acceso con mayor granularidad para libros mayores, tablas y comandos PartiQL.

  • Descripción de cifrado— Información sobre el cifrado de datos en reposo en el libro mayor. Esto incluye los elementos siguientes:

    • AWS KMS keyARN— El ARN de la clave KMS administrada por el cliente que utiliza el libro mayor para el cifrado en reposo. Si no se ha definido, el libro mayor utiliza unAWSClave KMS de propiedad para cifrado.

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

      • ENABLED— El cifrado está totalmente habilitado con la clave especificada.

      • UPDATING— El cambio de clave especificado se está procesando activamente.

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

      • KMS_KEY_INACCESSIBLE— No se puede acceder a la clave KMS administrada por el cliente especificada y el libro mayor está deteriorado. La clave se ha deshabilitado o eliminado, o bien se han revocado las concesiones de la clave. Cuando un libro mayor se ve afectado, no es accesible y no acepta ninguna solicitud de lectura o escritura.

        Un libro mayor deteriorado vuelve automáticamente a un estado activo después de restaurar las concesiones de la clave o después de volver a habilitar la clave deshabilitada. Sin embargo, eliminar una clave KMS administrada por el cliente es irreversible. Una vez que se elimina una clave, ya no se puede acceder a los libros mayores que están protegidos con ella y los datos se vuelven irrecuperables de forma permanente.

    • InaccesibleAWS KMS key— Es la fecha y la hora en que se hizo inaccesible por primera vez la clave KMS en que se produjo un error.

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

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

nota

Después de crear un libro mayor QLDB, estará listo para usarse cuando su estado pase deCREATINGaACTIVE.

Para describir un libro de contabilidad mediante laAWS SDK for Java

  1. Cree una instancia de la clase AmazonQLDB. O bien, puede utilizar la misma instancia de laAmazonQLDBcliente que ha creado una instancia para elCreateLedgerrequest.

  2. Cree una instancia de laDescribeLedgerRequesty proporcione el nombre del libro mayor que desea describir.

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

  4. LadescribeLedgerrequest devuelve unDescribeLedgerResultobjeto que tiene información actual sobre el libro mayor.

En el siguiente ejemplo de código se ponen en práctica los pasos anteriores. Puede llamar aldescribeLedgerdel 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());

Describir lavehicle-registrationlibro de contabilidad que acaba de crear.

ejemplo

aws qldb describe-ledger --name vehicle-registration

Actualización de un libro mayor

LaUpdateLedgeractualmente permite cambiar los siguientes valores de configuración de un libro mayor existente:

  • Deletion protection (Protección contra eliminación)— El indicador que impide que un usuario elimine un libro mayor. Si esta función está habilitada, primero debe deshabilitarla estableciendo el indicador enfalseantes de poder eliminar el libro mayor.

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

  • AWS KMS key— La clave enAWS Key Management Service(AWS KMS) para el cifrado de datos en reposo. Si no define este parámetro, no se realizarán cambios en la clave KMS del libro mayor.

    nota

    Amazon QLDB lanzó soporte para administración de clientesAWS KMS keysel 22 de julio de 2021. Los libros mayores creados antes del lanzamiento están protegidos porClaves propiedad de AWSde forma predeterminada, pero actualmente no son aptos para el cifrado en reposo mediante claves administradas por el cliente.

    Utilice una de las siguientes opciones:

    • AWSClave KMS de propiedad— Utilice una clave KMS que posee y administraAWSen su nombre. Para utilizar este tipo de clave, especifique la cadenaAWS_OWNED_KMS_KEYpara este parámetro. Esta opción no requiere configuración adicional.

    • Clave KMS administrada por el cliente— Utilice una clave KMS de cifrado simétrica en su cuenta de, que usted ha creado, posee y administra. QLDB no admiteClaves asimétricas.

      Esta opción requiere que crees una clave KMS o uses una clave existente en tu cuenta. Para obtener instrucciones sobre cómo crear una clave administrada por el cliente, consulteCreación de claves KMS con cifrado simétricoen laAWS Key Management ServiceGuía para desarrolladores.

      Puede especificar una clave KMS administrada por el cliente mediante un ID, un alias o un nombre de recurso de Amazon (ARN). Para obtener más información, consulteIdentificadores de clave (KeyId)en laAWS Key Management ServiceGuía para desarrolladores.

      nota

      No se admiten claves entre regiones. La clave KMS especificada debe estar en la mismaAWSRegión como libro mayor.

    Los cambios clave en QLDB son asíncronos. El libro mayor es totalmente accesible sin ningún impacto en el rendimiento mientras se procesa el cambio clave.

    Puede cambiar las teclas tantas veces como sea necesario, pero el tiempo que lleva actualizar una clave varía según el tamaño del libro mayor. Puede utilizar elDescribeLedgerpara comprobar el estado de encriptación 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 de contabilidad mediante laAWS 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 la protección contra 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 los siguientes ejemplos de código se ponen en marcha los pasos anteriores. LaupdateLedgerrequest devuelve unUpdateLedgerResultobjeto que tiene información actualizada sobre el libro mayor.

ejemplo : Deshabilita 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 — UsarUse unAWSClave KMS de propiedad

AmazonQLDB client = AmazonQLDBClientBuilder.standard().build(); UpdateLedgerRequest request = new UpdateLedgerRequest() .withName(ledgerName) .withKmsKey("AWS_OWNED_KMS_KEY") UpdateLedgerResult result = client.updateLedger(request);

Si las recetasvehicle-registrationEl libro mayor tiene habilitada la protección contra eliminación, primero debe deshabilitarla para poder eliminarla.

ejemplo

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

También puede cambiar la configuración de cifrado del libro mayor en reposo para utilizar una clave KMS administrada 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 unAWSClave KMS de propiedad.

ejemplo

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

Actualización de un modo de permisos de libro mayor

LaUpdateLedgerPermissionsModele 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 permite el control de acceso con granularidad a nivel de API para libros mayores.

    Este modo permite a los usuarios que tienen elSendCommandPermiso de API para que este libro mayor ejecute todos los comandos PartiQL (por lo tanto,ALLOW_ALL) en cualquier tabla del libro mayor especificado. Este modo no tiene en cuenta las políticas de permisos de IAM a nivel de tabla o de comandos que cree para el libro mayor.

  • estándar— (Recomendado) Un modo de permisos que permite el control de acceso con mayor granularidad para libros mayores, tablas y comandos PartiQL. Recomendamos encarecidamente utilizar este modo de permisos para maximizar la seguridad de los datos del libro mayor.

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

importante

Antes de cambiar alSTANDARDmodo permisos, primero debe crear todas las políticas y etiquetas de tabla de IAM necesarias para evitar la interrupción de los usuarios. Para obtener más información, proceda aMigración al modo de permisos estándar.

Para actualizar un modo de permisos de libro mayor mediante elAWS 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 los siguientes ejemplos de código se ponen en marcha los pasos anteriores. LaupdateLedgerPermissionsModerequest devuelve unUpdateLedgerPermissionsModeResultobjeto que tiene información actualizada sobre el libro mayor.

ejemplo — Asignar 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 laSTANDARDmodo de permisos para tuvehicle-registrationlibro mayor.

ejemplo

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

Migración al modo de permisos estándar

Para migrar alSTANDARDmodo permisos, recomendamos analizar los patrones de acceso de QLDB y agregar políticas de IAM que otorguen a los usuarios los permisos adecuados para acceder a sus recursos.

Antes de cambiar alSTANDARDmodo permisos, primero debe crear todas las políticas y etiquetas de tabla de IAM necesarias. De lo contrario, cambiar el modo de permisos puede interrumpir a los usuarios hasta que cree las políticas de IAM correctas o vuelva a revertir el modo de permisos aALLOW_ALL. Para obtener más información sobre cómo crear estas políticas, consulteIntroducción al modo de permisos estándar en Amazon QLDB.

También puede utilizar unaAWSpolítica administrada para conceder acceso completo a todos los recursos de QLDB. LaAmazonQLDBFullAccessyAmazonQLDBConsoleFullAccesslas políticas gestionadas incluyen todas las acciones QLDB, incluidas todas las acciones partiQL. Adjuntar una de estas políticas a un principal equivale a laALLOW_ALLmodo de permisos para ese principal. Para obtener más información, consulte AWSPolíticas administradas por para Amazon QLDB.

Eliminación de un libro mayor

UsarDeleteLedgerpara 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 el libro mayor, primero debe deshabilitarla para poder eliminarlo.

Cuando emite unDeleteLedgersolicitud, el estado del libro mayor cambia deACTIVEaDELETING. Puede que el libro mayor tarde un tiempo en eliminarse, según la cantidad de almacenamiento que utilice. Cuando laDeleteLedgerLa operación concluya, el libro mayor ya no existirá en QLDB.

Para eliminar un libro de contabilidad mediante laAWS SDK for Java

  1. Cree una instancia de la clase AmazonQLDB.

  2. Cree una instancia de laDeleteLedgerRequesty 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);

Eliminar suvehicle-registrationlibro mayor.

ejemplo

aws qldb delete-ledger --name vehicle-registration

Contabilidad de listado

LaListLedgersla operación devuelve información resumida de todos los libros mayores QLDB para el actualAWScuenta y región.

Para listar libros mayores en su cuenta mediante elAWS SDK for Java

  1. Cree una instancia de la clase AmazonQLDB.

  2. Cree una instancia de la clase ListLedgersRequest.

    Si has recibido un valor paraNextTokenen la respuesta de un anteriorListLedgerscall, debe proporcionar ese valor en esta solicitud. Esto le permite obtener la siguiente página de resultados.

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

  4. LalistLedgersrequest devuelve unListLedgersResultObjeto. Este objeto tiene una lista deLedgerSummaryobjetos y un token de paginación que indica si hay más resultados disponibles:

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

    • SiNextTokenno está vacío, hay más resultados disponibles. Para recuperar la siguiente página de resultados, utilice el valor deNextTokenen un subsiguienteListLedgersLlame a.

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

Enumerar todos los libros de contabilidad del actualAWScuenta y región.

ejemplo

aws qldb list-ledgers