Contenido del diario en Amazon QLDB

En Amazon QLDB, un diario es un registro transaccional inmutable que almacena el historial completo y verificable de todos los cambios en los datos. El diario es solamente un anexo, y está compuesto por un conjunto de bloques secuenciados y encadenados que contienen los datos confirmados y otros metadatos del sistema. QLDB escribe un bloque encadenado en el diario de una transacción.

En esta sección se proporciona un ejemplo de un bloque de diarios con datos de muestra y se describe el contenido del bloque.

Ejemplo de bloque

Un bloque de diarios contiene metadatos de transacciones junto con entradas que representan las revisiones del documento confirmadas en la transacción, así como las instrucciones PartiQL que las han confirmado.

El siguiente es un ejemplo de un bloque con datos de muestra.

nota

Este ejemplo de bloque se ofrece solo con fines informativos. Los hash que se muestran no son valores hash calculados reales.

{
  blockAddress:{
    strandId:"4o5UuzWSW5PIoOGm5jPA6J",
    sequenceNo:25
  },
  transactionId:"3gtB8Q8dfIMA8lQ5pzHAMo",
  blockTimestamp:2022-06-08T18:46:46.512Z,
  blockHash:{{QS5lJt8vRxT30L9OGL5oU1pxFTe+UlEwakYBCrvGQ4A=}},
  entriesHash:{{buYYc5kV4rrRtJAsrIQnfnhgkzfQ8BKjI0C2vFnYQEw=}},
  previousBlockHash:{{I1UKRIWUgkM1X6042kcoZ/eN1rn0uxhDTc08zw9kZ5I=}},
  entriesHashList:[
    {{BUCXP6oYgmug2AfPZcAZup2lKolJNTbTuV5RA1VaFpo=}},
    {{cTIRkjuULzp/4KaUEsb/S7+TG8FvpFiZHT4tEJGcANc=}},
    {{3aktJSMyJ3C5StZv4WIJLu/w3D8mGtduZvP0ldKUaUM=}},
    {{GPKIJ1+o8mMZmPj/35ZQXoca2z64MVYMCwqs/g080IM=}}
  ],
  transactionInfo:{
    statements:[
      {
        statement:"INSERT INTO VehicleRegistration VALUE ?",
        startTime:2022-06-08T18:46:46.063Z,
        statementDigest:{{KY2nL6UGUPs5lXCLVXcUaBxcEIop0Jvk4MEjcFVBfwI=}}
      },
      {
        statement:"SELECT p_id FROM Person p BY p_id WHERE p.FirstName = ? and p.LastName = ?",
        startTime:2022-06-08T18:46:46.173Z,
        statementDigest:{{QS2nfB8XBf2ozlDx0nvtsliOYDSmNHMYC3IRH4Uh690=}}
      },
      {
        statement:"UPDATE VehicleRegistration r SET r.Owners.PrimaryOwner.PersonId = ? WHERE r.VIN = ?",
        startTime:2022-06-08T18:46:46.278Z,
        statementDigest:{{nGtIA9Qh0/dwIplOR8J5CTeqyUVtNUQgXfltDUo2Aq4=}}
      },
      {
        statement:"DELETE FROM DriversLicense l WHERE l.LicenseNumber = ?",
        startTime:2022-06-08T18:46:46.385Z,
        statementDigest:{{ka783dcEP58Q9AVQ1m9NOJd3JAmEvXLjzl0OjN1BojQ=}}
      }
    ],
    documents:{
      HwVFkn8IMRa0xjze5xcgga:{
        tableName:"VehicleRegistration",
        tableId:"HQZ6cgIMUi204Lq1tT4oaJ",
        statements:[0,2]
      },
      IiPTRxLGJZa342zHFCFT15:{
        tableName:"DriversLicense",
        tableId:"BvtXEB1JxZg0lJlBAtbtSV",
        statements:[3]
      }
    }
  },
  revisions:[
    {
      hash:{{FR1IWcWew0yw1TnRklo2YMF/qtwb7ohsu5FD8A4DSVg=}}
    },
    {
      blockAddress:{
        strandId:"4o5UuzWSW5PIoOGm5jPA6J",
        sequenceNo:25
      },
      hash:{{6TTHbcfIVdWoFC/j90BOZi0JdHzhjSXo1tW+uHd6Dj4=}},
      data:{
        VIN:"1N4AL11D75C109151",
        LicensePlateNumber:"LEWISR261LL",
        State:"WA",
        City:"Seattle",
        PendingPenaltyTicketAmount:90.25,
        ValidFromDate:2017-08-21,
        ValidToDate:2020-05-11,
        Owners:{
          PrimaryOwner:{
            PersonId:"3Ax20JIix5J2ulu2rCMvo2"
          },
          SecondaryOwners:[]
        }
      },
      metadata:{
        id:"HwVFkn8IMRa0xjze5xcgga",
        version:0,
        txTime:2022-06-08T18:46:46.492Z,
        txId:"3gtB8Q8dfIMA8lQ5pzHAMo"
      }
    },
    {
      blockAddress:{
        strandId:"4o5UuzWSW5PIoOGm5jPA6J",
        sequenceNo:25
      },
      hash:{{ZVF/f1uSqd5DIMqzI04CCHaCGFK/J0Jf5AFzSEk0l90=}},
      metadata:{
        id:"IiPTRxLGJZa342zHFCFT15",
        version:1,
        txTime:2022-06-08T18:46:46.492Z,
        txId:"3gtB8Q8dfIMA8lQ5pzHAMo"
      }
    }
  ]
}

