Aller au contenu
Vérifié

Interroger les données via l'API

La référence complète de data_module, les formes de filtre et de tri de dbs_read, et ce que dbs_delete et dbs_restore font réellement basculer.

Six méthodes de data_module couvrent une table de bout en bout : les mêmes six que la grille d'une table appelle, dans Studio et dans l'onglet Données du tableau de bord, et les mêmes qu'une application en cours d'exécution appelle via xu.dbs_* (voir JavaScript Framework). Avec une clé API de compte, elles sont accessibles directement ; voir Interroger et écrire les données d'une application pour un pas-à-pas de dbs_read / dbs_create avec les corps de requête et de réponse. Cette page est la référence des quatre autres, et des options de filtre, de tri et d'archivage que dbs_read accepte.

Méthodes

Chacune prend table_id, le _id propre au nœud de la table, jamais son nom d'affichage, et chaque écriture passe par les mêmes conversions de types de champ décrites dans Tables et champs.

Mettre à jour une ligne

POST/cpi/dbs_update
admin

DBS Update

Replaces the data of an existing record, identified by row_id, in the specified app table.

table_data est fusionné dans les données existantes de la ligne par identifiant de champ : seuls les champs que vous incluez sont modifiés, tous les autres champs déjà présents sur la ligne restent tels quels. Envoyez uniquement les champs que vous voulez modifier ; il n'est pas nécessaire de lire d'abord la ligne pour conserver le reste.

Supprimer et restaurer des lignes

POST/cpi/dbs_delete
admin

DBS Delete

Soft-deletes (or permanently deletes when 'permanent' is set) the listed record IDs from an app table.

POST/cpi/dbs_restore
admin

DBS Restore

Restores previously soft-deleted records, identified by their IDs, in the specified app table.

dbs_delete sans permanent ne supprime pas la ligne : il la bascule en archivée, le même état que celui où se retrouve une ligne quand quelqu'un l'archive depuis la grille. Une ligne archivée cesse d'apparaître dans un dbs_read ordinaire, mais existe toujours et compte encore dans le chiffre des archivées de get_table_counts, et dbs_restore la rebascule aussitôt. permanent: true saute l'étape d'archivage et supprime la ligne définitivement, ce que dbs_restore ne peut pas annuler.

Archivage d'une ligne, pas d'une table

Il s'agit de l'état active/archived propre à une ligne, défini avec dbs_delete et dbs_restore et relu avec l'indicateur archived de dbs_read. Il n'a aucun rapport avec l'archivage d'une table entière en tant que nœud Studio, décrit dans Tables et champs.

Compter les lignes

POST/cpi/get_table_counts
admin

Get Table Counts

Returns the number of records in a table: active records, or archived records when archived is true.

Renvoie le nombre de lignes actives et archivées d'une table, les mêmes chiffres que dbs_read joint déjà à sa propre réponse sous total_table_count, utile seul quand vous voulez un compte sans parcourir les lignes pour l'obtenir.

Filtrer une lecture

Le champ query de dbs_read est un objet indexé par identifiant de champ, chaque valeur nommant un type de filtre et un opérateur :

json
{
  "query": {
    "STU_Campus": { "filterType": "text", "type": "equals", "filter": "Downtown" },
    "STU_Age": { "filterType": "number", "type": "greaterThanOrEqual", "filter": 18 }
  }
}

Chaque champ nommé dans query est combiné aux autres par un ET. Un même champ peut aussi porter sa propre liste de conditions avec un operator OR ou AND entre elles, pour « ce champ correspond à l'une ou l'autre de ces valeurs » :

json
{
  "query": {
    "STU_Campus": {
      "operator": "OR",
      "conditions": [
        { "filterType": "text", "type": "equals", "filter": "Downtown" },
        { "filterType": "text", "type": "equals", "filter": "Uptown" }
      ]
    }
  }
}

Trier et paginer

sortModel est une liste de paires { colId, sort } (sort vaut asc ou desc), appliquées dans l'ordre donné pour un tri sur plusieurs colonnes. from et to sont une plage de lignes (from le décalage, to - from la taille de la page), tous deux facultatifs ; omettez-les et vous obtenez la page par défaut de la table.

Erreurs à connaître

Elles s'appliquent aux six méthodes ci-dessus, pas seulement à une écriture :