Guide FileMaker 16 Data API
A propos de FileMaker Data API
Présentation
FileMaker® Data API est une interface de programmation d'applications (API) qui permet aux services Web d'accéder aux données se trouvant dans des solutions hébergées. FileMaker Data API utilisant une architecture REST (Representational State Transfer), elle peut donc être qualifiée d'API REST.
Votre service ou votre application Web appelle FileMaker Data API afin d'obtenir un jeton d'authentification lui permettant d'accéder à une solution hébergée, puis utilise ce jeton lors des appels suivants pour créer des enregistrements, les mettre à jour, les supprimer et exécuter des requêtes.
FileMaker Data API renvoie des données au format JSON (JavaScript Object Notation), un format de données couramment utilisé avec les API REST, car il ne dépend d'aucun format de langage de programmation en particulier.
Ce guide part du principe que vous savez :
- utiliser FileMaker Pro pour créer des bases de données. Vous devez comprendre les bases de la conception des bases de données avec FileMaker Pro, ainsi que les concepts de rubriques, de liens, de modèles, de tables externes et d'objets Conteneur. Consultez l'Aide FileMaker Pro.
- utiliser FileMaker Server pour héberger des solutions. Vous devez comprendre comment déployer FileMaker Server, activer l'accès à des solutions hébergées et surveiller les solutions hébergées avec l'Admin Console FileMaker Server. Consultez l'Aide FileMaker Server.
- utiliser des API REST dans des applications ou des services Web côté serveur qui appellent les méthodes POST, GET, PUT et DELETE avec des données au format JSON. Vous pouvez utiliser les langages de programmation ou les outils de votre choix.
Pour utiliser FileMaker Data API, procédez comme suit :
- Préparez votre base de données pour un accès via FileMaker Data API avec FileMaker Pro. Vous pouvez créer une base de données ou préparer une base de données existante. Consultez la section Préparer les bases de données pour un accès via FileMaker Data API.
- Ecrivez un code qui appelle les méthodes FileMaker Data API afin de rechercher, de créer, de modifier et de supprimer des enregistrements dans une solution hébergée. Consultez la section Ecrire des appels FileMaker Data API.
- Hébergez votre solution à l'aide de FileMaker Server tout en activant l'accès via FileMaker Data API. Consultez la section Héberger une solution FileMaker Data API.
- Testez le fonctionnement de l'accès via FileMaker Data API. Consultez la section Tester une solution FileMaker Data API.
- Surveillez votre solution hébergée avec l'Admin Console. Consultez la section Surveiller les solutions FileMaker Data API.
Comment traiter un appel FileMaker Data API
-
Un client API REST envoie un appel FileMaker Data API (requête HTTPS) au serveur Web FileMaker Server sur le port HTTPS. Il est inutile d'installer ou d'exécuter FileMaker Pro.
Le port HTTPS est le port 443 par défaut. Toutefois, au moment d'installer FileMaker Server, l'administrateur serveur peut indiquer un autre port.
- Le serveur Web achemine la requête via le module serveur Web FileMaker jusqu'au moteur FileMaker Data API.
- Le moteur FileMaker Data API convertit la requête HTTPS (URL et données JSON) en un format que le composant serveur de base de données peut comprendre, puis envoie des demandes de données à la solution hébergée par le serveur de base de données.
- Le serveur de base de données renvoie les données FileMaker demandées au moteur FileMaker Data API.
- Le moteur FileMaker Data API convertit les données FileMaker en une réponse HTTPS (URL avec données JSON) pour répondre à l'appel, retransférant ainsi les données au serveur Web.
- Le serveur Web envoie la réponse HTTPS au client API REST qui en fait la demande.
La disponibilité des ports 3000 et 8989 est indispensable pour un bon fonctionnement du moteur FileMaker Data API.
La disponibilité du port 5003 est indispensable pour un bon fonctionnement du serveur de base de données.
Alternatives à la publication Web
Si vous ne maîtrisez pas bien les API REST, envisagez les solutions suivantes pour publier vos données FileMaker sur Internet.
FileMaker WebDirect™ : Les utilisateurs Web se connectent à votre solution hébergée sur FileMaker Server pour visualiser, modifier, trier ou rechercher des enregistrements en fonction des droits d'accès que vous leur donnez. Ils n'ont pas besoin d'installer d'autres logiciels. Un navigateur Web compatible et un accès à Internet ou à un intranet suffisent. L'interface utilisateur ressemble à la version bureau de l'application FileMaker Pro. Les pages et les formulaires Web sur lesquels l'utilisateur Web interagit dépendent des modèles et des affichages définis dans la base de données FileMaker Pro.
Consultez le Guide de FileMaker WebDirect.
Publication statique : Si vous ne modifiez pas souvent vos données ou si vous ne souhaitez pas que les utilisateurs puissent se connecter directement à votre base de données, vous pouvez faire appel à la publication statique. Avec cette dernière, vous exportez les données FileMaker Pro pour créer une page Web, que vous pouvez ensuite personnaliser à l'aide du langage HTML. Ainsi, la page Web ne change pas lorsque des données de la base sont modifiées et les utilisateurs ne se connectent pas à votre base de données.
Consultez la section Publication de données sur des pages Web statiques de l'Aide FileMaker Pro.
Publication Web personnalisée : Pour intégrer votre base de données FileMaker dans un site Web personnalisé, utilisez les technologies de Publication Web personnalisée.
Consultez le Guide de la publication Web personnalisée FileMaker Server.
Préparer les bases de données pour un accès via FileMaker Data API
Choisir les données auxquelles accéder
Vous pouvez créer une base de données FileMaker Pro et l'utiliser avec FileMaker Data API ou utiliser une base de données existante. Si vous créez une base de données, vous pouvez concevoir les modèles et rubriques nécessaires à votre solution FileMaker Data API. Si vous utilisez une base de données existante, envisagez de créer un modèle spécifique à votre solution FileMaker Data API.
Les appels FileMaker Data API qui accèdent aux données des enregistrements vous obligent à spécifier un modèle. FileMaker Data API utilise la vue par défaut définie pour le modèle que vous avez spécifié. Indiquez un modèle qui définit la Vue Formulaire comme vue par défaut. Si au contraire vous utilisez un modèle qui définit la Vue Tableau comme vue par défaut, FileMaker Data API ne sera pas en mesure d'obtenir des données des enregistrements liés.
Protéger les solutions hébergées
FileMaker Data API impose que votre code d'API REST se connecte à une solution au moyen d'un compte protégé par mot de passe. Affectez des mots de passe aux comptes de base de données utilisés pour accéder à l'API REST ou utilisez un fournisseur de service OAuth pour ces comptes.
Remarque :Au moment de définir les noms des comptes et les mots de passe des solutions FileMaker Data API, utilisez des caractères ASCII imprimables, par exemple a-z, A-Z et 0-9. Pour sécuriser davantage encore les noms des comptes et les mots de passe, intégrez des caractères de ponctuation du type « ! » et « % », mais n'utilisez pas les deux points. Consultez l'Aide FileMaker Pro.
Activer l'accès via FileMaker Data API
Vous devez activer le privilège étendu Accès via FileMaker Data API dans chaque base de données à laquelle vous souhaitez accéder avec FileMaker Data API. Si vous n'activez pas le privilège étendu FileMaker Data API dans la base de données, les applications d'API REST ne pourront pas utiliser FileMaker Data API pour accéder à la base de données, même si celle-ci est hébergée par FileMaker Server.
Pour activer l'accès à une base de données via FileMaker Data API :
- Dans FileMaker Pro, ouvrez la base de données en utilisant un compte bénéficiant du jeu de privilèges Accès intégral. Une autre possibilité consiste à ouvrir la base de données en utilisant un compte bénéficiant des privilèges d'accès Gérer les autorisations étendues.
- Dans l'onglet Privilèges étendus de la boîte de dialogue Gérer la sécurité, sélectionnez le privilège étendu fmrest pour l'activer.
- Assignez à un ou plusieurs comptes les jeux de privilèges qui intègrent le privilège étendu fmrest.
Remarque :Pour des raisons de sécurité, activez uniquement le privilège étendu fmrest dans les jeux de privilèges des comptes que vous souhaitez autoriser à accéder à votre solution hébergée.
Consultez la section Création et modification de jeux de privilèges de l'Aide FileMaker Pro.
Ecrire des appels FileMaker Data API
Fonctions FileMaker Data API
FileMaker Data API propose une API REST pour accéder aux données des solutions hébergées. Avec FileMaker Data API, votre code :
- se connecte à une solution hébergée ou s'en déconnecte. Consultez la section Appels permettant de se connecter à une base de données ou de s'en déconnecter.
- crée, modifie, supprime ou obtient un enregistrement ou une plage d'enregistrements. Consultez la section Appels utilisant des enregistrements.
- exécute des requêtes. Consultez la section Appel exécutant des requêtes.
- définit des valeurs de rubrique de type Global. Consultez la section Appel définissant des valeurs de rubrique de type Global.
FileMaker Data API ne prend pas en charge :
- l'upload des données dans des rubriques Conteneur ;
- l'accès aux données dans des sources de données ODBC externes ;
- les plug-ins FileMaker ;
- l'exécution de scripts FileMaker ;
- l'activation des déclencheurs de script.
FileMaker Data API renvoie les données de rubrique telles qu'elles sont stockées dans la base de données et non telles qu'elles sont affichées dans FileMaker Pro.
Informations de référence sur FileMaker Data API
Quand vous avez installé FileMaker Server, vous avez installé les fichiers de référence FileMaker Data API. Cette référence fournit des informations détaillées sur tous les appels autorisés par FileMaker Data API.
- Pour afficher cette référence dans une fenêtre de navigateur sur l'ordinateur maître, saisissez l'URL
https://localhost/fmi/rest/apidoc/
- Pour afficher cette référence dans une fenêtre de navigateur sur un ordinateur distant, saisissez l'URL
https://
hôte
/fmi/rest/apidoc/
oùhôte
est l'adresse IP ou le nom d'hôte de l'ordinateur maître exécutant FileMaker Server. Sur un serveur Windows, les fichiers de référence se trouvent dans le dossier
[lecteur]
:\Program Files\FileMaker\FileMaker Server\Documentation\Data API Documentation
où[lecteur]
est le lecteur sur lequel se trouve le déploiement FileMaker Server.Si vous effectuez votre installation sur un emplacement sous Windows autre que l'emplacement par défaut, votre emplacement d'installation remplace la première partie du chemin d'installation par défaut
[emplacement_installation]
:\Documentation\Data API Documentation- Sur un serveur macOS, les fichiers de référence se trouvent dans le dossier
/Library/FileMaker Server/Documentation/Data API Documentation
Remarques concernant les formats de données
- Toutes les valeurs de données doivent utiliser le codage URL également appelé %-encodage, ce qui est normal pour les requêtes HTTP. Par exemple, pour indiquer un nom de modèle qui inclut un caractère barre oblique, vous devez spécifier le caractère barre oblique sous forme de valeur encodée : « %2F ».
- Les rubriques et les tables externes que vous spécifiez doivent figurer dans le modèle que vous indiquez.
- Pour spécifier les rubriques liées, utilisez impérativement la syntaxe
nomtable::rubrique-liée
- Pour utiliser des valeurs de rubrique (2 et au-delà), vous devez utiliser la syntaxe
nomtable::rubrique-liée(nombre-répétition)
- Si vous modifiez des enregistrements, vous devez utiliser la syntaxe applicable à l'identifiant de l'enregistrement
nomtable::rubrique-liée(nombre-répétition).id-enregistrement
- Pour des données de rubrique Conteneur, FileMaker Data API renvoie à l'objet de données de type Conteneur une URL contenant la référence au chemin.
Composants d'appel API REST
Les appels FileMaker Data API utilisent différents composants.
Composant | Description |
---|---|
Méthode HTTP (également appelée verbe HTTP) |
FileMaker Data API utilise les méthodes HTTP suivantes :
|
En-tête HTTP |
FileMaker Data API utilise les en-têtes suivants :
|
Appel URL | Les URL FileMaker Data API commencent toutes par : /fmi/rest/api/ |
Données de paramètres au format JSON | Inutiles pour se déconnecter d'une solution, supprimer un enregistrement, obtenir un seul enregistrement ou obtenir une plage d'enregistrements |
Appels permettant de se connecter à une base de données ou de s'en déconnecter
FileMaker Data API utilise un jeton d'accès pour définir une connexion à une base de données. Ce jeton d'accès doit figurer dans l'en-tête de tous les appels effectués par la suite auprès de la solution hébergée. Il est valide jusqu'à ce que vous vous déconnectiez d'une solution ou pendant une durée de 15 minutes après le dernier appel ayant 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.)
Se connecter à une solution
Pour vous connecter à une solution hébergée, utilisez une méthode HTTP POST avec l'URL auth
indiquant le nom d'une solution hébergée.
Si le nom de compte et le mot de passe sont authentifiés, votre code reçoit un jeton d'accès qui définit votre connexion à la solution.
Méthode HTTP | POST |
---|---|
URL | /fmi/rest/api/auth/solution solution est le nom de la base de données hébergée |
En-tête HTTP | Content/Type: application/json |
Paramètres | Nom de compte et mot de passe pour se connecter à la solution hébergée, ainsi que le modèle sur lequel basculer après la connexion, au format JSON. Par exemple : {
"user":"admin",
"password":"admin",
"layout":"Tâches"
} |
Réponse | Jeton d'accès, modèle actif et code d'erreur de 0. Par exemple : {
"errorCode": "0",
"layout": "Tâches",
"token": "fdde29fa175eb1cc8347512ca327b191619fc32ed65efaab26d8"
}
Consultez la section Codes d'erreur. |
Se connecter à une solution avec un fournisseur d'identité OAuth
Pour vous connecter à une solution hébergée, utilisez une méthode HTTP POST avec l'URL auth
indiquant le nom d'une solution hébergée.
Si le nom de compte et le mot de passe sont authentifiés, votre code reçoit un jeton d'accès qui définit votre connexion à la solution.
Méthode HTTP | POST |
---|---|
URL | /fmi/rest/api/auth/solution solution est le nom de la base de données hébergée |
En-tête HTTP | Content/Type: application/json X-FM-Data-Login-Type: oauth |
Paramètres | L'identifiant de requête OAuth qui contient l'URL de rappel pour authentification, l'identifiant OAuth renvoyé par le fournisseur d'identité OAuth et le modèle sur lequel basculer après la connexion. Toutes les données doivent être au format JSON. Par exemple : {
"oAuthRequestId":"E65B98CC17429CO643A31119F",
"oAuthIdentifier":"B164A4629A776E5177445DR223",
"layout":"Contacts"
} |
Réponse | Jeton d'accès, modèle actif et code d'erreur de 0. Par exemple : {
"errorCode": "0",
"layout": "Contacts",
"token": "fdde35fa175eb1cc8621782fd327b191619fc32ed65efaab26d8"
}
Consultez la section Codes d'erreur. |
Pour obtenir les paramètres OAuth au format JSON :
-
Obtenez la liste des fournisseurs OAuth pris en charge en utilisant une méthode HTTP GET avec cette URL :
https://hôte/fmws/oauthproviderinfo
où <hôte> correspond à l'adresse IP ou au nom de domaine de l'ordinateur maître dans votre déploiement FileMaker Server. Cette liste est renvoyée au format JSON.
- Sélectionnez un fournisseur OAuth pris en charge, puis obtenez un identifiant de suivi pour votre solution.
-
Utilisez une méthode HTTP GET avec cette URL :
http://hôte/oauth/getoauthurl?trackingID=ID-suivi&provider=fournisseur-OAuth&address=127.0.0.1&X-FMS-OAuth-AuthType=2
où hôte est l'adresse IP ou le nom de domaine de l'ordinateur maître dans votre déploiement FileMaker Server, ID-suivi est l'identifiant de suivi généré par le développer pour votre solution et fournisseur-OAuth est le nom du fournisseur OAuth sélectionné.
L'en-tête HTTP de cette requête doit inclure les éléments suivants :
- X-FMS-Application-Type: 9
- X-FMS-Application-Version: 15
- X-FMS-Return-URL: http://127.0.0.1/
- Lisez l'en-tête de réponse pour les données X-FMS-Request-ID. Cet en-tête de réponse contient l'identifiant de requête OAuth que vous utiliserez pour vous connecter.
- Lisez l'en-tête de réponse pour les données X-FMS-Return-URL. Appelez l'URL renvoyée dans ce paramètre pour autoriser l'utilisateur à s'authentifier auprès du fournisseur OAuth.
- L'« identifiant » renvoyé par le fournisseur OAuth correspond au paramètre d'identifiant OAuth que vous utiliserez pour vous connecter.
Consultez la section Création de comptes authentifiés via un fournisseur d'identité OAuth de l'Aide FileMaker Pro.
Se déconnecter d'une solution
Lorsque votre code a fini d'accéder à la solution hébergée, utilisez une méthode HTTP DELETE avec l'URL auth
indiquant le nom de la solution hébergée.
Le jeton de la session est envoyé dans l'en-tête de la requête.
Si votre code ne permet pas de se déconnecter de la solution hébergée, le jeton d'accès perd sa validité au moment où la session FileMaker Data API expire, soit 15 minutes après le dernier appel ayant permis de spécifier ce jeton.
Méthode HTTP | DELETE |
---|---|
URL | /fmi/rest/api/auth/solution solution est le nom de la base de données hébergée |
En-tête HTTP | FM-Data-token correspond au jeton d'accès renvoyé suite à l'appel ayant permis de se connecter à la solution |
Paramètres | Aucun |
Réponse | Un code d'erreur de 0. Par exemple : {
"errorCode": "0"
}
Consultez la section Codes d'erreur. |
Appels utilisant des enregistrements
Créer un enregistrement
Pour créer un enregistrement, utilisez une méthode HTTP POST avec l'URL record
indiquant le nom de la solution et le modèle.
Méthode HTTP | POST |
---|---|
URL | /fmi/rest/api/record/solution/modèle solution est le nom de la base de données hébergée |
En-tête HTTP | Content/Type: application/json FM-Data-token correspond au jeton d'accès renvoyé suite à l'appel ayant permis de se connecter à la solution |
Paramètres | Données d'enregistrement au format JSON contenant des paires rubrique/valeur qui indiquent les valeurs des rubriques dans le modèle cible. Par exemple : {"data":
{
"field_1": "value_1",
"field_2": "value_2",
"repetitionField(1)" : "fieldValue",
"Commandes::DateCommande.0":"12/22/2015"
}
}
Remarque :Pour créer un enregistrement vide avec des valeurs par défaut pour chaque rubrique, indiquez comme paramètre un objet de données vide au format JSON. Par exemple : {"data":
{
}
} |
Réponse | Un code d'erreur de 0 et l'identifiant de l'enregistrement créé. Par exemple : {
"errorCode": "0",
"recordId": "25"
}
Consultez la section Codes d'erreur. |
Remarques
- Quand vous créez des enregistrements avec FileMaker Data API, vous validez les rubriques. Si la validation des rubriques n'est pas acceptée pour les données, vous recevez un message d'erreur et l'enregistrement n'est pas créé.
-
Pour créer un enregistrement lié, ignorez l'identifiant de l'enregistrement ou utilisez la valeur 0 (zéro) comme identifiant de l'enregistrement lié, suivie par la valeur de la nouvelle rubrique.
Par exemple, pour créer un enregistrement lié, utilisez au choix :
"Commandes::DateCommande" : "12/22/2017" "Commandes::DateCommande.0" : "12/22/2017"
Un seul enregistrement lié peut être créé par appel de création d'enregistrement.
Modifier un enregistrement
Pour modifier un enregistrement, utilisez une méthode HTTP PUT avec l'URL record
indiquant le nom de la solution, le modèle et l'identifiant de l'enregistrement.
Méthode HTTP | PUT |
---|---|
URL | /fmi/rest/api/record/solution/modèle/recordid solution est le nom de la base de données hébergée |
En-tête HTTP | Content/Type: application/json FM-Data-token correspond au jeton d'accès renvoyé suite à l'appel ayant permis de se connecter à la solution |
Paramètres | Données d'enregistrement au format JSON contenant des paires rubrique/valeur à mettre à jour. Les données peuvent indiquer des tables externes ou des enregistrements figurant dans le modèle. Seules les rubriques que vous indiquez sont mises à jour. Les autres rubriques de l'enregistrement restent inchangées. Si « {} » est fourni en tant que valeur de données, l'enregistrement cible n'est pas mis à jour. Paramètres facultatifs : identifiant de modification. En indiquant un identifiant de modification, vous garantissez que vous modifiez bien la version actuelle d'un enregistrement. Si la valeur de l'identifiant de modification ne correspond pas à la valeur de l'identifiant de modification actuel figurant dans la base de données, l'enregistrement n'est pas modifié. Par exemple : {"data":
{
"prénom": "Bob",
"nom": "Smith",
"équipement(2)" : "PC",
"Commandes::DateCommande.2":"12/20/2017",
"Commandes::DateCommande.0":"12/22/2017", // crée un enregistrement "Commandes" lié avec 0 en tant que recordId
"deleteRelated": "Commandes.3" // supprime un enregistrement "Commandes" avec la chaîne "deleteRelated"
},
modId: "3"
} |
Réponse | Un code d'erreur de 0 et l'identifiant de l'enregistrement modifié. Par exemple : {
"errorCode": "0",
"recordId": "53"
}
Consultez la section Codes d'erreur. |
Remarques
- Quand vous modifiez des enregistrements avec FileMaker Data API, vous validez les rubriques. Si la validation des rubriques n'est pas acceptée pour les données, vous recevez un message d'erreur et l'enregistrement n'est pas mis à jour.
-
Pour créer un enregistrement lié, ignorez l'identifiant de l'enregistrement ou utilisez la valeur 0 (zéro) comme identifiant de l'enregistrement lié, suivie par la valeur de la nouvelle rubrique.
Par exemple, pour créer un enregistrement lié, utilisez au choix :
"Commandes::DateCommande" : "12/22/2017" "Commandes::DateCommande.0" : "12/22/2017"
Un seul enregistrement lié peut être créé par appel de modification d'enregistrement. -
Pour supprimer un enregistrement lié, utilisez la chaîne « deleteRelated » suivie de l'enregistrement lié à supprimer.
Par exemple :
"deleteRelated" : "Commandes.3"
Un seul enregistrement lié peut être supprimé par appel de modification d'enregistrement.
Supprimer un enregistrement
Pour supprimer un enregistrement, utilisez une méthode HTTP DELETE avec l'URL record
indiquant le nom de la solution, le modèle et l'identifiant de l'enregistrement.
Méthode HTTP | DELETE |
---|---|
URL | /fmi/rest/api/record/solution/modèle/recordid solution est le nom de la base de données hébergée |
En-tête HTTP | FM-Data-token correspond au jeton d'accès renvoyé suite à l'appel ayant permis de se connecter à la solution |
Paramètres | Aucun |
Réponse | Un code d'erreur de 0. Par exemple : {
"errorCode": "0"
}
Consultez la section Codes d'erreur. |
Obtenir un seul enregistrement
Pour obtenir un enregistrement, utilisez une méthode HTTP GET avec l'URL record
indiquant le nom de la solution, le modèle et l'identifiant de l'enregistrement.
Vous pouvez également indiquer des informations de table externe pour limiter le nombre d'enregistrements liés renvoyés.
Méthode HTTP | GET |
---|---|
URL | Format 1 :
/fmi/rest/api/record/solution/modèle/recordid solution est le nom de la base de données hébergée Pour le mot-clé de la table externe : La partie de l'URL correspondant à la table externe est facultative. Si le modèle inclut des tables externes, indiquez leur nom pour améliorer les performances. Si la partie relative aux tables externes est ignorée, l'appel renvoie tous les enregistrements liés dans toutes les tables externes du modèle. |
En-tête HTTP | FM-Data-token correspond au jeton d'accès renvoyé suite à l'appel ayant permis de se connecter à la solution |
Paramètres | Aucun |
Réponse | Un code d'erreur de 0 et les données de l'enregistrement au format JSON. Par exemple : {
"errorCode": "0",
"record": "{...}"
}
Consultez la section Codes d'erreur. |
Remarques
- Pour limiter le nombre d'enregistrements liés renvoyés, FileMaker Data API prend en charge l'option Barre de défilement vertical dans la boîte de dialogue Table externe. Si cette option est sélectionnée, FileMaker Data API renvoie les 50 premières rangées depuis la table externe. Si cette option n'est pas sélectionnée, FileMaker Data API renvoie le nombre de rangées indiqué pour l'option Nombre de rangées.
- Pour parcourir les rangées de la table externe, utilisez la syntaxe
offset.<nom-table>
etrange.<nom-table>
, où<nom-table>
est la valeur spécifiée pour la table externe dans FileMaker Pro, dans l'Inspecteur. Si vous ignorez les valeurs de décalage et de plage pour les rangées de la table externe, la valeur de décalage par défaut est de 1 et la plage par défaut est de 50.
Obtenir une plage d'enregistrements
Pour obtenir une plage d'enregistrements, utilisez une méthode HTTP GET avec l'URL record
indiquant le nom de la solution, le modèle et des informations supplémentaires (enregistrement de départ et nombre d'enregistrements).
Vous pouvez éventuellement indiquer l'ordre de tri des enregistrements.
Vous pouvez également indiquer des informations de table externe pour limiter le nombre d'enregistrements liés renvoyés.
Méthode HTTP | GET |
---|---|
URL | Format 1 :
/fmi/rest/api/record/solution/modèle?offset=enregistrement-départ&range=nombre-enregistrements solution est le nom de la base de données hébergée Pour l'ordre de tri, les informations doivent être indiquées au format JSON. nom-rubrique est le nom d'une rubrique à utiliser comme point de départ pour le tri des enregistrements. Vous pouvez indiquer plusieurs noms de rubrique. Pour l'ordre de tri, indiquez le mot-clé « ascend » ou « descend » ou spécifiez un nom de liste de valeurs pour nom-liste-valeur. Pour le mot-clé de la table externe : La partie de l'URL correspondant à la table externe est facultative. Si le modèle inclut des tables externes, il vous faudra peut-être indiquer leur nom pour améliorer les performances. Si la partie relative aux tables externes est ignorée, l'appel renvoie tous les enregistrements liés dans toutes les tables externes du modèle. |
En-tête HTTP | FM-Data-token correspond au jeton d'accès renvoyé suite à l'appel ayant permis de se connecter à la solution |
Paramètres | Aucun |
Réponse | Un code d'erreur de 0 et les données de la plage d'enregistrements au format JSON. Par exemple : {
"errorCode": "0",
"records": "[...]"
}
Consultez la section Codes d'erreur. |
Remarques
- Si vous ignorez les valeurs de décalage et de plage, la valeur de décalage par défaut est de 1 et la plage par défaut est de 100 :
offset=1&range=100
- Si vous ignorez les valeurs d'ordre de tri, la valeur par défaut est
&sort=[{ "fieldName": "recordId", "sortOrder": "ascend" }]
- Pour limiter le nombre d'enregistrements liés renvoyés, FileMaker Data API prend en charge l'option Barre de défilement vertical dans la boîte de dialogue Table externe. Si cette option est sélectionnée, FileMaker Data API renvoie les 50 premières rangées depuis la table externe. Si cette option n'est pas sélectionnée, FileMaker Data API renvoie le nombre de rangées indiqué pour l'option Nombre de rangées.
- Pour parcourir les rangées de la table externe, utilisez la syntaxe
offset.<nom-table>
etrange.<nom-table>
, où<nom-table>
est la valeur spécifiée pour la table externe dans FileMaker Pro, dans l'Inspecteur. Si vous ignorez les valeurs de décalage et de plage pour les rangées de la table externe, la valeur de décalage par défaut est de 1 et la plage par défaut est de 50.
Appel exécutant des requêtes
Pour exécuter une requête, utilisez une méthode HTTP POST avec l'URL find
indiquant le nom de la solution, le modèle et des informations supplémentaires (rubriques de recherche et critères, ordre de tri, enregistrement de départ et nombre d'enregistrements).
Vous pouvez également indiquer les informations de la table externe pour trouver les enregistrements liés.
Méthode HTTP | POST |
---|---|
URL | /fmi/rest/api/find/solution/modèle solution est le nom de la base de données hébergée |
En-tête HTTP | FM-Data-token correspond au jeton d'accès renvoyé suite à l'appel ayant permis de se connecter à la solution |
Paramètres | Une requête au format JSON spécifiant les rubriques et les critères de recherche. Paramètres facultatifs indiquant les requêtes à ignorer, l'ordre de tri, l'enregistrement de départ (décalage), le nombre d'enregistrements (plage) et les tables externes pour limiter le nombre d'enregistrements liés renvoyés. Par exemple : {
"query":[
{"Group": "=Chirurgien", "Région de travail" : "Ile-de-France"},
{"Group": "=Chirurgien", "Ville de travail" : "La Défense", "omit" : "true"}],
"sort":[
{"fieldName": "Région de travail","sortOrder": "ascend"},
{"fieldName": "Prénom", "sortOrder": "ascend"} ]
}
Exemple avec décalage, plage et tables externes : {
"query":[
{"Group": "=Chirurgien", "Région de travail" : "Ile-de-France"},
{"Group": "=Chirurgien", "Ville de travail" : "La Défense", "omit" : "true"}],
"portal": ["Table1","Table2"],
"range": "10",
"offset": "1",
"offset.Portal1": "1",
"range.Portal1": "5"
} |
Réponse | Un code d'erreur de 0 et la représentation JSON du jeu trouvé. Par exemple : {
"errorCode": "0",
"data": [enregistrement1, enregistrement2, ...]
}
Consultez la section Codes d'erreur. |
Remarques
- Dans une solution comportant de nombreux enregistrements liés, l'interrogation et le tri des enregistrements externes peuvent demander beaucoup de temps. Pour limiter le nombre d'enregistrements et de rangées à afficher dans un ensemble lié, indiquez les paramètres de décalage et de plage.
- Les rubriques de type Global ne sont pas autorisées dans les critères de recherche. Si vous en indiquez, vous recevez un message d'erreur. Au lieu de cela, indiquez la valeur de la rubrique de type Global avant la recherche. Consultez la section Appel définissant des valeurs de rubrique de type Global.
Appel définissant des valeurs de rubrique de type Global
Pour définir les valeurs des rubriques de type Global, utilisez une méthode HTTP PUT avec l'URL global
indiquant le nom de la solution et le modèle.
Méthode HTTP | PUT |
---|---|
URL | /fmi/rest/api/global/solution/modèle/ solution est le nom de la solution hébergée |
En-tête HTTP | FM-Data-token correspond au jeton d'accès renvoyé suite à l'appel ayant permis de se connecter à la solution |
Paramètres | Un objet JSON avec paires rubrique/valeur indiquant les rubriques de type Global à définir. Par exemple : { "globalFields":
{
"gCompany":"FileMaker",
"gCode":"95054"
}
} |
Réponse | Un code d'erreur de 0. Par exemple : {
"errorCode": "0"
}
Consultez la section Codes d'erreur. |
Codes d'erreur
Quand une erreur se produit, FileMaker Data API renvoie habituellement un code d'état de niveau HTTP 400 avec des informations supplémentaires dans un objet JSON.
Code d'état HTTP | Catégorie HTTP | Format d'erreur JSON | Description |
---|---|---|---|
400 | Requête incorrecte | {
"errorMessage": "détail erreur"
} |
Survient lorsque le serveur ne peut pas traiter la requête en raison d'une erreur du client. |
401 | Non autorisé | {
"errorMessage": "Non autorisé"
} |
Survient lorsque le client n'est pas autorisé à accéder à l'API. Si cette erreur survient alors que vous tentez de vous connecter à une solution hébergée, vous rencontrez un problème avec le compte utilisateur ou le mot de passe indiqué. Si cette erreur survient avec d'autres appels, le jeton d'accès n'est pas indiqué ou il n'est pas valide. |
404 | Introuvable | {
"errorMessage": "Introuvable"
} |
Survient si l'appel utilise une URL ayant un schéma non valide. Recherchez les erreurs de syntaxe dans l'URL. |
415 | Type de média non pris en charge | {
"errorMessage": "Type de média non pris en charge"
} |
Survient si l'en-tête « Content/Type: application/json » n'est pas spécifié ou si un type de contenu différent a été indiqué au lieu du type « application/json ». |
477 | Erreur de service FileMaker | {
"errorMessage": "message d'erreur FileMaker",
"errorCode": "message d'erreur FileMaker"
} |
Inclut les messages d'erreur et les codes d'erreur FileMaker. Consultez la section Codes d'erreur FileMaker de l'Aide FileMaker Pro. |
Remarques
- Si le moteur FileMaker Data API n'est pas en cours d'exécution ou est inaccessible, le code d'état 0 (zéro) peut être renvoyé sans message d'erreur.
- Pour plus d'informations sur les codes d'état HTTP supplémentaires renvoyés, consultez le site www.w3.org.
Héberger, tester et surveiller des solutions FileMaker Data API
Héberger une solution FileMaker Data API
- Passez en revue toutes les étapes décrites dans la section Préparer les bases de données pour un accès via FileMaker Data API.
- Assurez-vous que l'accès via FileMaker Data API a été activé et correctement paramétré dans l'Admin Console de FileMaker Server. Consultez l'Aide FileMaker Server.
- Vérifiez que le serveur Web, le moteur de publication Web et le moteur FileMaker Data API sont en cours d'exécution.
-
Cryptez les communications.
FileMaker Data API impose à vos applications d'API REST d'utiliser une connexion HTTPS. Les connexions HTTPS utilisent le cryptage SSL (Secure Sockets Layer) pour les communications.
FileMaker Server fournit un certificat SSL standard signé par FileMaker, Inc. qui ne vérifie pas le nom du serveur. Le certificat par défaut de FileMaker est uniquement destiné à des fins de tests. Un certificat SSL personnalisé est requis à des fins de production. Consultez le Guide d'installation et de configuration de FileMaker Server.
Le langage ou la technologie que vous utilisez pour appeler FileMaker Data API doit prendre en charge le protocole TLS (Transport Layer Security) v1.2 pour communiquer avec le serveur Web.
Tester une solution FileMaker Data API
Avant de mettre votre solution FileMaker Data API en production, vérifiez qu'elle fonctionne comme prévu.
- Testez les fonctions telles que la recherche, l'ajout et la suppression d'enregistrements avec différents jeux de comptes et de privilèges.
- Vérifiez que les jeux de privilèges fonctionnent comme prévu en procédant à des tests avec différents comptes. Faites en sorte que des utilisateurs non autorisés ne puissent pas accéder à vos données ni les modifier.
- Testez le comportement de votre solution et vérifiez qu'il est identique d'un système d'exploitation à un autre.
Surveiller les solutions FileMaker Data API
L'administrateur serveur peut utiliser l'Admin Console pour démarrer ou arrêter le moteur FileMaker Data API, modifier les paramètres FileMaker Data API, surveiller les clients FileMaker Data API, suivre l'utilisation des appels FileMaker Data API et consulter le fichier journal de FileMaker Data API.
Pour | Utilisez |
---|---|
Démarrer ou arrêter le moteur FileMaker Data API | Zone d'état de l'Admin Console ou commande de l'interface de ligne de commande. Consultez les sections Démarrage ou arrêt des composants FileMaker Server et Utilisation de l'interface de ligne de commande de l'Aide FileMaker Server. |
Modifier les paramètres FileMaker Data API | Onglet Publication Web > FileMaker Data API de l'Admin Console. Dans cet onglet, activez l'utilisation de FileMaker Data API et la consignation des appels FileMaker Data API, puis définissez la taille maximale du fichier journal et le niveau de consignation des messages écrits dans ce fichier. Consultez la section Paramètres de FileMaker Data API de l'Aide FileMaker Server. |
Surveiller les clients FileMaker Data API | Onglet Activité > Clients de l'Admin Console. Cet onglet présente des informations sur le client et les solutions auxquelles vous accédez. Consultez la section Administration des clients de l'Aide FileMaker Server. Depuis cet onglet, vous pouvez déconnecter les clients FileMaker Data API, mais vous ne pouvez pas leur envoyer de messages. Si les clients FileMaker Data API sont connectés à une solution, des données statistiques sur les clients sont proposées dans l'onglet Statistiques > Clients de l'Admin Console. Consultez la section Affichage des statistiques de client de l'Aide FileMaker Server. |
Suivre l'utilisation des appels FileMaker Data API | Onglet Publication Web > FileMaker Data API de l'Admin Console. Cet onglet indique le nombre d'appels FileMaker Data API autorisés par votre licence FileMaker Server, le nombre d'appels utilisés pendant le mois en cours et le nombre d'appels utilisés au cours du mois précédent. Si vous approchez de la limite fixée, vous pouvez également acheter des appels à partir de cet onglet. Consultez la section Paramètres de FileMaker Data API de l'Aide FileMaker Server. |
Afficher le fichier journal FileMaker Data API | Onglet Log Viewer de l'Admin Console. Les composants FileMaker Data API génèrent les données des fichiers journaux relatives aux clients qui accèdent aux solutions hébergées via FileMaker Data API. Consultez la section Fichier journal de FileMaker Data API de l'Aide FileMaker Server. |
Intégration de FileMaker Data API à Tableau
A propos de l'intégration à Tableau
FileMaker Server intègre le Connecteur de données Web Tableau, un exemple de mise en œuvre qui accepte les appels d'API REST au format JSON. Utilisez le Connecteur de données Web Tableau pour définir une connexion entre FileMaker Server et Tableau Desktop. Cette connexion utilise FileMaker Data API pour importer des données depuis des solutions FileMaker hébergées dans Tableau Desktop.
Conditions requises pour le Connecteur de données Web Tableau
- Tableau Desktop, version 9.1 ou ultérieure pour Windows ou Mac.
- Une base de données FileMaker Pro protégée par mot de passe et contenant les données à importer. La base de données doit être hébergée sur FileMaker Server.
-
Un point de terminaison API REST valide. Pour FileMaker Server, le point de terminaison est un point de connexion HTML qui fournit les informations nécessaires aux services Web. Ce point de terminaison a pour format
https://<nomhôte>/fmi/rest/tableau/fm_connector.html
oùnomhôte
correspond au nom d'hôte complet de FileMaker Server.Par exemple :
https://monserveur.monentreprise.com/fmi/rest/tableau/fm_connector.html
- Un certificat SSL personnalisé valide sur FileMaker Server. Le Connecteur de données Web Tableau n'autorise pas l'importation de données depuis FileMaker Server sans certificat SSL personnalisé valide.
Se préparer à importer des données dans Tableau
Suivez les étapes décrites dans la section Préparer les bases de données pour un accès via FileMaker Data API pour définir le modèle servant à l'importation et pour activer la base de données permettant d'accéder à FileMaker Data API.
Remarque :Pour importer des données dans Tableau, la table doit contenir au moins un enregistrement et des données d'enregistrement.
Les types de rubrique FileMaker suivants sont importés sous forme de types de données Tableau.
Type de rubrique FileMaker | Type de données Tableau |
---|---|
Texte | Chaîne de caractères |
Date | Date |
Heure | Chaîne de caractères |
Horodatage | Date & heure |
Nombre | Nombre (décimal) |
Les types de rubrique FileMaker suivants ne sont pas pris en charge au moment de l'importation dans Tableau :
- rubriques Conteneur
- rubriques de type Statistique. Vous pouvez créer une rubrique de type Statistique dans Tableau d'après les données que vous importez depuis FileMaker.
- rubriques de type Calcul. Vous pouvez créer une rubrique de type Calcul dans Tableau d'après les données que vous importez depuis FileMaker.
- données de graphique
- données provenant de tables externes FileMaker Pro. Pour importer des données depuis des enregistrements liés, créez un modèle FileMaker Pro d'après la table liée ou importez des données dans Tableau depuis des tables FileMaker Pro distinctes, puis créez un lien entre elles dans Tableau.
- valeurs de rubrique dans lesquelles l'affichage des rubriques multivaluées pour Afficher les répétitions intègre des valeurs multiples. Une seule répétition est acceptée.
- valeurs non numériques dans les rubriques de type Nombre. Si Tableau détecte des valeurs non numériques dans des rubriques de type Nombre, les données ne sont pas importées.
N'utilisez pas de mots réservés pour les noms de rubrique dans FileMaker Pro.
Configurer la connexion des données dans Tableau Desktop
- Dans Tableau Desktop, sous Connexion (à gauche de l'écran), choisissez Plus > Connecteur de données Web.
- Saisissez l'URL de votre point de terminaison FileMaker Server
https://<nomhôte>/fmi/rest/tableau/fm_connector.html
où<nomhôte>
est le nom d'hôte complet de FileMaker Server. -
Dans la boîte de dialogue Importer des données d'un fichier FileMaker :
-
Connectez-vous à la solution FileMaker Pro en saisissant les informations suivantes ou en utilisant un fournisseur d'identité OAuth.
- Nom de la base de données source : nom de la solution FileMaker Pro
- Nom du modèle source : nom du modèle FileMaker Pro
- Nom de compte : nom du compte FileMaker Pro détenant le privilège fmrest
- Mot de passe : mot de passe FileMaker Pro
- Sélectionnez Activer l'actualisation incrémentielle pour activer l'actualisation incrémentielle.
-
- Cliquez sur Importer des données FileMaker.
Tableau importe les données. La durée du traitement dépend du nombre d'enregistrements importés, de la charge du serveur et du débit du réseau. Tableau établit une correspondance entre les noms de rubrique et données FileMaker Pro et les dimensions et mesures. Les données de type Chaîne sont habituellement mises en correspondance avec les dimensions et les donnés numériques avec les mesures. Cette mise en correspondance intervient automatiquement au moment de l'importation. Toutefois, vous pouvez la personnaliser.
Remarques
-
Quand vous indiquez le nom du modèle source, vérifiez qu'il est bien unique. Si votre base de données possède deux modèles du même nom, Tableau ne peut pas les distinguer au moment de connecter les données. Tableau affiche un nom seulement qui peut ne pas être le modèle souhaité.
-
Utilisez l'option Activer l'actualisation incrémentielle pour importer uniquement les nouveaux enregistrements.
- Après avoir sélectionné l'option Activer l'actualisation incrémentielle et importé les données FileMaker, cliquez sur l'onglet Feuille dans Tableau pour accéder à la feuille de calcul.
- Choisissez Données > FM: nom_solution / nom_modèle > Extraire > Actualisation incrémentielle.
- Sélectionnez l'onglet Source de données.
- Cliquez sur Mettre à jour pour afficher les nouveaux enregistrements.
- En activant l'actualisation incrémentielle, vous ne créez aucune connexion active et directe entre Tableau et la base de données FileMaker hébergée. Vous devez exécuter l'actualisation incrémentielle manuellement.
- L'actualisation incrémentielle importe uniquement les nouveaux enregistrements. Les enregistrements FileMaker Pro qui ont été modifiés ou supprimés ne sont pas mis à jour. Pour obtenir les données modifiées ou pour retirer les enregistrements supprimés, vous devez créer un nouveau classeur dans Tableau et réimporter les données.
- L'actualisation incrémentielle crée une rubrique appelée -recordId. Toute modification apportée à cette rubrique peut empêcher l'actualisation incrémentielle.
- Dans Tableau, vous pouvez modifier le schéma et les données qui ont été importés. Toutefois, si vous les modifiez dans Tableau, ces modifications ne sont pas transférées au fichier FileMaker Pro.
- Si vous modifiez le schéma dans le fichier FileMaker Pro, vous devez créer un nouveau classeur dans Tableau, puis réimporter les données.
- La base de données Tableau Desktop peut être hébergée sur Tableau Server pour Windows.
- Si vous fermez le classeur Tableau puis que vous le rouvrez, l'importation incrémentielle ne fonctionne plus.
- Une fois les données connectées à Tableau, le Connecteur de données Web pour FileMaker met en cache le compte utilisateur et le mot de passe jusqu'à la fermeture du classeur, tout en tenant compte des points suivants :
- Si la session FileMaker expire pendant que vous êtes connecté à Tableau, le Connecteur de données Web pour FileMaker tente de reconnecter l'utilisateur à FileMaker Server.
- Si la connexion à Tableau expire, le Connecteur de données Web pour FileMaker tente de vous reconnecter à FileMaker Server tant que le classeur Tableau est ouvert.
- Si le classeur est fermé puis rouvert, vous devez saisir à nouveau vos nom de compte et mot de passe pendant l'importation de données initiale.
- La page Source de données de Tableau affiche jusqu'à 1 000 000 (un million) de lignes, même si un nombre plus important d'enregistrements est importé.