Importer des données depuis une API externe

Cet article explique comment utiliser la fonctionnalité d'importation pour importer des données à partir d'une interface de programmation d'application (API) externe, et spécifie les exigences de format de l'API.

Pour suivre ce processus, vous devez avoir les rôles et permissions suivants :

• Permission d'ajouter des enregistrements au Formulaire cible
• Modifier les enregistrements si vous mettez à jour des enregistrements existants
• Ajouter des Formulaires, des dossiers et des rapports (pour pouvoir concevoir le Formulaire, si vous avez besoin d'un nouveau Formulaire)

Format de données source pris en charge

• L'API doit fournir une réponse au format JSON
• La réponse JSON doit contenir un tableau d'objets JSON, par exemple :

[
  { "name": "Nord Kivu", "code": "RD001" },
  { "name": "Sud Kivu", "code": "RD002" },
  { "name": "Ituri", "code": "RD003" }
]

• Les objets imbriqués sont pris en charge, donc l'exemple suivant serait correct :

{ "status": "OK",
  "data": 
    [  
      { "name": "Nord Kivu", "code": "RD001" },
      { "name": "Sud Kivu", "code": "RD002" }, 
      { "name": "Ituri", "code": "RD003" }
    ]
}

• Les noms de Champs doivent être cohérents, donc l'exemple suivant ne fonctionnerait pas :

[
  { "location": "Nord Kivu" },
  { "loc": "Sud Kivu" },
  { "Location": "Ituri" }
]

• Le point de terminaison de l'API doit prendre en charge la requête HTTP GET

• Si l'API n'est pas publique, deux types d'en-têtes Authorization sont pris en charge :

• Authentification d'accès de base : un nom d'utilisateur et un mot de passe en codage Base64

• Jeton de porteur : un seul jeton secret. ActivityInfo enverra l'en-tête d'autorisation au format "Bearer " dans le cadre de la requête

• Accessible via HTTPS

Importer des données depuis une API

Pour importer des données depuis une API en utilisant la fonctionnalité d'importation, suivez ces étapes :

1. Vérifiez si vous remplissez les conditions préalables :

• Avoir un compte ActivityInfo
• Accès au Formulaire
• Permissions appropriées

2. Créer un Formulaire dans lequel vous allez importer les données. Il est important de définir la structure du Formulaire avant d'importer les données.
   Si vous avez déjà un Formulaire, naviguez vers la vue Tableau de celui-ci.
3. Sélectionner l'outil "Importer" dans la barre d'outils.

4. Cliquez sur "Depuis API".

5. Configurer l'importation de l'API en remplissant les Champs suivants :

• URL de l'API : collez le lien ici. Seuls les protocoles sécurisés sont pris en charge (https).
• Sélectionner la méthode d'authentification, en fonction du service externe : "Aucune" pour une API publique par exemple ; "Jeton de porteur" ou "Authentification de base". Consultez la documentation de l'API que vous utilisez pour déterminer quelle méthode d'authentification est prise en charge.

6. Cliquez sur "Continuer" et attendez que les données se chargent.
7. Sélectionner le chemin des données dans la fenêtre d'aperçu des données. Si l'API ne fournit pas directement un tableau d'objets, vous devez choisir un chemin vers le tableau à importer.
   Dans cet exemple, sélectionnez "data" comme chemin de requête de l'API.

Si plusieurs chemins de données sont disponibles dans la liste déroulante, vous devez déterminer quelle partie de la réponse vous souhaitez importer.
Dans cet exemple, vous pouvez voir qu'il y a deux tableaux d'objets ("provinces" et "changes") dans la réponse de l'API :

{
  "status": "OK",
  "provinces": [
    {
      "name": "Nord Kivu",
      "code": "RD001"
    },
    {
      "name": "Sud Kivu",
      "code": "RD002"
    }
  ],
  "changes": [
    { 
      "date": "2025-01-01",
      "version": 1
    },
    {
      "date": "2025-03-02",
      "version": 2
    }
  ]
}

Vous ne pouvez pas importer les deux tableaux en même temps, vous devez choisir un chemin de données dans la liste déroulante.

7. Cliquez sur "Continuer" et attendez que les enregistrements se chargent.

8. Il est temps de faire correspondre les colonnes et de valider les Champs, en cliquant sur chaque colonne mise en évidence pour résoudre les problèmes. Pour plus d'informations, voir Résolution des problèmes liés à l'importateur.
   Dans cette étape, vous pouvez utiliser des filtres pour limiter les données que vous souhaitez importer.

Le filtrage n'est pas disponible sur les valeurs de Champs de référence multiples et les Champs non mappés. Le mappage des Champs cibles n'est pas pris en charge.

Conseil : Vous pouvez configurer un Champ caché avec une valeur par défaut dans votre Formulaire pour activer le filtrage sur le Champ source non mappé. De cette façon, le Champ non mappé devient un Champ mappé.

9. Après avoir résolu les incohérences, cliquez sur "Continuer" dans le coin supérieur droit.
10. Les utilisateurs avec la permission “Gérer les configurations d'importation” peuvent choisir d'enregistrer cette configuration d'importation pour des importations de données répétées, et de la partager avec d'autres utilisateurs de la Base de données. Les configurations enregistrées ne sont pas exécutées automatiquement.

L'option de configuration enregistrée comprend les aspects suivants :

• Source d'importation ("Depuis API" dans ce cas)
• URL de l'API, autorisation, chemin des données
• Correspondance des Champs, y compris les valeurs constantes
• Filtres, si appliqués
• Les informations d'identification sont stockées, si vous utilisez l'authentification à l'étape. Bien que les informations d'identification ne soient pas visibles par les autres utilisateurs, sachez que toute personne ayant la permission de gérer la configuration d'importation pourra utiliser les informations d'identification stockées pour relancer l'importation à l'avenir.

11. Examiner l'aperçu du "Résumé de l'importation" :

• Si tout est correct, passez à l'étape suivante.
• Si vous devez recommencer, cliquez sur "Annuler".
• Pour revenir à la partie du processus de correspondance des colonnes et de validation des Champs, cliquez sur "Retour".
• Basculer le commutateur "Enregistrer la configuration" pour enregistrer cette configuration d'importation, et cliquez sur "Continuer" dans la fenêtre contextuelle.

12. Si vous enregistrez la configuration, tapez une étiquette pour la configuration enregistrée, puis cliquez sur "Enregistrer et Importer les enregistrements" dans le coin supérieur droit.

13. Si vous n'enregistrez pas une configuration personnalisée, cliquez sur "Importer les enregistrements" dans le coin supérieur droit et attendez que les mises à jour se chargent.