Sortie d'exportation du journal dans QLDB

Une tâche d'exportation de journal Amazon QLDB écrit deux fichiers manifestes en plus des objets de données qui contiennent vos blocs de journal. Ils sont tous enregistrés dans le compartiment Amazon S3 que vous avez fourni dans votre demande d'exportation. Les sections suivantes décrivent le format et le contenu de chaque objet en sortie.

Note

Si vous spécifiez JSON comme format de sortie de votre tâche d'exportation, QLDB convertit les données du journal Amazon Ion en JSON dans vos objets de données exportés. Pour plus d'informations, rendez-vous surConversion descendante au format JSON.

Fichiers manifestes

Amazon QLDB crée deux fichiers manifestes dans le compartiment S3 fourni pour chaque demande d'exportation. Le fichier manifeste initial est créé dès que vous soumettez la demande d'exportation. Le fichier manifeste final est écrit une fois l'exportation terminée. Vous pouvez utiliser ces fichiers pour vérifier le statut de vos tâches d'exportation dans Amazon S3.

Le format du contenu des fichiers manifestes correspond au format de sortie demandé pour l'exportation.

Manifeste initial

Le manifeste initial indique que votre tâche d'exportation a commencé. Il contient les paramètres d'entrée que vous avez transmis à la demande. Outre la destination Amazon S3 et les paramètres d'heure de début et de fin de l'exportation, ce fichier contient également unexportId. exportIdIl s'agit d'un identifiant unique que QLDB attribue à chaque tâche d'exportation.

La convention de dénomination des fichiers est la suivante.

s3://DOC-EXAMPLE-BUCKET/prefix/exportId.started.manifest

Voici un exemple de fichier manifeste initial et de son contenu au format texte Ion.

s3://DOC-EXAMPLE-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:"DOC-EXAMPLE-BUCKET",
  prefix:"journalExport",
  objectEncryptionType:"NO_ENCRYPTION",
  outputFormat:"ION_TEXT"
}

Le manifeste initial inclut le manifeste outputFormat uniquement s'il a été spécifié dans la demande d'exportation. Si vous ne spécifiez pas le format de sortie, les données exportées sont ION_TEXT formatées par défaut.

Le fonctionnement de l'API DescribeJournalS3Export et le type de contenu des objets Amazon S3 exportés indiquent également le format de sortie.

Manifeste final

Le manifeste final indique que votre tâche d'exportation pour un volet de journal en particulier est terminée. La tâche d'exportation écrit un fichier manifeste final distinct pour chaque volet.

Note

Dans Amazon QLDB, un fil est une partition du journal de votre registre. QLDB prend actuellement en charge les revues à un seul volet.

Le manifeste final inclut une liste ordonnée de clés d'objets de données écrites lors de l'exportation. La convention de dénomination des fichiers est la suivante.

s3://DOC-EXAMPLE-BUCKET/prefix/exportId.strandId.completed.manifest

strandIdIl s'agit d'un identifiant unique que QLDB attribue au brin. Voici un exemple de fichier manifeste final et de son contenu au format texte Ion.

s3://DOC-EXAMPLE-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"
  ]
}

Objets de données

Amazon QLDB écrit les objets de données de journal dans le compartiment Amazon S3 fourni sous forme de texte ou de représentation binaire au format Amazon Ion, ou au format de texte JSON Lines.

Au format JSON Lines, chaque bloc d'un objet de données exporté est un objet JSON valide délimité par une nouvelle ligne. Vous pouvez utiliser ce format pour intégrer directement les exportations JSON à des outils d'analyse tels qu'Amazon Athena et AWS Glue parce que ces services peuvent analyser automatiquement le JSON délimité par de nouvelles lignes. Pour plus d'informations sur le format, consultez Lignes JSON.

Noms des objets de données

Une tâche d'exportation de journal écrit ces objets de données selon la convention de dénomination suivante.

s3://DOC-EXAMPLE-BUCKET/prefix/yyyy/mm/dd/hh/strandId.startSn-endSn.ion|.json

• Les données de sortie de chaque tâche d'exportation sont divisées en morceaux.

• yyyy/mm/dd/hh— La date et l'heure auxquelles vous avez soumis la demande d'exportation. Les objets exportés au cours de la même heure sont regroupés sous le même préfixe Amazon S3.

• strandId— L'identifiant unique du fil spécifique qui contient le bloc de journal en cours d'exportation.

• startSn-endSn— La plage de numéros de séquence incluse dans l'objet. Un numéro de séquence indique l'emplacement d'un bloc dans un fil.

Supposons, par exemple, que vous spécifiez le chemin suivant.

s3://DOC-EXAMPLE-BUCKET/journalExport/

Votre tâche d'exportation crée un objet de données Amazon S3 qui ressemble à ce qui suit. Cet exemple montre le nom d'un objet au format Ion.

s3://DOC-EXAMPLE-BUCKET/journalExport/2019/04/15/22/JdxjkR9bSYB5jMHWcI464T.1-5.ion

Contenu de l'objet de données

Chaque objet de données contient des objets de bloc de journal au format suivant.

{
  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 bloc est un objet qui est enregistré dans le journal lors d'une transaction. Un bloc contient des métadonnées de transaction ainsi que des entrées représentant les révisions du document qui ont été validées dans la transaction et les instructions partiQL qui les ont validées.

Voici un exemple de bloc contenant des exemples de données au format texte Ion. Pour plus d'informations sur les champs d'un objet de bloc, consultezContenu du journal dans Amazon QLDB.

Note

Cet exemple de bloc est fourni à titre informatif uniquement. Les hachages affichés ne sont pas de véritables valeurs de hachage calculées.

{
  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"
      }
    }
  ]
}

Sur le revisions terrain, certains objets de révision peuvent ne contenir qu'une hash valeur et aucun autre attribut. Il s'agit de révisions internes du système qui ne contiennent aucune donnée utilisateur. Une tâche d'exportation inclut ces révisions dans leurs blocs respectifs, car les hachages de ces révisions font partie de la chaîne de hachage complète du journal. La chaîne de hachage complète est requise pour la vérification cryptographique.

Conversion descendante au format JSON

Si vous spécifiez JSON comme format de sortie de votre tâche d'exportation, QLDB convertit les données du journal Amazon Ion en JSON dans vos objets de données exportés. Cependant, la conversion d'Ion en JSON entraîne des pertes dans certains cas où vos données utilisent des types d'ions riches qui n'existent pas dans JSON.

Pour en savoir plus sur les règles de conversion d'ions en JSON, consultez la section Conversion descendante au format JSON dans le livre de recettes Amazon Ion.

bibliothèque de processeurs d'exportation (Java)

QLDB fournit un framework extensible pour Java qui rationalise le traitement des exportations dans Amazon S3. Cette bibliothèque de framework permet de lire le résultat d'une exportation et d'itérer les blocs exportés dans un ordre séquentiel. Pour utiliser ce processeur d'exportation, consultez le GitHub référentiel amazon-qldb-export-processorawslabs/ -java.