Skip to main content

Lecture et écriture sur TimeTonic

Maintenant que nous pouvons communiquer avec l'API TimeTonic via le M5Stack, il faut savoir utiliser les principales requêtes permettant de lire, créer et modifier les données contenues dans un book (espace de travail). Voici les étapes principales, avec le détail des fonctions API à utiliser et des exemples de structure de requête.

1. Lire les données d’une smart table

Pour récupérer le contenu d’une smart table, il faut utiliser la requête getTableValues. Cette requête retourne les lignes (rows) et les valeurs des champs (fields) d’une table donnée.

Paramètres nécessaires :

  • version : version de l’API (ex : "6.49") (optionnel)

  • req : "getTableValues"

  • o_u et u_c : identifiants utilisateur

  • sesskey : clé de session API

  • b_c : code du book (carnet)

  • catCode : code de la table (catégorie)

Exemple de requête POST :

version=6.49&req=getTableValues&o_u=USER_ID&u_c=USER_ID&sesskey=SESSION_KEY&b_c=BOOK_CODE&catCode=TABLE_CODE

En version formatée pour le code C précédentdemment utilisé :

"version=6.49"
"&req=getTableValues"
"&b_c=BOOK_CODE"
"&catCode=TABLE_CODE"
"&o_u=USER_ID"
"&u_c=USER_ID"
"&sesskey=SESSION_KEY"

La réponse contiendra un tableau JSON avec toutes les lignes et les valeurs des champs pour chaque ligne. Pour pouvoir exploiter ces données dans le code C, il faut utiliser un parseur, qui permet d'identifier et d'isoler chaque donnée lue.

2. Écrire des données dans une smart table

L’ajout ou la modification de données dans une smart table se fait avec la requête createOrUpdateTableRow.

 

a) Créer une nouvelle ligne

Pour créer une nouvelle ligne, il faut :

  • Utiliser rowId=tmpNEW_ROW

  • Fournir les valeurs à insérer dans un objet JSON associé au paramètre fieldValues (clé = identifiant du champ, valeur = donnée à insérer).

Exemple de requête POST :

text
version=6.49&req=createOrUpdateTableRow&o_u=USER_ID&u_c=USER_ID&sesskey=SESSION_KEY&b_c=BOOK_CODE&catCode=TABLE_CODE&rowId=tmpNEW_ROW&fieldValues={"FIELD_ID1":"Valeur1","FIELD_ID2":"Valeur2"}

Remplacez FIELD_ID1, FIELD_ID2 par les identifiants des champs récupérés via l’API, et "Valeur1", "Valeur2" par les données à insérer453.

b) Modifier une ligne existante

Pour modifier une ligne, il suffit d’indiquer l’identifiant de la ligne (rowId=ROW_ID_EXISTANTou rowId=tmpNEW_ROW) et de fournir les nouveaux champs à modifier dans fieldValues.

Paramètres nécessaires :

  • req : "createOrUpdateTableRow"

  • o_u et u_c : identifiants utilisateur

  • sesskey : clé de session API

  • b_c : code du book (carnet)

  • catCode : code de la table (catégorie)

  • fieldValues : données à écrire. celles-ci doivent être sous la forme d'un objet JSON avec la syntaxe suivante :
{
	"field ID": "Value",
	"field ID 2": "Value 2",
	"field ID 3": "Value 3"
	}

Exemple de requête POST:

version=6.49&req=createOrUpdateTableRow&o_u=USER_ID&u_c=USER_ID&sesskey=SESSION_KEY&b_c=BOOK_CODE&catCode=TABLE_CODE&rowId=ROW_ID_EXISTANT&fieldValues={"FIELD_ID1":"NouvelleValeur"}

En version formatée pour le code C (bien noter les antislashs avant les guillemets contenus dans fieldValues : ils permettent de les considérer comme des caractères normaux sans interférer avec les balises de Strings):

"req=createOrUpdateTableRow"
"&o_u=USER_ID"
"&u_c=USER_ID"
"&sesskey=SESSION_KEY"
"&b_c=BOOK_CODE"
"&catCode=TABLE_CODE"
"&rowId=ROW_ID"
"&fieldValues={\"FIELD_ID\":\"NouvelleValeur\"}"

 

Seuls les champs à modifier doivent être précisés dans fieldValues.

3. Récupérer les identifiants nécessaires

Si les données que vous lisez/écrivez sont toujours au même endroit, vous pouvez manuellement regarder les IDs de chaque champ et les copier dans votre code. Cependant, si vous voulez écrire des données à des endroits dépendant de certains champs/valeurs, vous pouvez obtenir les IDs pertinents via les requêtes getAllBooks (pour les books) et getBookTables (pour les tables et champs). Avant de pouvoir lire ou écrire, il est indispensable de connaître :

  • Le code du book (b_c)

  • Le code de la table (catCode)

  • Les identifiants des champs (fieldID1, fieldID2, etc.)

  • L’identifiant de la ligne, si modification (rowId)

Ces informations peuvent être obtenues via les requêtes getAllBooks (pour les books) et getBookTables (pour les tables et champs)123.

4. Résumé des étapes

  1. Authentification : Obtenir un sesskey via l’API.

  2. Lister les tables : Utiliser getAllBooks puis getBookTables pour identifier le book et la table cible.cible si nécessaire.

  3. Lire des données : Utiliser getTableValues pour obtenir les lignes et champs.

  4. Écrire des données :

    • Pour ajouter une ligne :Utiliser createOrUpdateTableRow avec rowId=tmpNEW_ROW.

      • si
    • vous

      Pourvoulez modifiercréer une lignenouvelle : createOrUpdateTableRow avec rowId de la ligne à modifier.ligne.

5. Bonnes pratiques

  • Utiliser systématiquement la méthode POST pour transmettre les paramètres.

  • Manipuler les objets JSON avec soin pour le paramètre fieldValues., et utiliser un parseur pour pouvoir utiliser les données lues.

  • Toujours vérifier le champ status dans la réponse de l’API pour s’assurer du succès de l’opération.ration (le code de succès 200 indique simplement que la requête est parvenue à l'API, pas nécessairement qu'elle a été correctement exécutée).

En résumé, la lecture et l’écriture dans une smart table TimeTonic via l’API sont simples : il suffit d’identifier les bons paramètres (book, table, champs), d’utiliser les requêtes appropriées, et de structurer correctement les données à envoyer ou à traiter.

Back to top