Para obtener capacidades similares a las de Amazon Timestream, considere Amazon Timestream LiveAnalytics para InfluxDB. Ofrece una ingesta de datos simplificada y tiempos de respuesta a las consultas en milisegundos de un solo dígito para realizar análisis en tiempo real. Obtenga más información [aquí](https://docs.aws.amazon.com//timestream/latest/developerguide/timestream-for-influxdb.html).
Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.
# Escritura de datos en su clúster de Timestream para InfluxDB 3
Amazon Timestream para InfluxDB 3 ofrece capacidades sólidas para ingerir datos de serie temporal de manera eficiente. Comprender los métodos adecuados para escribir datos es fundamental para maximizar el rendimiento y garantizar la integridad de los datos.
Timestream para InfluxDB 3 ofrece varios puntos de conexión de la API HTTP para escribir datos de serie temporal, lo que brinda flexibilidad para los diferentes métodos de integración y la compatibilidad con las cargas de trabajo de InfluxDB existentes.
## Descripción general del protocolo de línea
InfluxDB 3 está diseñado para un alto rendimiento de escritura y utiliza una sintaxis de escritura eficiente y legible por humanos llamada [protocolo de línea](https://docs.influxdata.com/influxdb3/core/reference/line-protocol/). Como schema-on-write base de datos, InfluxDB crea automáticamente la base de datos lógica, las tablas y sus esquemas cuando comienza a escribir datos, sin necesidad de ninguna configuración manual. Una vez que se crea el esquema, InfluxDB valida las solicitudes de escritura futuras con respecto a él antes de aceptar datos nuevos, mientras permite la evolución del esquema a medida que cambien sus necesidades.
### Estructura del protocolo de línea
El protocolo de línea consta de los siguientes elementos indispensables:
+ **Tabla**: un identificador de cadena para la tabla en la que se almacenarán los datos.
+ (Opcional) **Conjunto de etiquetas**: pares clave-valor delimitados por comas que representan metadatos (indexados).
+ **Conjunto de campos**: pares clave-valor delimitados por comas que representan las mediciones reales.
+ (Opcional) **Marca de tiempo**: marca de tiempo de Unix asociada al punto de datos con una precisión de hasta nanosegundos.
Los valores de campo pueden ser uno de los siguientes tipos de datos:
+ Cadenas (deben estar entre comillas)
+ Flota (por ejemplo, 23,4)
+ Enteros (por ejemplo, 10i)
+ Enteros sin signo (por ejemplo, 10u)
+ Booleano (verdadero o falso)
El protocolo de línea sigue esta sintaxis general:
```
myTable,tag1=val1,tag2=val2 field1="v1",field2=1i 0000000000000000000
```
Ejemplo de punto de datos que utiliza el protocolo de línea:
```
home,room=Living\ Room temp=21.1,hum=35.9,co=0i 1735545600
```
Esto crea un punto en la tabla “inicial” con:
+ Etiqueta: room="Living Room"
+ Campos: temp=21,1 (flota), hum=35,9 (flota), co=0 (entero)
+ Marca de tiempo: 1735545600 (segundos Unix)
## Información general de los puntos de conexión de la API
InfluxDB 3 admite tres puntos de conexión de escritura principales:
1. **API v3 nativa** (`/api/v3/write_lp`): el punto de conexión recomendado para las nuevas implementaciones.
1. **API de compatibilidad v2** (`/api/v2/write`): para migrar las cargas de trabajo de InfluxDB v2.x.
1. **API de compatibilidad v1** (`/write`): para migrar las cargas de trabajo de InfluxDB v1.x.
### Uso de la API de escritura nativa v3
El punto de conexión `/api/v3/write_lp` es la API nativa de InfluxDB 3 para escribir los datos de protocolo de línea.
Formato de solicitudes:
```
POST /api/v3/write_lp?db=DATABASE_NAME&precision=PRECISION&accept_partial=BOOLEAN&no_sync=BOOLEAN
```
Parámetros de consulta:
| **Parámetro** | **Descripción** | **Predeterminado** |
| --- | --- | --- |
| db | Nombre de la base de datos (obligatorio) | - |
| precision | Precisión de la marca de tiempo (ns, us, ms, s) | Detectado automático |
| accept\_partial | Acepta escrituras parciales en caso de errores | true |
| no\_sync | Reconoce antes de la persistencia de WAL | false |
####
Ejemplo de solicitud de escritura:
```
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"
```
### Modos de respuesta de escritura
Modo estándar (`no_sync` = falso)
+ Espera a que los datos se escriban en el WAL (registro de escritura anticipada) antes de confirmarlos.
+ Ofrece garantías de durabilidad.
+ Mayor latencia debido a la espera de persistencia del WAL.
+ Se recomienda para datos críticos en los que la durabilidad es fundamental.
Modo rápido (`no_sync` = verdadero)
+ Reconoce de inmediato sin esperar a que el WAL persista.
+ La latencia de escritura más baja posible.
+ Riesgo de pérdida de datos si el sistema se bloquea antes de que se complete la escritura del WAL.
+ Ideal para situaciones de alto rendimiento en las que se prioriza la velocidad por encima de la durabilidad absoluta.
### Gestión de escritura parcial
El parámetro `accept_partial` controla el comportamiento cuando los lotes de escritura tienen errores:
Cuándo `accept_partial` es `true` (predeterminado):
+ Las líneas válidas se escriben de manera correcta.
+ Se rechazan las líneas no válidas.
+ Devuelve el estado 400 con detalles sobre las líneas fallidas.
+ Útil para operaciones de lotes grandes en las que se aceptan algunas fallas.
Cuando `accept_partial` es `false`:
+ Si alguna línea falla, se rechaza todo el lote.
+ No se escribe ningún dato.
+ Devuelve el estado 400 con los detalles del error.
+ Garantiza la semántica all-or-nothing de escritura.
### Compatibilidad APIs
La compatibilidad APIs permite una migración perfecta de las cargas de trabajo existentes de InfluxDB v1 o v2 a InfluxDB 3. Estos puntos de conexión funcionan con las bibliotecas de clientes de InfluxDB existentes, Telegraf y las integraciones de agentes externos.
**Diferencias más destacadas:**
+ Las etiquetas de una tabla (medida) son inmutables una vez creadas.
+ Una etiqueta y un campo no pueden tener el mismo nombre en una tabla.
+ La validación del esquema se aplica al momento de escribir.
#### Compatibilidad con InfluxDB v2
El punto de conexión `/api/v2/write` ofrece compatibilidad con versiones anteriores para los clientes de la 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 de la API v2:
| **Parámetro** | **Ubicación** | **Descripción** |
| --- | --- | --- |
| bucket \* | Cadena de consulta | Mapeo hasta el nombre de la base de datos |
| precision | Cadena de consulta | Precisión de la marca de tiempo (ns, us, ms, s, m, h) |
| Authorization | Encabezado | Esquema de portador o token |
| Content-Encoding | Encabezado | gzip o identidad |
##### Compatibilidad con InfluxDB v1
El punto de conexión `/write` ofrece compatibilidad con versiones anteriores para los clientes de la 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'
```
Opciones de autenticación de la v1:
+ Autenticación básica: token como contraseña (`--user "any:TOKEN"`).
+ Parámetro de consulta: `p=TOKEN` en la URL.
+ Bearer/Token encabezado: encabezado de autorización estándar.
Parámetro de la API v1:
| **Parámetro** | **Ubicación** | **Descripción** |
| --- | --- | --- |
| db \* | Cadena de consulta | Nombre de base de datos |
| precision | Cadena de consulta | Precisión de la marca de tiempo |
| p | Cadena de consulta | Símbolo de autenticación de las consultas |
| u | Cadena de consulta | Nombre de usuario (ignorado) |
| Authorization | Encabezado | Varias programaciones admitidas |
| Content-Encoding | Encabezado | gzip o identidad |
## Integraciones y bibliotecas de los clientes
### Bibliotecas de cliente oficiales de InfluxDB 3
En las bibliotecas del cliente de InfluxDB 3 se ofrecen interfaces en el idioma nativo para construir y escribir datos de serie temporal:
+ **Python**: `influxdb3-python`
+ **Ve**: `influxdb3-go`
+ **JavaScript/Node.js**: `influxdb3-js`
+ **Java**: `influxdb3-java`
+ **C\#**: `InfluxDB3.Client`
Ejemplo: cliente 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)
```
Ejemplo: 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 heredadas de los clientes
Para las cargas de trabajo de las v1 y v2 existentes, puede seguir utilizando las bibliotecas heredadas de los clientes con los siguientes puntos de conexión de compatibilidad:
Ejemplo: cliente de 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ácticas recomendadas para la escritura de datos
Al escribir los datos, recomendamos lo siguiente:
+ Optimización del lote
+ Tamaño óptimo de lote: de 5000 a 10 000 líneas o 10 MB por solicitud.
+ Utilice la compresión (gzip) para cargas útiles de gran tamaño.
+ Clasifique las etiquetas por clave en orden lexicográfico para obtener un mejor rendimiento.
+ Precisión de la marca de tiempo
+ Utilice la precisión más basta que se adapte a sus necesidades.
+ Especifique la precisión de manera explícita para evitar la ambigüedad.
+ Mantenga una precisión uniforme en toda la aplicación.
+ Gestión de errores
+ Implemente una lógica de reintento para las fallas transitorias.
+ Utilice accept\_partial=true para operaciones por lotes resilientes.
+ Supervise los errores de escritura mediante CloudWatch métricas.
+ Ajuste del rendimiento
+ Utilice no\_sync=true para situaciones de alto rendimiento.
+ Distribuya las escrituras en varias conexiones.
+ Utilice el writer/reader punto final para todas las operaciones de escritura.
+ Consideraciones del esquema
+ Las etiquetas son inmutables una vez que se crearon.
+ Los campos y las etiquetas no pueden tener el mismo nombre.
+ Diseñe esquemas teniendo en cuenta los patrones de consulta.
+ Mantenga bajo control la cardinalidad de las etiquetas.
Diferencias importantes de las versiones anteriores:
+ Etiquetas inmutables: una vez que se crea una etiqueta en una tabla, no se puede cambiar su tipo
+ No hay conflictos de tag/field nombres: una etiqueta y un campo no pueden tener el mismo nombre en una tabla
+ Schema-on-write: InfluxDB 3 valida los tipos de datos al escribirlos
+ Creación automática de tablas: las tablas se crean de manera automática la primera vez que se escriben
+ Verificación estricta de tipos: los tipos de campo deben permanecer uniformes en todas las escrituras
Al utilizar la API de escritura adecuada y seguir estas prácticas recomendadas, puede ingerir datos de serie temporal de manera eficiente a la instancia de Timestream para InfluxDB 3 y, al mismo tiempo, mantener un alto rendimiento y la integridad de los datos.