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

Importante

Aviso de fim do suporte: os clientes existentes poderão usar a Amazon QLDB até o final do suporte em 31/07/2025. Para obter mais detalhes, consulte Migrar um Amazon QLDB Ledger para o Amazon Aurora Postgre. SQL

Um trabalho de exportação de QLDB diário da Amazon 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, QLDB converterá negativamente os dados do diário Amazon Ion JSON em seus objetos de dados exportados. Para obter mais informações, acesse o Conversão descendente para JSON.

Arquivos de manifesto

QLDBA Amazon cria dois arquivos de manifesto no bucket 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. exportIdÉ uma ID exclusiva que é QLDB atribuída a cada trabalho 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 API operação 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

Na AmazonQLDB, um fio é uma partição do diário do seu livro contábil. QLDBatualmente suporta periódicos 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

strandIdÉ uma ID exclusiva que é QLDB atribuída à cadeia. 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

A 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 JSONLines.

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

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 na 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, QLDB converterá negativamente os dados do diário Amazon Ion JSON em seus objetos de dados exportados. No entanto, a JSON conversão de íon em causa perdas em certos casos em que seus dados usam os tipos ricos de íons que não existem em. JSON

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

Biblioteca de processadores de exportação (Java)

QLDBfornece 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.