Comprendre l'API de requête

Cet article a été traduit de l'anglais par IA et peut contenir des erreurs. Vos commentaires nous aideront à l'améliorer.

Lorsque vous incluez des données d'ActivityInfo dans un tableau de bord Power BI, Power BI récupère les données via l'API de requête d'ActivityInfo.

Alors que Power BI nécessite des données dans un format tabulaire rectangulaire, les formulaires ActivityInfo peuvent être plus complexes et peuvent inclure des références à d'autres formulaires ainsi que des sous-formulaires. Pour cette raison, l'API de requête vous donne le contrôle sur la façon dont un formulaire ActivityInfo est transformé en tableau pour Power BI.

La requête par défaut

ActivityInfo fournit une requête "par défaut" pour chaque formulaire qui tente de fournir les données d'un formulaire dans un format le plus souvent requis par les utilisateurs. La "Requête par défaut" est accessible via l'URL suivante :

https://www.activityinfo.org/resources/query/form/{formId}

Où {formId} est l'identifiant alphanumérique du formulaire, tel que c1y5yyukfwb6x077. Vous pouvez trouver l'ID du formulaire dans l'URL de votre navigateur, ou vous pouvez le trouver en sélectionnant "Exporter", puis "Exporter via l'API", puis "Interroger tous les champs au format JSON"

La requête par défaut inclura :

  • L'ID de l'enregistrement dans une colonne appelée "_id"
  • L'heure de la dernière modification de l'enregistrement dans une colonne appelée "_lastEditTime", en tant que nombre de secondes depuis 1970-01-01
  • Deux colonnes pour les champs de point géographique dans le formulaire "{nom du champ}.latitude" et "{nom du champ}.longitude"
  • Une colonne pour chaque champ de texte, de quantité, de sélection unique, de numéro de série, de date et autres champs simples
  • Une colonne pour chaque champ de texte multiligne, tronquée à 128 caractères
  • Une colonne pour les champs à sélection multiple, avec les éléments sélectionnés séparés par des virgules.
  • Une colonne pour les sous-formulaires, affichant le nombre de sous-enregistrements
  • Une colonne pour chaque champ clé dans un formulaire référencé, sous la forme "{nom du champ de référence}.{nom du champ}"
  • Une colonne pour chaque champ dans le formulaire parent, au format "parent.{nom du champ}"

Si un champ a reçu un code dans le Concepteur de formulaires, alors le code apparaîtra dans la colonne, sinon l'étiquette complète du champ apparaîtra.

Interroger les sous-formulaires

Lors de l'interrogation d'un formulaire "parent", le tableau résultant ne peut pas inclure les enregistrements des sous-formulaires, car cela ne correspondrait pas au format tabulaire attendu par Power BI. Si vous souhaitez inclure des données provenant de sous-formulaires, vous devez interroger le sous-formulaire lui-même à partir de Power BI.

Vous pouvez le faire en naviguant du formulaire parent vers le sous-formulaire et en copiant l'URL de la requête à partir du sous-formulaire :

Cela inclura TOUS les sous-enregistrements dans ce sous-formulaire, même ceux qui appartiennent à un parent différent de la sélection actuelle :

Personnalisation de la requête

L'API de requête d'ActivityInfo vous permet de personnaliser les colonnes que vous recevez de l'API. Vous pouvez le faire en utilisant des "paramètres de requête" de l'URL dans column_name=field.

Par exemple, si vous souhaitez uniquement interroger le mois et le nombre de kits du sous-formulaire ci-dessus, vous pouvez composer l'URL :

https://www.activityinfo.org/resources/form/cn3wkxykmbwk6t59/query?reporting_month=month&total=KITS

Cela donnera le tableau suivant dans Power BI :

La première partie du paramètre, avant le signe égal, est le nom qui apparaîtra dans Power BI. La valeur après le signe égal peut être n'importe quelle formule ActivityInfo valide, y compris un ID de champ, un code ou une formule comme "HOMMES+FEMMES". Notez que les paramètres de requête doivent être encodés en URL, donc la formule "HOMMES+FEMMES" devrait être écrite comme :

https://www.activityinfo.org/resources/form/cn3wkxykmbwk6t59/query?total=MEN%2BWOMEN

Utilisation de la vue Tableau pour construire une requête

La vue Tableau d'ActivityInfo offre un moyen pratique de construire une requête personnalisée. Cliquez sur le bouton "Sélectionner les colonnes" pour ouvrir le volet de sélection des colonnes. Vous pouvez ensuite faire glisser de nouvelles colonnes sur le tableau, renommer les colonnes et ajouter des champs calculés à votre tableau :

Une fois que vous êtes satisfait de votre tableau, vous pouvez choisir "Interroger les champs sélectionnés au format JSON" dans le menu Exporter :

URL par défaut

La méthode par défaut génère une URL qui encode vos sélections dans la chaîne URL.

  • Sélectionnez "URL par défaut", puis cliquez sur le bouton "Générer l'URL".

Cela vous donnera une URL qui inclut précisément les champs que vous avez sélectionnés :

https://www.activityinfo.org/resources/form/cn3wkxykmbwk6t59/query?Record+ID=cn3wkxykmbwk6t59._id&Province=c4q7r1xkmbwj7942.c40qj9zkmbwjrmy3.E00000012490000000001&TOTAL=MEN+%2B+WOMEN

Le serveur d'ActivityInfo ne peut pas accepter les URL de plus de 2 048 caractères. Lorsque vous construisez une requête qui génère une URL de plus de 2 048 caractères, vous serez invité à utiliser l'option d'URL "courte" à la place.

URL courte

La méthode d'URL courte génère une URL plus petite, qui n'encode pas vos sélections dans la chaîne URL. Elle vous permet également d'utiliser l'API pour interroger des tableaux avec un grand nombre de champs ou avec des noms de colonnes très longs.

La méthode d'URL courte produit des sorties similaires à la méthode d'URL par défaut.

  • Sélectionnez "URL courte", puis cliquez sur le bouton "Générer l'URL".
Élément suivant
Publication sur Power BI Online