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
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
Temas
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 enfalse
. -
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
-
Cree una instancia de la clase
AmazonQLDB
. -
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.
-
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
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
-
Cree una instancia de la clase
AmazonQLDB
. También puede usar la misma instancia del cliente deAmazonQLDB
instanciada para la solicitudCreateLedger
. -
Cree una instancia de la clase
DescribeLedgerRequest
y proporcione el nombre del libro mayor que desea describir. -
Ejecute el método
describeLedger
proporcionando el objeto de solicitud como parámetro. -
La solicitud
describeLedger
devuelve un objetoDescribeLedgerResult
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
-
Cree una instancia de la clase
AmazonQLDB
. -
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.
-
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
-
Cree una instancia de la clase
AmazonQLDB
. -
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.
-
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
-
Cree una instancia de la clase
AmazonQLDB
. -
Cree una instancia de la clase
DeleteLedgerRequest
y proporcione el nombre del libro mayor que desea eliminar. -
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
-
Cree una instancia de la clase
AmazonQLDB
. -
Cree una instancia de la clase
ListLedgersRequest
.Si ha recibido un valor de
NextToken
en la respuesta de una llamadaListLedgers
previa, debe proporcionarlo en esta solicitud para pasar a la siguiente página de resultados. -
Ejecute el método
listLedgers
proporcionando el objeto de solicitud como parámetro. -
La solicitud
listLedgers
devuelve un objetoListLedgersResult
. Este objeto tiene una lista de objetosLedgerSummary
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 deNextToken
en una llamada posterior aListLedgers
.
-
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