Guide FileMaker 18 Admin API

Ce guide fournit des informations sur l'utilisation de FileMaker Admin API version 2 (v2) pour effectuer des tâches administratives sur les produits FileMaker Cloud et FileMaker Server. (Pour en savoir plus sur FileMaker Admin API version 1 (v1), consultez la référence FileMaker Admin API installée avec les produits pris en charge.)

Ce guide part du principe que vous savez :

• utiliser FileMaker Pro Advanced pour uploader des bases de données. Consultez l'Aide FileMaker Pro Advanced.
• utiliser FileMaker Server ou un produit FileMaker Cloud pour héberger et gérer des bases de données. Consultez l'Aide FileMaker Server ou la documentation du produit FileMaker Cloud dans le Centre de Documentation produit.
• utiliser des API REST dans des applications côté serveur ou des services Web qui appellent les méthodes POST, GET, PATCH et DELETE avec des données au format JSON. Vous pouvez utiliser les langages de programmation ou les outils de votre choix.

Remarques

• FileMaker Cloud est un service permettant aux apps personnalisées qui utilisent FileMaker Pro Advanced, FileMaker Go et FileMaker WebDirect d'accéder au cloud. FileMaker Cloud utilise le système d'authentification intégré FileMaker ID pour authentifier les utilisateurs. Ce dernier est directement proposé par FileMaker, Inc.
• FileMaker Cloud for AWS est un service permettant aux apps personnalisées qui utilisent FileMaker Pro Advanced, FileMaker Go et FileMaker WebDirect d'accéder au cloud. FileMaker Cloud for AWS s'exécute sur le cloud Amazon Web Services (AWS) et est disponible via l'AWS Marketplace.
• Les produits FileMaker Cloud font référence à FileMaker Cloud et FileMaker Cloud for AWS.
• Ce guide utilise l'Admin Console pour faire référence à l'Admin Console de FileMaker Server, FileMaker Cloud for AWS et FileMaker Cloud, sauf si un produit en particulier est mentionné. FileMaker Cloud Admin Console désigne l'Admin Console des deux produits FileMaker Cloud, sauf si un produit en particulier est mentionné.
• App personnalisée, solution, base de données et fichier sont tous des termes représentant ce que vous créez et utilisez à l'aide des produits FileMaker.
• Ce guide utilise jeton d'accès pour faire référence au jeton Web JSON requis pour l'authentification.

FileMaker^® Admin API est une interface de programmation d'applications (API) qui permet aux services Web de réaliser des tâches administratives sur des produits FileMaker Cloud ou FileMaker Server. FileMaker Admin API utilisant une architecture REST (Representational State Transfer), elle peut donc être qualifiée d'API REST.

FileMaker Admin API renvoie ensuite des données au format JSON (JavaScript Object Notation), un format texte couramment utilisé avec les API REST, car il ne dépend d'aucun format de langage de programmation en particulier.

Pour utiliser FileMaker Admin API :

1. Rédigez du code qui utilise des appels FileMaker Admin API pour effectuer des tâches administratives.
2. Testez le fonctionnement de l'accès via FileMaker Admin API.
3. Surveillez les résultats obtenus en consultant gateway.log pour un produit FileMaker Cloud ou fac.log pour FileMaker Server, deux fichiers dans lesquels tous les appels API sont consignés. Vous pouvez télécharger le fichier gateway.log depuis FileMaker Cloud Admin Console. Le fichier fac.log se trouve dans le dossier suivant : .../FileMaker Server/Admin/FAC/logs.

Remarques

• Pour accéder aux données des bases de données hébergées, consultez le Guide FileMaker Data API.

Client API REST

1

6

Serveur Web

2

5

Moteur FileMaker Admin API

3

4

Serveur de base de données

Certains des appels FileMaker Admin API, par exemple les appels d'authentification, sont traités uniquement en fonction des deux premières étapes ci-dessous. D'autres appels, par exemple ceux liés à la création de programmes ou à la mise à jour de la configuration, sont traités en fonction de l'ensemble des étapes ci-dessous.

