El resultado de exportación del diario en QLDB

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.

Un trabajo de exportación de Amazon QLDB Journal escribe dos archivos de manifiesto además de los objetos de datos que contienen tus bloques de diario. Todos estos archivos se guardan en el bucket de Amazon S3 que especifique en su solicitud de exportación. En las siguientes secciones se describe el formato y el contenido de cada objeto de salida.

nota

Si lo especificas JSON como formato de salida de tu trabajo de exportación, QLDB convierte de forma descendente los datos del diario de Amazon Ion a los objetos JSON de datos exportados. Para obtener más información, vaya a Convertir descendentemente a JSON.

Archivos de manifiesto

Amazon QLDB crea dos archivos de manifiesto en el bucket de S3 proporcionado para cada solicitud de exportación. El archivo de manifiesto inicial se crea en cuanto envía la solicitud de exportación. El archivo de manifiesto final se escribe una vez finalizada la exportación. Puede utilizar estos archivos para comprobar el estado de sus trabajos de exportación en Amazon S3.

El formato del contenido de los archivos de manifiesto corresponde al formato de salida solicitado para la exportación.

Manifiesto inicial

El manifiesto inicial indica que su trabajo de exportación ha comenzado. Contiene los parámetros de entrada que has transferido a la solicitud. Además del destino de Amazon S3 y los parámetros de hora de inicio y finalización de la exportación, este archivo también contiene un exportId. exportIdEs un identificador único que se QLDB asigna a cada trabajo de exportación.

La convención de nomenclatura de archivos es la siguiente.

s3://amzn-s3-demo-bucket/prefix/exportId.started.manifest

A continuación se incluye un ejemplo de un archivo de manifiesto inicial y su contenido en formato de texto Ion.

s3://amzn-s3-demo-bucket/journalExport/8UyXulxccYLAsbN1aon7e4.started.manifest

{
  ledgerName:"my-example-ledger",
  exportId:"8UyXulxccYLAsbN1aon7e4",
  inclusiveStartTime:2019-04-15T00:00:00.000Z,
  exclusiveEndTime:2019-04-15T22:00:00.000Z,
  bucket:"amzn-s3-demo-bucket",
  prefix:"journalExport",
  objectEncryptionType:"NO_ENCRYPTION",
  outputFormat:"ION_TEXT"
}

El manifiesto inicial solo incluye el outputFormat si se especificó en la solicitud de exportación. Si no especifica el formato de salida, los datos exportados tomarán el formato ION_TEXT predeterminado.

La API operación DescribeJournalS3Export y el tipo de contenido de los objetos de Amazon S3 exportados también indican el formato de salida.

Manifiesto final

El manifiesto final indica que su trabajo de exportación para una cadena concreta del diario ha finalizado. El trabajo de exportación escribe un archivo de manifiesto final independiente para cada cadena.

nota

En AmazonQLDB, un capítulo es una partición del diario de tu libro de contabilidad. QLDBactualmente solo admite diarios con una sola cadena.

El manifiesto final incluye una lista ordenada de claves de objetos de datos que se escribieron durante la exportación. La convención de nomenclatura de archivos es la siguiente.

s3://amzn-s3-demo-bucket/prefix/exportId.strandId.completed.manifest

strandIdEs un identificador único que se QLDB asigna a la cadena. A continuación se incluye un ejemplo de un archivo de manifiesto final y su contenido en formato de texto Ion.

s3://amzn-s3-demo-bucket/journalExport/8UyXulxccYLAsbN1aon7e4.JdxjkR9bSYB5jMHWcI464T.completed.manifest

{
  keys:[
    "2019/04/15/22/JdxjkR9bSYB5jMHWcI464T.1-4.ion",
    "2019/04/15/22/JdxjkR9bSYB5jMHWcI464T.5-10.ion",
    "2019/04/15/22/JdxjkR9bSYB5jMHWcI464T.11-12.ion",
    "2019/04/15/22/JdxjkR9bSYB5jMHWcI464T.13-20.ion",
    "2019/04/15/22/JdxjkR9bSYB5jMHWcI464T.21-21.ion"
  ]
}