En el campo revisions, es posible que algunos objetos de revisión contengan solo un valor hash y ningún otro atributo. Son revisiones del sistema exclusivamente internas que no contienen datos de usuario. Los hash de estas revisiones forman parte de la cadena de hash completa del diario, necesaria para la verificación criptográfica.

Contenidos del bloque

Un bloque de diarios cuenta con los siguientes campos:

blockAddress

La ubicación del bloque en el diario. La dirección es una estructura de Amazon Ion que consta de dos campos: strandId ysequenceNo.

Por ejemplo: {strandId:"BlFTjlSXze9BIh1KOszcE3",sequenceNo:14}

transactionId

El ID único de la transacción que confirmó el bloque.

blockTimestamp

La fecha y hora de confirmación del bloque en el diario.

blockHash

El valor de hash de 256 bits que representa ese bloque único. Es el hash de la concatenación de entriesHash y previousBlockHash.

entriesHash

El hash que representa todas las entradas del bloque, incluidas las entradas del sistema únicamente internas. Se trata del hash raíz del árbol de Merkle, en el que los nodos de las hojas están compuestos por todos los hash de entriesHashList.

previousBlockHash

El hash del anterior bloque encadenado del diario.

entriesHashList

La lista de hash que representan cada entrada del bloque. Esta lista puede incluir los siguientes hash de entrada:

• El hash de Ion que representa transactionInfo. Este valor se calcula tomando el hash de Ion de toda la estructura de transactionInfo.

• Se trata del hash raíz del árbol de Merkle, en el que los nodos de las hojas están compuestos por todos los hash de revisions.

• El hash de Ion que representa redactionInfo. Este hash solo existe en los bloques confirmados mediante una transacción de redacción. Este valor se calcula tomando el hash de Ion de toda la estructura de redactionInfo.

• Hashes que representan metadatos del sistema únicamente internos. Es posible que estos hashes no existan en todos los bloques.

transactionInfo

Estructura de Amazon Ion que contiene información sobre las instrucciones de la transacción en la que se confirmó el bloque. Esta estructura tiene los campos siguientes:

• statements: la lista de instrucciones PartiQL y el startTime en que comenzaron a ejecutarse. Cada instrucción tiene un hash de statementDigest necesario para calcular el hash de la estructura de transactionInfo.

• documents: los ID de los documentos que se actualizaron con las instrucciones. Cada documento incluye el tableName e tableId al que pertenece, así como el índice de cada instrucción que lo actualizó.

revisions

La lista de revisiones de documentos confirmadas en el bloque. Cada estructura de revisión contiene todos los campos de la vista confirmada de la revisión.

También puede incluir hashes que representen revisiones del sistema exclusivamente internas y que formen parte de la cadena de hash completa de un diario.

Revisiones redactadas