1. Un client API REST envoie un appel FileMaker Admin API (une requête HTTPS) au serveur Web.
2. Le serveur Web achemine la requête via le module de serveur Web FileMaker jusqu'au moteur FileMaker Admin API.
3. Le moteur FileMaker Admin API convertit la requête HTTPS (données URL et JSON) en un format compatible avec le serveur de base de données FileMaker.
4. Le serveur de base de données renvoie alors les résultats de la demande au moteur FileMaker Admin API.
5. Le moteur FileMaker Admin API convertit les résultats en une réponse HTTPS (données URL et JSON) et retransmet la réponse au serveur Web.
6. Le serveur Web envoie la réponse HTTPS au client API REST qui en fait la demande.

La référence FileMaker Admin API est installée avec FileMaker Server et les produits FileMaker Cloud. Elle fournit des informations détaillées sur tous les appels pris en charge par FileMaker Admin API.

Pour afficher cette référence pour le produit FileMaker Cloud utilisé, saisissez l'URL suivante dans une fenêtre de navigateur :

https://hôte/fmi/admin/apidoc/

où hôte est le nom d'hôte ou l'adresse IP du serveur virtuel exécutant le produit FileMaker Cloud.

Pour accéder à la référence pour FileMaker Server :

• Pour afficher cette référence dans une fenêtre de navigateur sur l'ordinateur maître, saisissez l'URL suivante :

  https://hôtelocal/fmi/admin/apidoc/

• Pour afficher cette référence dans une fenêtre de navigateur sur un ordinateur distant, saisissez l'URL suivante :

  https://hôte/fmi/admin/apidoc/

• Sur un serveur Windows, la référence se trouve dans le dossier suivant :

  [disque]:\Program Files\FileMaker\FileMaker Server\Documentation\Admin API Documentation

  où [disque] est le disque sur lequel se trouve le déploiement FileMaker Server.

  Si vous effectuez votre installation sur un emplacement sous Windows autre que celui par défaut, votre emplacement d'installation remplace la première partie du chemin d'installation par défaut :

  [disque]:emplacement_installation\FileMaker\FileMaker Server\Documentation\Admin API Documentation

• Sur un serveur macOS, les fichiers de référence se trouvent dans le dossier suivant :

  /Bibliothèque/FileMaker Server/Documentation/AdminAPI Documentation

Remarques

• Si vous utilisez les URL fournies à titre d'exemple dans la référence Admin API et que vous ouvrez le fichier de référence depuis votre disque en local, tous les exemples commencent par file:///. Pour utiliser les URL, remplacez file:/// par https://VotreNomHôte/fmi/admin/api/v2.

FileMaker Admin API fournit une API REST que vous pouvez utiliser pour automatiser certaines tâches administratives de routine en rédigeant des scripts au lieu de faire appel à l'Admin Console.

FileMaker Admin API opère un suivi de l'état des interactions. Vous pouvez commencer par un appel d'authentification ou utiliser d'autres appels pour l'authentification et poursuivre en utilisant le jeton d'accès renvoyé pour les appels suivants.

