Importer des données depuis une API externe

Cet article décrit comment utiliser la fonctionnalité d'Importation pour importer des données depuis 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 autorisations suivants :

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

Format des données sources 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": "North Kivu", "code": "RD001" },
  { "name": "South Kivu", "code": "RD002" },
  { "name": "Ituri", "code": "RD003" }
]

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

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

• Les noms de champs doivent être cohérents, par conséquent l'exemple suivant ne fonctionnerait pas :

[
  { "location": "North Kivu" },
  { "loc": "South 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 encodés en Base64

• Jeton d'authentification : un jeton secret unique. 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 l'API

Pour importer des données depuis une API à l'aide de la fonctionnalité d'Importation, suivez ces étapes :

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

• Avoir un compte ActivityInfo
• Avoir accès au Formulaire
• Avoir les autorisations appropriées

2. Créez 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, allez à sa vue Tableau.
3. Sélectionnez l'outil « Importer » dans la barre d'outils.

4. Cliquez sur « Depuis l'API ».

5. Configurez l'importation 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électionnez la méthode d'authentification, en fonction du service externe : « Aucun(e) » pour une API publique par exemple ; « Jeton d'authentification » 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électionnez 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 alors choisir un chemin vers le tableau à importer.
   Dans cet exemple, sélectionnez « data » comme chemin de requête de l'API.

Si vous avez plusieurs chemins de données disponibles dans la liste déroulante, vous devez alors 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": "North Kivu",
      "code": "RD001"
    },
    {
      "name": "South 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 surlignée pour résoudre les problèmes. Pour plus d'informations, consultez Dépannage des problèmes liés à l'importateur.
   À cette étape, vous pouvez utiliser des filtres pour limiter les données que vous souhaitez importer.

Le filtrage n'est pas disponible pour les valeurs de champ de Référence multiple et les Champs non mappés. Le mappage du Champ cible n'est pas pris en charge.

Astuce : Vous pouvez configurer un Champ masqué 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 disposant de l'autorisation « 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 contient les aspects suivants :

• Source d'importation (« Depuis l'API » dans ce cas)
• URL de l'API, autorisation, chemin des données
• Correspondance des Champs, y compris les valeurs constantes
• Filtres, s'ils sont appliqués
• Les identifiants sont stockés, si vous utilisez l'authentification à cette étape. Bien que les identifiants ne soient pas visibles pour les autres utilisateurs, sachez que toute personne disposant de l'autorisation de gérer les configurations d'importation pourra utiliser les identifiants stockés pour réexécuter l'importation à l'avenir.

11. Examinez le résumé « Résumé de l'importation » :

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

12. Si vous enregistrez la configuration, saisissez une étiquette pour la configuration enregistrée, puis cliquez sur « Enregistrer & Importer les enregistrements » dans le coin supérieur droit.

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