En Amazon QLDB, una instrucción DELETE solo elimina un documento de forma lógica al crear una nueva revisión que lo marca como eliminado. QLDB también permite realizar una operación de edición de datos para eliminar permanentemente las revisiones de documentos inactivos del historial de una tabla.

La operación de redacción elimina solo los datos de usuario de la revisión especificada, sin alterar el diario ni los metadatos del documento. Esto mantiene la integridad general de los datos del libro mayor. Para obtener más información y ver un ejemplo de operación de redacción, consulte Editar revisiones de documentos.

Ejemplo de revisión redactada

Considere el ejemplo de bloque anterior. En este bloque, supongamos que redacta la revisión con ID de documento HwVFkn8IMRa0xjze5xcgga y número de versión 0.

Una vez finalizada la redacción, los datos de usuario de la revisión (representados por la estructura data) se sustituyen por un nuevo campo dataHash. El valor de este campo es el hash de Ion de la estructura data eliminada. Como resultado, el libro mayor mantiene la integridad general de sus datos y sigue siendo verificable criptográficamente mediante las operaciones de la API de verificación existentes.

El siguiente ejemplo de revisión muestra los resultados de esta redacción, con el nuevo campo dataHash resaltado en cursiva roja.

nota

Este ejemplo de revisión se ofrece solo con fines informativos. Los hash que se muestran no son valores hash calculados reales.

...
{
  blockAddress:{
    strandId:"4o5UuzWSW5PIoOGm5jPA6J",
    sequenceNo:25
  },
  hash:{{6TTHbcfIVdWoFC/j90BOZi0JdHzhjSXo1tW+uHd6Dj4=}},
  dataHash:{{s83jd7sfhsdfhksj7hskjdfjfpIPP/DP2hvionas2d4=}},
  metadata:{
    id:"HwVFkn8IMRa0xjze5xcgga",
    version:0,
    txTime:2022-06-08T18:46:46.492Z,
    txId:"3gtB8Q8dfIMA8lQ5pzHAMo"
  }
}
...

QLDB también añade un nuevo bloque al diario con la solicitud finalizada de redacción. En este bloque se incluye una entrada redactionInfo adicional que contiene una lista de las revisiones redactadas en la transacción, tal como se muestra en el ejemplo siguiente.

...
redactionInfo:{
  revisions:[
    {
      blockAddress:{
        strandId:"4o5UuzWSW5PIoOGm5jPA6J",
        sequenceNo:25
      },
      tableId:"HQZ6cgIMUi204Lq1tT4oaJ",
      documentId:"HwVFkn8IMRa0xjze5xcgga",
      version:0
    }
  ]
}
...

Aplicación de muestra

Para ver un ejemplo de código Java que valida la cadena de hash de un diario usando datos exportados, consulte el repositorio de GitHub aws-samples/amazon-qldb-dmv-sample-java. Esta aplicación de ejemplo incluye los siguientes archivos de clase:

• ValidateQldbHashChain.java: contiene un código tutorial que exporta bloques de diarios de un libro mayor y emplea los datos exportados para validar la cadena de hash entre bloques.

• JournalBlock.java: contiene un método denominado verifyBlockHash() que muestra cómo calcular cada componente de hash individual de un bloque. Este método se invoca mediante el código del tutorial de ValidateQldbHashChain.java.

Para obtener instrucciones sobre cómo descargar e instalar esta aplicación de ejemplo completa, consulte Instalación de la aplicación de ejemplo Java de Amazon QLDB. Antes de ejecutar el código del tutorial, asegúrese de seguir los pasos 1 a 3 de Tutorial de Java para configurar un libro mayor y cargarlo con datos de ejemplo.

Véase también

Para obtener más información sobre diarios en QLDB, consulte los siguientes temas:

• Exportación de datos de diarios desde Amazon QLDB: para saber cómo exportar datos del diario a Amazon Simple Storage Service (Amazon S3).

• Transmisión de datos de diarios desde Amazon QLDB: para saber cómo transmitir datos del diario a Amazon Kinesis Data Streams.

• Verificación de datos en Amazon QLDB: para obtener más información sobre la verificación criptográfica de los datos del diario.