Objetos de datos

Amazon QLDB escribe los objetos de datos del diario en el bucket de Amazon S3 proporcionado en formato de texto o binario de Amazon Ion o en formato de texto de JSONlíneas.

En el formato JSON Lines, cada bloque de un objeto de datos exportado es un JSON objeto válido que está delimitado por una nueva línea. Puede utilizar este formato para integrar directamente JSON las exportaciones con herramientas de análisis como Amazon Athena y AWS Glue porque estos servicios pueden analizar automáticamente las nuevas líneas delimitadas. JSON Para obtener más información sobre el formato, consulte Líneas. JSON

Nombres de objetos de datos

Un trabajo de exportación de diarios escribe estos objetos de datos con la siguiente convención de nomenclatura.

s3://amzn-s3-demo-bucket/prefix/yyyy/mm/dd/hh/strandId.startSn-endSn.ion|.json

• Los datos de salida de cada trabajo de exportación se dividen en partes.

• yyyy/mm/dd/hh: la fecha y hora en que envió la solicitud de exportación. Los objetos que se exportan en la misma hora se agrupan con el mismo prefijo de Amazon S3.

• strandId: el identificador único de la cadena del diario concreta que contiene el bloque del diario que se va a exportar.

• startSn-endSn: el rango de números de secuencia que se incluye en el objeto. Un número de secuencia especifica la ubicación de un bloque dentro de una cadena.

Por ejemplo, suponga que especifica la siguiente ruta.

s3://amzn-s3-demo-bucket/journalExport/

El trabajo de exportación crea un objeto de datos de Amazon S3 similar al siguiente. Este ejemplo muestra el nombre de un objeto en formato Ion.

s3://amzn-s3-demo-bucket/journalExport/2019/04/15/22/JdxjkR9bSYB5jMHWcI464T.1-5.ion

Contenido del objeto de datos

Cada objeto de datos contiene objetos de bloques de diario con el siguiente formato.

{
  blockAddress: {
    strandId: String,
    sequenceNo: Int
  },
  transactionId: String,
  blockTimestamp: Datetime,
  blockHash: SHA256,
  entriesHash: SHA256,
  previousBlockHash: SHA256,
  entriesHashList: [ SHA256 ],
  transactionInfo: {
    statements: [
      {
        //PartiQL statement object
      }
    ],
    documents: {
      //document-table-statement mapping object
    }
  },
  revisions: [
    {
      //document revision object
    }
  ]
}

Un bloque es un objeto que se asigna al diario durante una transacción. Un bloque contiene metadatos de transacciones junto con entradas que representan las revisiones del documento que se registraron en la transacción y las instrucciones PartiQL que las confirmaron.

A continuación, se muestra un ejemplo de un bloque con datos de ejemplo en formato de texto Ion. Para obtener más información sobre los campos en un objeto de bloque, consulte Contenido de revistas en Amazon QLDB.

nota

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