Ce jeton reste valide tant qu'il n'est pas invalidé au moyen de l'appel Invalidate Access Token (Invalider le jeton d'accès) ou pendant 15 minutes après le dernier appel qui a permis de le spécifier. (Tant que ce jeton est valide, chaque appel qui le spécifie réinitialise le compteur de délai d'expiration de session et le remet à zéro.)

Les appels API liés aux bases de données et les appels API de programme (à l'exception de ceux utilisés pour créer et modifier/exécuter les appels de programme) sont asynchrones et n'ont pas besoin de recevoir de réponse de la part du produit FileMaker Cloud ou de FileMaker Server. Il vous faudra peut-être suivre un appel asynchrone avec un appel GET pour confirmer que le statut du fichier a été modifié. Par exemple, suivez un appel de fermeture de base de données avec un appel GET databases pour confirmer leur fermeture. Si ce statut n'est pas immédiatement modifié, poursuivez la vérification.

Le reste des appels API sont synchrones et ont besoin de recevoir une réponse du produit FileMaker Cloud ou de FileMaker Server.

FileMaker Admin API utilise un jeton d'accès pour définir une connexion à l'hôte. Utilisez l'appel d'authentification pour demander un jeton d'accès à partir de l'hôte au moyen du nom de compte et du mot de passe de l'administrateur racine. Insérez un en-tête d'autorisation avec la valeur Basic chaîne codée en base64. La chaîne codée en base64 doit être générée sur le modèle nomutilisateur:motdepasse. Vous pouvez également utiliser le schéma d'authentification Basic pour d'autres appels.

Si vous utilisez le schéma d'authentification Basic pour l'appel d'authentification, la demande renvoie le jeton d'accès dans le corps de la réponse. Si vous utilisez le schéma d'authentification Basic pour d'autres appels, la demande renvoie le jeton d'accès dans la rubrique X-FM-Access-Token de l'en-tête de la réponse.

Pour les appels API suivants, utilisez le schéma d'authentification Bearer et insérez-y un en-tête d'autorisation avec la valeur Bearer jeton d'accès.

Remarques

• Chaque fois que vous utilisez le schéma d'authentification Basic pour obtenir un jeton d'accès, une nouvelle session API est créée. Pour éviter d'avoir plusieurs sessions API, utilisez le même jeton d'accès avec le schéma d'authentification Bearer pour tous les appels API.

FileMaker Admin API utilise un jeton d'accès pour définir une connexion à l'hôte.

Pour authentifier les comptes pour FileMaker Cloud :

1. Générez le jeton FileMaker ID. Consultez l'aide FileMaker Customer Console dans le Centre de Documentation produit.

2. Insérez le jeton FileMaker ID obtenu à l'étape 1 dans l'appel d'authentification ou les autres appels afin de générer un jeton d'accès.

   Par exemple, utilisez l'URL et l'en-tête suivants pour l'appel d'authentification :

   • URL : https://hôte/fmi/admin/api/v2/user/auth

     où hôte est le nom d'hôte ou l'adresse IP du serveur virtuel exécutant FileMaker Cloud.

   • En-tête : Authorization FMID Jeton_FileMaker_ID

   Si vous utilisez l'appel d'authentification, le jeton d'accès est renvoyé dans le corps de la réponse. Si vous utilisez d'autres appels, le jeton est renvoyé dans la rubrique X-FM-Access-Token de l'en-tête de la réponse.

3. Pour les appels API suivants, insérez l'en-tête d'autorisation suivant pour l'appel d'authentification :

   En-tête : Authorization Bearer jeton d'accès

Remarques

• Chaque fois que vous utilisez le schéma d'authentification FileMaker ID pour obtenir un jeton d'accès, une nouvelle session API est créée. Pour éviter d'avoir plusieurs sessions API, utilisez le même jeton d'accès avec le schéma d'authentification Bearer pour tous les appels API.

Le tableau suivant répertorie les appels FileMaker Admin API pris en charge pour FileMaker Server et les produits FileMaker Cloud.

• Le paramètre startupRestorationLogPath pour l'API FileMaker Server Admin indique le chemin d'accès au dossier pour l'enregistrement des fichiers journaux de restauration. Pour de meilleurs résultats, modifiez cet emplacement et choisissez un autre disque.
• Les produits FileMaker Cloud utilisent l'heure UTC pour le paramètre startTimeStamp.
• Pour filemakerScriptType, vous devez indiquer à la fois les paramètres fmScriptAccount et fmScriptPassword si vous voulez que le script s'exécute.
• Dans FileMaker Cloud, pour filemakerScriptType, utilisez le paramètre fmScriptAccount pour préciser le jeton FileMaker ID et le paramètre fmScriptPassword pour préciser le jeton d'actualisation FileMaker ID. Si vous ne précisez aucun jeton d'actualisation, le script ne peut pas s'exécuter une fois le jeton FileMaker ID arrivé à expiration. Pour en savoir plus sur la façon de générer le jeton, consultez l'Aide FileMaker Customer Console dans le Centre de Documentation produit.
• Si la valeur renvoyée pour le paramètre d'état dans l'appel List Databases (Répertorier les bases de données) est Normal, la base de données s'ouvre.