Saída de exportação de diário no QLDB - Amazon Quantum Ledger Database (Amazon QLDB)
Arquivos de manifestoObjetos de dadosConversão descendente para JSONBiblioteca de processadores de exportação (Java)

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Saída de exportação de diário no QLDB

Um trabalho de exportação de diário do Amazon QLDB grava dois arquivos de manifesto, além dos objetos de dados que contêm seus blocos de diário. Esses arquivos são salvos no bucket do Amazon S3 fornecido por você na solicitação de exportação. As seções a seguir descrevem o formato e o conteúdo de cada objeto de saída.

nota

Se você especificar JSON como formato de saída do seu trabalho de exportação, o QLDB converterá negativamente os dados do diário do Amazon Ion em JSON nos objetos de dados exportados. Para obter mais informações, acesse o Conversão descendente para JSON.

Arquivos de manifesto

O Amazon QLDB cria dois arquivos de manifesto no bucket do S3 fornecido para cada solicitação de exportação. O arquivo de manifesto inicial é criado assim que você envia a solicitação de exportação. O arquivo de manifesto final é gravado após a conclusão da exportação. Você pode usar esses arquivos para verificar o status dos seus trabalhos de exportação no Amazon S3.

O formato do conteúdo dos arquivos de manifesto corresponde ao formato de saída solicitado para a exportação.

Manifesto inicial

O manifesto inicial indica que seu trabalho de exportação foi iniciado. Ele contém os parâmetros de entrada que você passou para a solicitação. Além do destino do Amazon S3 e dos parâmetros de horário de início e término da exportação, esse arquivo também contém um exportId. O exportId é uma ID exclusiva atribuída pelo QLDB a cada tarefa de exportação.

A convenção de nomenclatura de arquivos é a seguinte.

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

Veja a seguir um exemplo de manifesto inicial e seu conteúdo no formato de texto 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"
}

O manifesto inicial inclui outputFormat somente se tiver sido especificado na solicitação de exportação. Se você não especificar o formato de saída, os dados exportados assumirão o formato padrão ION_TEXT.

A operação da API DescribeJournalS3Export e o tipo de conteúdo dos objetos Amazon S3 exportados também indicam o formato de saída.

Manifesto final

O manifesto final indica que seu trabalho de exportação para uma determinada cadeia do diário foi concluído. O trabalho de exportação grava um arquivo de manifesto final separado para cada cadeia.

nota

No Amazon QLDB, uma cadeia é uma partição do diário do seu ledger. Atualmente, o QLDB suporta diários com apenas uma única vertente.

O manifesto final inclui uma lista ordenada de chaves de objetos de dados que foram gravadas durante a exportação. A convenção de nomenclatura de arquivos é a seguinte.

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

O strandId é um ID exclusivo atribuído pelo QLDB à cadeia de caracteres. Veja a seguir um exemplo de manifesto final e seu conteúdo em formato de texto 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"
  ]
}

Objetos de dados

O Amazon QLDB grava objetos de dados de diário no bucket Amazon S3 fornecido na representação de texto ou binária do formato Amazon Ion ou no formato de texto JSON Lines.

No formato JSON Lines, cada bloco em um objeto de dados exportado é um objeto JSON válido delimitado por uma nova linha. Você pode usar esse formato para integrar diretamente as exportações JSON com ferramentas de análise, como o Amazon Athena, AWS Glue e porque esses serviços podem analisar automaticamente o JSON delimitado por novas linhas. Para obter mais informações sobre o formato, consulte Linhas JSON.

Nomes de objeto de dados

Um trabalho de exportação de diário grava esses objetos de dados com a seguinte convenção de nomenclatura.

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

  • Os dados de saída de cada trabalho de exportação são divididos em partes.

  • yyyy/mm/dd/hh — A data e a hora em que você enviou a solicitação de exportação. Objetos que são exportados na mesma hora são agrupados sob o mesmo prefixo do Amazon S3.

  • strandId— O ID exclusivo da cadeia específica que contém o bloco de diário que está sendo exportado.

  • startSn-endSn— O intervalo de números de sequência incluído no objeto. Um número de sequência especifica a localização de um bloco dentro de uma cadeia.

Por exemplo, suponha que você especifique o seguinte caminho.

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

Seu trabalho de exportação cria um objeto de dados do Amazon S3 semelhante ao seguinte. Este exemplo mostra um nome de objeto no formato Ion.

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

Conteúdo do objeto de dados

Cada objeto de dados contém objetos de bloco de diário com o seguinte 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
    }
  ]
}

Um bloco é um objeto que é confirmado no diário durante uma transação. Um bloco contém metadados da transação junto com entradas que representam as revisões do documento que foram confirmadas na transação e as declarações PartiQL que as confirmaram.

O exemplo a seguir é de um bloco com dados de amostra em formato de texto Ion. Para obter mais informações sobre os campos em um objeto de bloco, consulte Conteúdo do periódico no Amazon QLDB.

nota

Este exemplo de bloco é fornecido apenas para fins informativos. Os hashes mostrados não são valores reais de hash calculados.

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

No campo revisions, alguns objetos de revisão podem conter apenas um valor hash e nenhum outro atributo. Essas são revisões de sistema somente internas que não contêm dados do usuário. Um trabalho de exportação inclui essas revisões em seus respectivos blocos porque os hashes dessas revisões fazem parte da cadeia de hash completa do diário. A cadeia de hash completa é necessária para a verificação criptográfica.

Conversão descendente para JSON

Se você especificar JSON como formato de saída do seu trabalho de exportação, o QLDB converterá negativamente os dados do diário do Amazon Ion em JSON nos objetos de dados exportados. No entanto, a conversão de Ion para JSON causa perdas em alguns casos em que seus dados usam os tipos ricos de Ion que não existem em JSON.

Para obter detalhes sobre as regras de conversão de Ion para JSON, consulte Conversão descendente para JSON no Cookbook Amazon Ion.

Biblioteca de processadores de exportação (Java)

O QLDB fornece uma estrutura extensível para Java que simplifica o processamento de exportações no Amazon S3. Essa biblioteca de estrutura lida com o trabalho de ler a saída de uma exportação e iterar os blocos exportados em ordem sequencial. Para usar esse processador de exportação, consulte o GitHub repositório amazon-qldb-export-processorawslabs/ -java.