Para recursos semelhantes aos do Amazon Timestream para, considere o Amazon Timestream LiveAnalytics para InfluxDB. Ele oferece ingestão de dados simplificada e tempos de resposta de consulta de um dígito em milissegundos para análises em tempo real. Saiba mais [aqui](https://docs.aws.amazon.com//timestream/latest/developerguide/timestream-for-influxdb.html).
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á.
# Gravar dados em seu cluster Timestream para InfluxDB 3
O Amazon Timestream para InfluxDB 3 fornece recursos robustos para ingerir dados de séries temporais com eficiência. Compreender os métodos adequados para gravar dados é essencial para maximizar o desempenho e garantir a integridade dos dados.
O Timestream para InfluxDB 3 fornece vários endpoints de API HTTP para gravar dados de séries temporais, oferecendo flexibilidade para diferentes métodos de integração e compatibilidade com workloads existentes do InfluxDB.
## Visão geral do protocolo de linha
O InfluxDB 3 foi projetado para alta taxa de gravação e usa uma sintaxe de gravação eficiente e legível por humanos chamada [protocolo de linha.](https://docs.influxdata.com/influxdb3/core/reference/line-protocol/) Como schema-on-write banco de dados, o InfluxDB cria automaticamente o banco de dados lógico, as tabelas e seus esquemas quando você começa a gravar dados, sem exigir nenhuma configuração manual. Depois que o esquema é criado, o InfluxDB valida futuras solicitações de gravação antes de aceitar novos dados, enquanto ainda permite a evolução do esquema conforme suas necessidades mudam.
### Estrutura do protocolo de linha
O protocolo de linha consiste nos seguintes elementos essenciais:
+ **Tabela**: um identificador de string para a tabela em que os dados serão armazenados.
+ (Opcional) **Conjunto de tags**: pares de valores-chave delimitados por vírgula que representam metadados (indexados).
+ **Conjunto de campos**: pares de valores-chave delimitados por vírgula que representam as medidas reais.
+ (Opcional) **Registro de data/hora**: registro de data/hora Unix associado ao ponto de dados com precisão de até nanossegundos.
Os valores de campo podem ser um dos seguintes tipos de dados:
+ Cadeias de caracteres (devem ser citadas)
+ Flutua (por exemplo, 23,4)
+ Números inteiros (por exemplo, 10i)
+ Números inteiros não assinados (por exemplo, 10u)
+ Booleano: (true/false)
O protocolo de linha segue esta sintaxe geral:
```
myTable,tag1=val1,tag2=val2 field1="v1",field2=1i 0000000000000000000
```
Exemplo de ponto de dados usando protocolo de linha:
```
home,room=Living\ Room temp=21.1,hum=35.9,co=0i 1735545600
```
Isso cria um ponto na tabela “inicial” com:
+ Tag: room="Sala de estar"
+ Campos: temp=21,1 (flutuante), hum=35,9 (flutuante), co=0 (inteiro)
+ Registro de data/hora: 1735545600 (segundos Unix)
## Visão geral dos endpoints de API
O InfluxDB 3 é compatível com três endpoints primários de gravação:
1. **API v3 nativa** (`/api/v3/write_lp`): o endpoint recomendado para novas implantações.
1. **API de compatibilidade v2** (`/api/v2/write`): para migrar workloads do InfluxDB v2.x.
1. **API de compatibilidade v1** (`/write`): para migrar workloads do InfluxDB v1.x.
### Utilização da API de gravação Native v3
O endpoint `/api/v3/write_lp` é a API nativa do InfluxDB 3 para escrever dados de protocolo de linha.
Formato de solicitação:
```
POST /api/v3/write_lp?db=DATABASE_NAME&precision=PRECISION&accept_partial=BOOLEAN&no_sync=BOOLEAN
```
Parâmetros de consulta:
| **Parâmetro** | **Descrição** | **Padrão** |
| --- | --- | --- |
| db | Nome do banco de dados (obrigatório) | - |
| precision | Precisão do registro de data/hora (ns, us, ms, s) | Detectado automaticamente |
| accept\_partial | Aceitar gravações parciais em erros | true |
| no\_sync | Reconheça antes da persistência do WAL | false |
####
Exemplo de solicitação de gravação:
```
curl -v "https://your-cluster-endpoint:8086/api/v3/write_lp?db=sensors&precision=s" \
--header "Authorization: Bearer YOUR_TOKEN" \
--data-raw "home,room=Living\ Room temp=21.1,hum=35.9,co=0i 1735545600
home,room=Kitchen temp=21.0,hum=35.9,co=0i 1735545600"
```
### Gravar modos de resposta
Modo padrão (`no_sync`=false)
+ Espera que os dados sejam gravados no WAL (Write-Ahead Log) antes de confirmar.
+ Oferece garantias de durabilidade.
+ Maior latência devido à espera persistente do WAL.
+ Recomendado para dados críticos em que a durabilidade é essencial.
Modo rápido (`no_sync`=true)
+ Confirma imediatamente sem esperar pela persistência do WAL.
+ Menor latência de gravação possível.
+ Risco de perda de dados se o sistema travar antes da conclusão da gravação do WAL.
+ Ideal para cenários de alto throughput em que a velocidade é priorizada em relação à durabilidade absoluta.
### Manipulação parcial de gravação
O parâmetro `accept_partial` controla o comportamento quando os lotes de gravação contêm erros:
Quando `accept_partial` é `true` (padrão):
+ As linhas válidas foram escritas com sucesso.
+ Linhas inválidas são rejeitadas.
+ Retorna o status 400 com detalhes sobre linhas com falha.
+ Útil para operações em grandes lotes em que algumas falhas são aceitáveis.
Quando `accept_partial` for `false`:
+ O lote inteiro será rejeitado se alguma linha falhar.
+ Nenhum dado é gravado.
+ Retorna o status 400 com detalhes do erro.
+ Garante a semântica de all-or-nothing gravação.
### Compatibilidade APIs
A compatibilidade APIs permite a migração perfeita das cargas de trabalho existentes do InfluxDB v1 ou v2 para o InfluxDB 3. Esses endpoints funcionam com bibliotecas de clientes do InfluxDB existentes, Telegraf e integrações de terceiros.
**Diferenças importantes:**
+ As tags em uma tabela (medição) são imutáveis depois de criadas.
+ Uma tag e um campo não podem ter o mesmo nome em uma tabela.
+ A validação do esquema é aplicada na gravação.
#### Compatibilidade com o InfluxDB v2
O endpoint `/api/v2/write` fornece compatibilidade com versões anteriores para clientes v2:
```
curl -i "https://your-cluster-endpoint:8086/api/v2/write?bucket=DATABASE_NAME&precision=s" \
--header "Authorization: Bearer DATABASE_TOKEN" \
--header "Content-type: text/plain; charset=utf-8" \
--data-binary 'home,room=kitchen temp=72 1641024000'
```
Parâmetro da API V2:
| **Parâmetro** | **Local** | **Descrição** |
| --- | --- | --- |
| bucket \* | String de consulta | Mapeia para o nome do banco de dados |
| precision | String de consulta | Precisão do registro de data/hora (ns, us, ms, s, m, h) |
| Authorization | Cabeçalho | Esquema de portador ou token |
| Content-Encoding | Cabeçalho | gzip ou identidade |
##### Compatibilidade com o InfluxDB v1
O endpoint `/write` fornece compatibilidade com versões anteriores para clientes v1:
```
curl -i "https://your-cluster-endpoint:8086/write?db=DATABASE_NAME&precision=s" \
--user "any:DATABASE_TOKEN" \
--header "Content-type: text/plain; charset=utf-8" \
--data-binary 'home,room=kitchen temp=72 1641024000'
```
Opções de autenticação V1:
+ Autenticação básica: token como senha (`--user "any:TOKEN"`).
+ Parâmetro de consulta: `p=TOKEN` na URL.
+ Bearer/Token cabeçalho: cabeçalho de autorização padrão.
Parâmetros da API do V1:
| **Parâmetro** | **Local** | **Descrição** |
| --- | --- | --- |
| db \* | String de consulta | Nome do banco de dados |
| precision | String de consulta | Precisão do registro de data/hora |
| p | String de consulta | Token para autenticação de consulta |
| u | String de consulta | Nome de usuário (ignorado) |
| Authorization | Cabeçalho | Compatibilidade com várias agendas |
| Content-Encoding | Cabeçalho | gzip ou identidade |
## Bibliotecas e integrações de clientes
### Bibliotecas de clientes oficiais do InfluxDB 3
As bibliotecas de cliente do InfluxDB 3 fornecem interfaces de linguagem nativa para construir e gravar dados de séries temporais:
+ **Python**: `influxdb3-python`
+ **Vá**: `influxdb3-go`
+ **JavaScript/Node.js**: `influxdb3-js`
+ **Java**: `influxdb3-java`
+ **C\#**: `InfluxDB3.Client`
Exemplo: cliente do Python
```
from influxdb3 import InfluxDBClient3
client = InfluxDBClient3(
host="your-cluster-endpoint:8086",
token="YOUR_TOKEN",
database="DATABASE_NAME"
)
# Write using line protocol
client.write("home,room=Living\\ Room temp=21.1,hum=35.9,co=0i")
# Write using Point objects
from influxdb3 import Point
point = Point("home") \
.tag("room", "Living Room") \
.field("temp", 21.1) \
.field("hum", 35.9) \
.field("co", 0)
client.write(point)
```
Exemplo: cliente Go
```
import "github.com/InfluxCommunity/influxdb3-go/v2/influxdb3"
client, err := influxdb3.New(influxdb3.ClientConfig{
Host: "your-cluster-endpoint:8086",
Token: "YOUR_TOKEN",
Database: "DATABASE_NAME",
})
point := influxdb3.NewPoint("home",
map[string]string{"room": "Living Room"},
map[string]any{
"temp": 24.5,
"hum": 40.5,
"co": 15,
},
time.Now(),
)
err = client.WritePoints(context.Background(), []*influxdb3.Point{point})
```
### Bibliotecas de cliente legadas
Para workloads v1 e v2 existentes, você pode continuar usando bibliotecas de cliente legadas com os endpoints de compatibilidade:
Exemplo: cliente Node.js v1:
```
const Influx = require('influx')
const client = new Influx.InfluxDB({
host: 'your-cluster-endpoint',
port: 8086,
protocol: 'https',
database: 'DATABASE_NAME',
username: 'ignored',
password: 'DATABASE_TOKEN'
})
```
## Práticas recomendadas para gravação de dados
Ao gravar dados, recomendamos o seguinte:
+ Otimização em lote
+ Tamanho de lote ideal: 5.000 a 10.000 linhas ou 10 MB por solicitação.
+ Use compressão (gzip) para grandes cargas úteis.
+ Classifique as etiquetas por chave em ordem lexicográfica para obter melhor desempenho.
+ Precisão do registro de data/hora
+ Use a precisão mais bruta que satisfaz suas necessidades.
+ Especifique explicitamente a precisão para evitar ambiguidade.
+ Mantenha uma precisão consistente em todo o seu aplicativo.
+ Tratamento de erros
+ Implemente a lógica de repetição para falhas transitórias.
+ Use accept\_partial=true para operações em lote resilientes.
+ Monitore erros de gravação por meio de CloudWatch métricas.
+ Ajuste de performance
+ Use no\_sync=true para cenários de alto throughput.
+ Distribua gravações em várias conexões.
+ Use o writer/reader endpoint para todas as operações de gravação.
+ Considerações sobre esquemas
+ As tags são imutáveis depois de criadas.
+ Campos e tags não podem compartilhar o mesmo nome.
+ Crie esquemas com padrões de consulta em mente.
+ Mantenha a cardinalidade da tag sob controle.
Diferenças importantes em relação às versões anteriores:
+ Tags imutáveis: depois que uma tag é criada em uma tabela, seu tipo não pode ser alterado
+ Sem conflitos de tag/field nome: uma tag e um campo não podem ter o mesmo nome em uma tabela
+ Schema-on-write: O InfluxDB 3 valida os tipos de dados na gravação
+ Criação automática de tabelas: as tabelas são criadas automaticamente na primeira gravação
+ Verificação estrita de tipos: os tipos de campo devem permanecer consistentes em todas as gravações
Ao aproveitar a API de gravação apropriada e seguir essas práticas recomendadas, você pode ingerir com eficiência dados de séries temporais em sua instância Timestream for InfluxDB 3, mantendo o alto desempenho e a integridade dos dados.