Pour des fonctionnalités similaires à celles d'Amazon Timestream pour, pensez à Amazon Timestream LiveAnalytics pour InfluxDB. Il permet une ingestion simplifiée des données et des temps de réponse aux requêtes à un chiffre en millisecondes pour des analyses en temps réel. Pour en savoir plus, [cliquez ici](https://docs.aws.amazon.com//timestream/latest/developerguide/timestream-for-influxdb.html).
Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.
# Écrire des données dans votre cluster Timestream pour InfluxDB 3
Amazon Timestream pour InfluxDB 3 fournit des fonctionnalités robustes pour ingérer efficacement des données de séries chronologiques. Comprendre les méthodes appropriées pour écrire des données est essentiel pour optimiser les performances et garantir l'intégrité des données.
Timestream for InfluxDB 3 fournit plusieurs points de terminaison d'API HTTP pour écrire des données de séries chronologiques, offrant ainsi une flexibilité pour différentes méthodes d'intégration et une compatibilité avec les charges de travail InfluxDB existantes.
## Vue d'ensemble du protocole de ligne
[InfluxDB 3 est conçu pour un débit d'écriture élevé et utilise une syntaxe d'écriture efficace et lisible par l'homme appelée protocole de ligne.](https://docs.influxdata.com/influxdb3/core/reference/line-protocol/) En tant que schema-on-write base de données, InfluxDB crée automatiquement la base de données logique, les tables et leurs schémas lorsque vous commencez à écrire des données, sans nécessiter de configuration manuelle. Une fois le schéma créé, InfluxDB valide les futures demandes d'écriture par rapport à celui-ci avant d'accepter de nouvelles données, tout en permettant l'évolution du schéma en fonction de l'évolution de vos besoins.
### Structure du protocole de ligne
Le protocole de ligne comprend les éléments essentiels suivants :
+ **Table** : identifiant de chaîne pour la table dans laquelle les données seront stockées.
+ (Facultatif) **Ensemble de balises** : paires clé-valeur séparées par des virgules représentant les métadonnées (indexées).
+ **Ensemble de champs** : paires clé-valeur séparées par des virgules représentant les mesures réelles.
+ **Horodatage (Facultatif) : horodatage** Unix associé au point de données avec une précision maximale de la nanoseconde.
Les valeurs des champs peuvent être de l'un des types de données suivants :
+ Chaînes (doivent être entre guillemets)
+ Floats (par exemple, 23,4)
+ Entiers (par exemple, 10i)
+ Entiers non signés (par exemple, 10u)
+ Booléens (vrai/faux)
Le protocole de ligne suit cette syntaxe générale :
```
myTable,tag1=val1,tag2=val2 field1="v1",field2=1i 0000000000000000000
```
Exemple de point de données utilisant le protocole de ligne :
```
home,room=Living\ Room temp=21.1,hum=35.9,co=0i 1735545600
```
Cela crée un point dans le tableau « d'accueil » avec :
+ Tag : Chambre="Salon »
+ Champs : temp=21,1 (flottant), hum=35,9 (flottant), co=0 (entier)
+ Horodatage : 1735545600 (secondes Unix)
## Présentation des points de terminaison de l'API
InfluxDB 3 prend en charge trois points de terminaison d'écriture principaux :
1. **API native v3** (`/api/v3/write_lp`) : point de terminaison recommandé pour les nouvelles implémentations.
1. **API de compatibilité v2** (`/api/v2/write`) : pour la migration des charges de travail InfluxDB v2.x.
1. **API de compatibilité v1** (`/write`) : pour la migration des charges de travail InfluxDB v1.x.
### Utilisation de l'API d'écriture native v3
Le `/api/v3/write_lp` point de terminaison est l'API native InfluxDB 3 pour écrire les données du protocole de ligne.
Format de demande :
```
POST /api/v3/write_lp?db=DATABASE_NAME&precision=PRECISION&accept_partial=BOOLEAN&no_sync=BOOLEAN
```
Paramètres de requête :
| **Paramètre** | **Description** | **Par défaut** |
| --- | --- | --- |
| db | Nom de la base de données (obligatoire) | - |
| precision | Précision de l'horodatage (ns, us, ms, s) | Détecté automatiquement |
| accept\_partial | Accepter les écritures partielles en cas d'erreur | true |
| no\_sync | Reconnaître avant la persistance du WAL | false |
####
Exemple de demande d'écriture :
```
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"
```
### Modes de réponse en écriture
Mode standard (`no_sync`=faux)
+ Attend que les données soient écrites dans le WAL (Write-Ahead Log) avant d'accuser réception.
+ Fournit des garanties de durabilité.
+ Latence plus élevée en raison de l'attente persistante du WAL.
+ Recommandé pour les données critiques où la durabilité est essentielle.
Mode rapide (`no_sync`=vrai)
+ Reconnaît immédiatement sans attendre la persistance du WAL.
+ Latence d'écriture la plus faible possible.
+ Risque de perte de données en cas de panne du système avant la fin de l'écriture du WAL.
+ Idéal pour les scénarios à haut débit où la vitesse est privilégiée par rapport à la durabilité absolue.
### Gestion partielle de l'écriture
Le `accept_partial` paramètre contrôle le comportement lorsque les lots d'écriture contiennent des erreurs :
Quand `accept_partial` est `true` (par défaut) :
+ Les lignes valides sont écrites avec succès.
+ Les lignes non valides sont rejetées.
+ Renvoie le statut 400 avec des détails sur les lignes défaillantes.
+ Utile pour les opérations par lots importants où certaines défaillances sont acceptables.
Lorsque `accept_partial` est `false` :
+ Le lot entier est rejeté en cas de défaillance d'une ligne.
+ Aucune donnée n'est écrite.
+ Renvoie le statut 400 avec les détails de l'erreur.
+ Garantit la sémantique d' all-or-nothingécriture.
### Compatibilité APIs
La compatibilité APIs permet une migration fluide des charges de travail InfluxDB v1 ou v2 existantes vers InfluxDB 3. Ces points de terminaison fonctionnent avec les bibliothèques clientes InfluxDB existantes, Telegraf et les intégrations tierces.
**Différences importantes :**
+ Les balises d'un tableau (mesure) sont immuables une fois créées.
+ Une balise et un champ ne peuvent pas porter le même nom dans une table.
+ La validation du schéma est appliquée lors de l'écriture.
#### Compatibilité avec InfluxDB v2
Le `/api/v2/write` point de terminaison assure la rétrocompatibilité pour les clients 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'
```
Paramètres de l'API V2 :
| **Paramètre** | **Emplacement** | **Description** |
| --- | --- | --- |
| bucket \* | Chaîne de requête | Correspond au nom de la base de données |
| precision | Chaîne de requête | Précision de l'horodatage (ns, us, ms, s, m, h) |
| Authorization | En-tête | Schéma du porteur ou du jeton |
| Content-Encoding | En-tête | gzip ou identité |
##### Compatibilité avec InfluxDB v1
Le `/write` point de terminaison assure la rétrocompatibilité pour les clients 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'
```
Options d'authentification V1 :
+ Authentification de base : jeton comme mot de passe (`--user "any:TOKEN"`).
+ Paramètre de requête : `p=TOKEN` dans l'URL.
+ Bearer/Token en-tête : en-tête d'autorisation standard.
Paramètres de l'API V1 :
| **Paramètre** | **Emplacement** | **Description** |
| --- | --- | --- |
| db \* | Chaîne de requête | Nom de la base de données |
| precision | Chaîne de requête | Précision de l'horodatage |
| p | Chaîne de requête | Jeton pour l'authentification des requêtes |
| u | Chaîne de requête | Nom d'utilisateur (ignoré) |
| Authorization | En-tête | Plusieurs schémas pris en charge |
| Content-Encoding | En-tête | gzip ou identité |
## Bibliothèques clientes et intégrations
### Bibliothèques clientes officielles d'InfluxDB 3
Les bibliothèques clientes InfluxDB 3 fournissent des interfaces en langage natif pour la construction et l'écriture de séries chronologiques :
+ **Python** : `influxdb3-python`
+ **Allez** : `influxdb3-go`
+ **JavaScript/Node.js** : `influxdb3-js`
+ **Java** : `influxdb3-java`
+ **C\#** : `InfluxDB3.Client`
Exemple : client 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)
```
Exemple : Go client
```
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})
```
### Bibliothèques clientes héritées
Pour les charges de travail v1 et v2 existantes, vous pouvez continuer à utiliser les bibliothèques clientes existantes avec les points de terminaison de compatibilité :
Exemple : client 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'
})
```
## Bonnes pratiques en matière de rédaction de données
Lorsque vous rédigez des données, nous recommandons ce qui suit :
+ Optimisation des lots
+ Taille de lot optimale : 5 000 à 10 000 lignes ou 10 Mo par demande.
+ Utilisez la compression (gzip) pour les charges utiles importantes.
+ Triez les balises par clé dans l'ordre lexicographique pour de meilleures performances.
+ Précision de l'horodatage
+ Utilisez la précision la plus grossière qui répond à vos besoins.
+ Spécifiez explicitement la précision pour éviter toute ambiguïté.
+ Maintenez une précision constante dans l'ensemble de votre application.
+ Gestion des erreurs
+ Implémentez une logique de nouvelle tentative pour les échecs transitoires.
+ Utilisez accept\_partial=true pour des opérations par lots résilientes.
+ Surveillez les erreurs d'écriture grâce à CloudWatch des métriques.
+ Personnalisation de performances
+ Utilisez no\_sync=true pour les scénarios à haut débit.
+ Répartissez les écritures sur plusieurs connexions.
+ Utilisez le writer/reader point de terminaison pour toutes les opérations d'écriture.
+ Considérations relatives au schéma
+ Les balises sont immuables une fois créées.
+ Les champs et les balises ne peuvent pas partager le même nom.
+ Concevez des schémas en tenant compte des modèles de requêtes.
+ Gardez le contrôle de la cardinalité des balises.
Différences importantes par rapport aux versions précédentes :
+ Balises immuables : une fois qu'une balise est créée dans une table, son type ne peut pas être modifié
+ Aucun conflit de tag/field nom : une balise et un champ ne peuvent pas porter le même nom dans une table
+ Schema-on-write: InfluxDB 3 valide les types de données en écriture
+ Création automatique de tables : les tables sont créées automatiquement lors de la première écriture
+ Vérification de type stricte : les types de champs doivent rester cohérents lors de toutes les écritures
En tirant parti de l'API d'écriture appropriée et en suivant ces meilleures pratiques, vous pouvez ingérer efficacement des données de séries chronologiques dans votre instance Timestream for InfluxDB 3 tout en maintenant des performances élevées et l'intégrité des données.