WriteRecords

Permite que você grave seus dados de séries temporais no Timestream. É possível especificar um único ponto de dados ou um lote de pontos de dados a serem inseridos no sistema. O Timestream oferece um esquema flexível que detecta automaticamente os nomes das colunas e os tipos de dados das tabelas do Timestream com base nos nomes das dimensões e nos tipos de dados dos pontos de dados especificados ao invocar gravações no banco de dados.

O Timestream é compatível com uma eventual semântica de leitura final consistente. Isso significa que quando você consulta dados imediatamente após gravar um lote de dados no Timestream, os resultados da consulta podem não refletir os resultados de uma operação de gravação recém-concluída. Os resultados também podem incluir alguns dados obsoletos. Se você repetir a solicitação da consulta após um curto período de tempo, os resultados devem retornar os dados mais recentes. Cotas de serviço se aplicam.

Consulte a amostra de código para obter detalhes.

Upserts

Você pode usar o parâmetro Version em uma solicitação WriteRecords para atualizar pontos de dados. O Timestream rastreia um número de versão com cada registro. Version o padrão é 1 quando não é especificado para o registro na solicitação. O Timestream atualiza o valor de medida de um registro existente junto com o valor Version quando recebe uma solicitação de gravação com um Version número maior para esse registro. Quando recebe uma solicitação de atualização em que o valor da medida é o mesmo do registro existente, o Timestream ainda é atualizado Version, se for maior que o valor existente de Version. É possível atualizar um ponto de dados quantas vezes quiser, desde que o valor de aumente Version continuamente.

Por exemplo, suponha que você grave um novo registro sem indicar Version na solicitação. O Timestream armazena esse registro e o define Version como 1. Agora, suponha que você tente atualizar esse registro com uma solicitação WriteRecords do mesmo registro com um valor de medida diferente, mas, como antes, não forneça Version. Nesse caso, o Timestream rejeitará essa atualização com a, RejectedRecordsException já que a versão do registro atualizado não é maior que o valor existente de Versão.

No entanto, se você reenviasse a solicitação de atualização com Version definido como 2, o Timestream conseguiria atualizar o valor do registro e o Version seria definido como 2. Em seguida, suponha que você tenha enviado uma solicitação WriteRecords com esse mesmo registro e um valor de medida idêntico, mas com Version definido como 3. Nesse caso, o Timestream só seria atualizado para Version para 3. Quaisquer atualizações adicionais precisariam enviar um número de versão maior que 3, ou as solicitações de atualização receberiam um RejectedRecordsException.

Sintaxe da solicitação

{
   "CommonAttributes": { 
      "Dimensions": [ 
         { 
            "DimensionValueType": "string",
            "Name": "string",
            "Value": "string"
         }
      ],
      "MeasureName": "string",
      "MeasureValue": "string",
      "MeasureValues": [ 
         { 
            "Name": "string",
            "Type": "string",
            "Value": "string"
         }
      ],
      "MeasureValueType": "string",
      "Time": "string",
      "TimeUnit": "string",
      "Version": number
   },
   "DatabaseName": "string",
   "Records": [ 
      { 
         "Dimensions": [ 
            { 
               "DimensionValueType": "string",
               "Name": "string",
               "Value": "string"
            }
         ],
         "MeasureName": "string",
         "MeasureValue": "string",
         "MeasureValues": [ 
            { 
               "Name": "string",
               "Type": "string",
               "Value": "string"
            }
         ],
         "MeasureValueType": "string",
         "Time": "string",
         "TimeUnit": "string",
         "Version": number
      }
   ],
   "TableName": "string"
}

Parâmetros da solicitação

Para obter informações sobre os parâmetros que são comuns em todas as ações, consulte Parâmetros comuns.

A solicitação aceita os dados a seguir no formato JSON.

CommonAttributes

Um registro que contém os atributos comuns de medida, dimensão, tempo e versão compartilhados entre todos os registros na solicitação. Os atributos de medida e dimensão especificados serão mesclados com os atributos de medida e dimensão no objeto de registros quando os dados forem gravados no Timestream. As dimensões não podem se sobrepor ou podem ser ValidationException lançadas. Em outras palavras, um registro deve conter dimensões com nomes exclusivos.

Tipo: objeto Record

Obrigatório: não

DatabaseName

O nome do banco de dados do Timestream.

Tipo: string

Restrições de tamanho: tamanho mínimo 3. Tamanho máximo de 256.

Obrigatório: sim

Records

Uma matriz de registros que contém os atributos exclusivos de medida, dimensão, tempo e versão para cada ponto de dados de série temporal.

Tipo: matriz de objetos Record

Membros da matriz: número mínimo de 1 item. Número máximo de 100 itens.

Obrigatório: sim

TableName

O nome da tabela do Timestream.

Tipo: string

Restrições de tamanho: tamanho mínimo 3. Tamanho máximo de 256.

Obrigatório: sim

Sintaxe da Resposta

{
   "RecordsIngested": { 
      "MagneticStore": number,
      "MemoryStore": number,
      "Total": number
   }
}

Elementos de Resposta

Se a ação for bem-sucedida, o serviço retornará uma resposta HTTP 200.

Os dados a seguir são retornados no formato JSON pelo serviço.

RecordsIngested

Informações sobre os registros ingeridos por essa solicitação.

Tipo: objeto RecordsIngested

Erros

Para obter informações sobre os erros comuns retornados pelas ações, consulte Erros comuns.

AccessDeniedException

Você não está autorizado a executar esta ação.

Código de status HTTP: 400

InternalServerException

O Timestream não conseguiu processar totalmente essa solicitação devido a um erro interno do servidor.

Código de status HTTP: 500

InvalidEndpointException

O endpoint solicitado não era válido.

Código de status HTTP: 400

RejectedRecordsException

WriteRecords lançaria essa exceção nos seguintes casos:

• Registros com dados duplicados em que há vários registros com as mesmas dimensões, carimbos de data/hora e nomes de medidas, mas:

  • Os valores das medidas são diferentes

  • A versão não está presente na solicitação ou o valor da versão no novo registro é igual ou inferior ao valor existente

  Nesse caso, se o Timestream rejeitar dados, o campo ExistingVersion na resposta RejectedRecords indicará a versão atual do registro. Para forçar uma atualização, você pode reenviar a solicitação com uma versão do conjunto de registros com um valor maior que ExistingVersion.

• Registros com carimbos de data/hora que estão fora da duração de retenção do armazenamento de memória.

• Registros com dimensões ou medidas que excedem os limites definidos pelo Timestream.

Para obter mais informações, consulte Cotas no Guia do desenvolvedor do Amazon Timestream.

RejectedRecords

Código de status HTTP: 400

ResourceNotFoundException

A operação tentou acessar um recurso inexistente. O recurso pode não estar especificado corretamente ou seu status pode não ser ATIVO.

Código de status HTTP: 400

ThrottlingException

Muitas solicitações foram feitas por um usuário e elas excederam as cotas de serviço. A solicitação foi acelerada.

Código de status HTTP: 400

ValidationException

Uma solicitação inválida ou malformada.

Código de status HTTP: 400

Consulte também

Para obter mais informações sobre como usar essa API em um dos SDKs específicos de linguagem AWS, consulte:

• AWS Command Line Interface V2

• AWS SDK para .NET

• AWS SDK para C++

• AWS SDK para Go v2

• AWS SDK for Java v2

• AWS SDK para JavaScript V3

• AWS SDK para Kotlin

• AWS SDK para PHP V3

• AWS SDK para Python

• AWS SDK para Ruby V3