{
  blockAddress:{
    strandId:"JdxjkR9bSYB5jMHWcI464T",
    sequenceNo:1234
  },
  transactionId:"D35qctdJRU1L1N2VhxbwSn",
  blockTimestamp:2019-10-25T17:20:21.009Z,
  blockHash:{{WYLOfZClk0lYWT3lUsSr0ONXh+Pw8MxxB+9zvTgSvlQ=}},
  entriesHash:{{xN9X96atkMvhvF3nEy6jMSVQzKjHJfz1H3bsNeg8GMA=}},
  previousBlockHash:{{IAfZ0h22ZjvcuHPSBCDy/6XNQTsqEmeY3GW0gBae8mg=}},
  entriesHashList:[
      {{F7rQIKCNn0vXVWPexilGfJn5+MCrtsSQqqVdlQxXpS4=}},
      {{C+L8gRhkzVcxt3qRJpw8w6hVEqA5A6ImGne+E7iHizo=}}
  ],
  transactionInfo:{
    statements:[
      {
        statement:"CREATE TABLE VehicleRegistration",
        startTime:2019-10-25T17:20:20.496Z,
        statementDigest:{{3jeSdejOgp6spJ8huZxDRUtp2fRXRqpOMtG43V0nXg8=}}
      },
      {
        statement:"CREATE INDEX ON VehicleRegistration (VIN)",
        startTime:2019-10-25T17:20:20.549Z,
        statementDigest:{{099D+5ZWDgA7r+aWeNUrWhc8ebBTXjgscq+mZ2dVibI=}}
      },
      {
        statement:"CREATE INDEX ON VehicleRegistration (LicensePlateNumber)",
        startTime:2019-10-25T17:20:20.560Z,
        statementDigest:{{B73tVJzVyVXicnH4n96NzU2L2JFY8e9Tjg895suWMew=}}
      },
      {
        statement:"INSERT INTO VehicleRegistration ?",
        startTime:2019-10-25T17:20:20.595Z,
        statementDigest:{{ggpon5qCXLo95K578YVhAD8ix0A0M5CcBx/W40Ey/Tk=}}
      }
    ],
    documents:{
      '8F0TPCmdNQ6JTRpiLj2TmW':{
        tableName:"VehicleRegistration",
        tableId:"BPxNiDQXCIB5l5F68KZoOz",
        statements:[3]
      }
    }
  },
  revisions:[
    {
      hash:{{FR1IWcWew0yw1TnRklo2YMF/qtwb7ohsu5FD8A4DSVg=}}
    },
    {
      blockAddress:{
        strandId:"JdxjkR9bSYB5jMHWcI464T",
        sequenceNo:1234
      },
      hash:{{t8Hj6/VC4SBitxnvBqJbOmrGytF2XAA/1c0AoSq2NQY=}},
      data:{
        VIN:"1N4AL11D75C109151",
        LicensePlateNumber:"LEWISR261LL",
        State:"WA",
        City:"Seattle",
        PendingPenaltyTicketAmount:90.25,
        ValidFromDate:2017-08-21,
        ValidToDate:2020-05-11,
        Owners:{
          PrimaryOwner:{
            PersonId:"GddsXfIYfDlKCEprOLOwYt"
          },
          SecondaryOwners:[]
        }
      },
      metadata:{
        id:"8F0TPCmdNQ6JTRpiLj2TmW",
        version:0,
        txTime:2019-10-25T17:20:20.618Z,
        txId:"D35qctdJRU1L1N2VhxbwSn"
      }
    }
  ]
}

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. Un trabajo de exportación incluye estas revisiones en sus bloques respectivos porque los hashes de estas revisiones forman parte de toda la cadena de hash del diario. Se requiere la cadena de hash completa para la verificación criptográfica.

Convertir descendentemente a JSON

Si lo especificas JSON como formato de salida de tu trabajo de exportación, QLDB convierte de forma descendente los datos del diario de Amazon Ion a los objetos JSON de datos exportados. Sin embargo, la conversión de Ion a JSON Ion conlleva pérdidas en algunos casos en los que los datos utilizan tipos de iones enriquecidos que no existen en ellos. JSON

Para obtener más información sobre las reglas de JSON conversión de Ion a Ion, consulte Convertir a, JSON en el libro de cocina de Amazon Ion.

Biblioteca de procesador de exportación (Java)

QLDBproporciona un marco extensible para Java que agiliza el procesamiento de las exportaciones en Amazon S3. Esta biblioteca de marcos se encarga del trabajo de leer el resultado de una exportación e iterar los bloques exportados en orden secuencial. Para usar este procesador de exportación, consulte el GitHub repositorio amazon-qldb-export-processorawslabs/ -java.