Guide FileMaker Cloud 2.18 OData
À propos de l'utilisation d'OData avec les bases de données FileMaker
Présentation
OData (Open Data Protocol) est une implémentation d'API conforme aux normes de l'industrie qui fournit une méthode standard pour interroger et mettre à jour les données, permettant aux clients API REST d'accéder aux données FileMaker® hébergées par FileMaker Cloud®. OData utilisant une architecture REST (Representational State Transfer), elle peut donc être qualifiée d'API REST. OData est similaire à ODBC (Open Database Connectivity) et JDBC (Java Database Connectivity), car ce protocole offre aux applications tierces comme Excel une méthode standard pour accéder aux données FileMaker. Consultez la page Protocole OData 4.0 (anglais).
De plus, OData renvoie des données aux formats JSON (JavaScript Object Notation) et Atom (Atom Syndication Format). JSON est un format texte couramment utilisé avec les API REST, car il est compact et interprétable par l'utilisateur. Atom est un format XML permettant de créer et de mettre à jour des ressources Web. Il est pris en charge par les applications utilisant des données XML au lieu de JSON.
Ce guide part du principe que vous savez :
- utiliser FileMaker Pro Advanced pour créer des bases de données. Vous devez comprendre les bases de la conception des bases de données avec FileMaker Pro Advanced, ainsi que les concepts de rubriques, tables, liens et conteneurs. Consultez l'Aide FileMaker Pro Advanced.
- utiliser FileMaker Cloud pour héberger des bases de données. Vous devez savoir configurer FileMaker Cloud, autoriser l'accès aux bases de données hébergées et les surveiller à l'aide de l'Admin Console de FileMaker Cloud. Consultez la documentation 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.
Étapes générales pour l'utilisation d'OData avec les bases de données FileMaker
- Préparez votre base de données pour un accès via OData avec FileMaker Pro Advanced. Consultez la section Activer l'accès via OData.
- Écrivez du code qui appelle les méthodes OData pour rechercher et modifier des enregistrements, exécuter des scripts FileMaker et modifier le schéma d'une base de données hébergée. Consultez la section Écrire des appels d'API OData.
- Hébergez votre base de données FileMaker par FileMaker Cloud en activant l'accès via OData. Consultez la section Héberger des bases de données pour un accès via OData.
- Testez l'accès via OData pour vérifier qu'il fonctionne correctement. Consultez la section Tester l'accès via OData.
- Surveillez votre base de données hébergée à l'aide de l'Admin Console de FileMaker Cloud. Consultez la section Surveiller l'accès via OData.
Traitement des appels OData
Client API REST
1
6
Serveur Web
2
5
Port d'écoute OData
3
4
Serveur de base de données
- Un client API REST envoie un appel OData (requête HTTPS) au serveur Web sur le port HTTPS (port 443).
- Le serveur Web achemine la requête via le module de serveur Web FileMaker jusqu'au port d'écoute OData.
- Le port d'écoute OData convertit la requête HTTPS (URL avec données JSON ou Atom) en un format que le composant du serveur de base de données peut comprendre, puis demande des données de la base de données hébergée par le serveur de base de données.
- Le serveur de base de données envoie les données FileMaker demandées au port d'écoute OData.
- Le port d'écoute OData convertit les données FileMaker en une réponse HTTPS (URL avec données JSON ou Atom) à 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.
Comparaison des solutions API
La plateforme FileMaker fournit deux API REST pour accéder aux données des bases de données FileMaker hébergées. Déterminez la solution adaptée à vos objectifs et à votre environnement d'entreprise.
| Solution | Utilisation | Avantages |
|---|---|---|
| Norme OData |
|
|
| FileMaker Data API |
|
|
Terminologie OData et FileMaker
Ce guide utilise la terminologie FileMaker dans la mesure du possible. Pour plus de clarté, un terme OData est parfois utilisé avec un terme FileMaker. Le tableau ci-dessous indique les termes et définitions équivalents.
Pour plus d'informations sur la terminologie FileMaker, consultez le Centre de documentation produit.
| Terme OData | Terme FileMaker |
|---|---|
| entity | enregistrement |
| entity set | table |
| entity container | groupe de rubriques qui n'est pas nécessairement un enregistrement (par exemple, un nom et une URL de base de données) |
| collection of entity containers | liste d'un groupe de rubriques (par exemple, une liste de noms de bases de données) |
| property | rubrique |
| path segment | valeur comprise entre deux caractères slash (dans une URL) |
| raw value | une valeur binaire sous forme de chaîne d'octets plutôt qu'une valeur Atom ou JSON structurée interprétable par l'utilisateur |
Préparer les bases de données pour un accès via OData
Activer l'accès via OData
Pour autoriser l'accès via OData aux données FileMaker, vous devez activer le privilège étendu fmodata dans FileMaker Pro Advanced. Si vous n'activez pas le privilège étendu fmodata, les applications OData ne pourront pas utiliser OData pour accéder à la base de données, même si celle-ci est hébergée.
Remarque :pour des raisons de sécurité, activez uniquement le privilège étendu fmodata dans les jeux de privilèges des comptes auxquels vous souhaitez autoriser l'accès via OData.
Consultez la section « Modification de privilèges étendus pour un jeu de privilèges » de l'Aide FileMaker Pro Advanced.
Conformité à la norme OData et prise en charge des fonctions OData
Fonctions OData prises en charge
OData utilise des conventions compatibles avec les normes existantes (REST, JSON, XML et Atom) pour fournir une représentation des fonctionnalités courantes. La plateforme FileMaker prend en charge OData à un niveau de conformité intermédiaire, avec quelques exceptions. Consultez les spécifications et le guide de référence sur la page Protocole OData 4.0 (anglais).
Vous pouvez utiliser l'API OData pour :
- récupérer des informations sur FileMaker Cloud ; par exemple, des noms de bases de données hébergées, des noms de tables et des métadonnées de base de données. Consultez la section Structure et métadonnées de base de données.
- créer, modifier ou supprimer un enregistrement. Consultez la section Modifier des données.
- rechercher un enregistrement ou tous les enregistrements. Consultez la section Demander des données.
- spécifier des critères pour rechercher un jeu d'enregistrements. Consultez la section Options de requête.
- exécuter des scripts FileMaker. Consultez la section Exécuter des scripts.
- uploader des données de conteneur. Consultez la section Utiliser des données de conteneur.
Fonctions OData non prises en charge
Ces fonctions OData ne sont pas prises en charge à un niveau de conformité intermédiaire :
- option de requête
$search $expand(prise en charge uniquement dans le cadre d'une opération$crossjoin)- opérateurs
lambdaanyetall $filtersur les entités développéesfonctions et opérateurs canoniques intégrés :
- indexof()
- fractionalseconds()
- isof()
- geo.distance()
- geo.length()
- geo.intersects()
De plus, les actions suivantes ne sont pas prises en charge :
- l'accès aux données de sources de données ODBC externes.
- l'utilisation des plug-ins FileMaker.
- l'activation des déclencheurs de script par l'utilisateur ; OData active les déclencheurs de script uniquement en exécutant un script FileMaker.
- l'accès au système de fichiers de la machine serveur ; par exemple, OData ne prend pas en charge la fonction Obtenir ( CheminTemporaire ).
Informations de référence sur OData
Plusieurs références API fournissent des spécifications pour OData :
Remarques concernant le format des URL et des données
- La longueur d'URL maximale dépend du système d'exploitation, du serveur Web et du navigateur Web. Pour une utilisation optimale sur toutes les plateformes, limitez cette longueur à 2 000 caractères.
- Les chaînes de caractères des URL doivent utiliser le codage URL également appelé encodage-pourcent, ce qui est normal pour les requêtes HTTP.
- Les valeurs de données de chaîne de caractères définies dans les paramètres, dans le corps de la requête, doivent utiliser le codage UTF-8.
Scripts FileMaker et OData
Un script FileMaker est un jeu nommé d'actions de script automatisant les tâches fréquemment effectuées et pouvant combiner plusieurs tâches. Lorsque les scripts FileMaker sont utilisés avec OData, ils permettent aux services Web d'exécuter plus de tâches ou une série de tâches. Consultez la section Exécuter des scripts.
Remarques
- Utilisez les comptes et privilèges pour restreindre l'ensemble des scripts qu'un service Web exécute. Vérifiez que les scripts contiennent exclusivement des actions de script compatibles avec le Web et donnez uniquement accès aux scripts pouvant être utilisés depuis un service Web.
- Pensez aux effets des scripts qui exécutent une combinaison d'actions contrôlées par des privilèges d'accès. Par exemple, si un script comporte une action visant à supprimer des enregistrements et qu'un service Web ne se connecte pas avec un compte autorisant la suppression d'enregistrements, le script n'exécutera pas l'action Supprimer des enregistrements. L'exécution du script peut néanmoins se poursuivre et mener à des résultats inattendus.
- Dans l'Espace de travail de script, accordez le jeu de privilèges Accès intégral à un script afin d'effectuer des actions auxquelles des utilisateurs n'ont normalement pas accès. Par exemple, vous pouvez empêcher les utilisateurs de supprimer des enregistrements avec leurs comptes et privilèges, mais les autoriser à exécuter un script visant à supprimer certains enregistrements dans les conditions définies dans le script.
- Tout script modifiant des données doit inclure l'action de script Valider enreg./requêtes, car toutes les modifications apportées aux données ne sont pas accessibles tant que les données ne sont pas enregistrées sur le serveur. Ceci inclut des actions de script telles que Couper, Copier ou Coller. Convertissez les actions uniques en scripts pour inclure l'action Valider enreg./requêtes. Lors de la conception de scripts exécutés depuis un service Web, incorporez l'action de script Valider enreg./requêtes en fin de script pour garantir l'enregistrement de toutes les modifications.
- Ouvrez les scripts susceptibles d'être exécutés par les utilisateurs Web et vérifiez qu'ils s'exécutent correctement lorsque la base de données est hébergée pour un accès via OData. Vérifiez que le script utilise uniquement les actions de script prises en charge par OData, comme décrit ci-dessus.
Écrire des appels d'API OData
Composants des appels OData
Les appels OData utilisent les composants ci-après.
| Composant | Description |
|---|---|
| Méthode HTTP | OData utilise les méthodes HTTP suivantes :
|
| En-têtes HTTP | OData utilise les en-têtes suivants :
|
| URL | https://hôte/fmi/odata/version/nom-base hôte : nom d'hôte FileMaker Cloud. Exemple : |
| Exemple de données de paramètres au format JSON et Atom | Pour les méthodes POST et PATCH uniquement. |
Créer une connexion authentifiée à l'hôte FileMaker
OData exige l'authentification via un compte FileMaker ID.
Pour définir une connexion à l'hôte FileMaker :
- Générez un jeton FileMaker ID pour l'authentification externe. Consultez l'Aide FileMaker Customer Console.
- Incluez le jeton FileMaker ID de l'étape 1 dans l'en-tête Authorization pour tous les appels OData.
Par exemple, utilisez l'URL et l'en-tête suivants :
- URL :
https://hôte/fmi/odata/v4/nom-base/$metadatahôte : nom d'hôte FileMaker Cloud.
nom-base : nom de la base de données FileMaker. - En-tête :
Authorization FMID FileMaker_ID_Token
- URL :
Structure et métadonnées de base de données
Les informations concernant les bases de données et leur structure sont disponibles en utilisant les méthodes HTTP GET.
Obtenir des noms de bases de données
Pour renvoyer une liste de noms de bases de données, utilisez la méthode GET sans spécifier le nom d'une base de données dans l'URL.
| Composant | Description |
|---|---|
| Méthode HTTP | GET |
| URL | https://hôte/fmi/odata/version hôte : nom d'hôte FileMaker Cloud. Exemple : |
Informations FileMaker
- OData renvoie une liste de noms de bases de données et leurs URL de point de terminaison correspondantes.
Obtenir une liste de tables
Pour récupérer une liste de tables d'une base de données, utilisez la méthode HTTP GET et ajoutez le nom de la base de données dans l'URL.
| Composant | Description |
|---|---|
| Méthode HTTP | GET |
| URL | https://hôte/fmi/odata/version/nom-base hôte : nom d'hôte FileMaker Cloud. Exemple : |
Obtenir des métadonnées
Pour récupérer les informations de métadonnées d'une table, utilisez la méthode HTTP GET.
Utilisez le mot-clé $metadata avec la racine du service de base de données pour demander une liste complète des métadonnées de la base de données.
| Composant | Description |
|---|---|
| Méthode HTTP | GET |
| URL | https://hôte/fmi/odata/version/nom-base/$metadata hôte : nom d'hôte FileMaker Cloud. Exemple : |
Informations FileMaker
Pour fournir des informations concernant les tables FileMaker de la base de données, des annotations (informations non définies dans la norme OData) sont ajoutées aux résultats des métadonnées, telles que le numéro de version du produit FileMaker.
Les annotations ci-dessous ont une valeur booléenne « true » si elles sont présentes. Sinon, la valeur est « false ».
- AutoGenerated : indique si la valeur de rubrique est automatiquement générée par FileMaker Pro Advanced.
- Index : indique si les valeurs de rubrique sont indexées.
- VersionID : indique si la rubrique est une rubrique Horodatage et une nouvelle valeur d'horodatage est générée lorsque l'enregistrement est modifié.
- Global : indique si la rubrique contient une valeur globale.
- Calculation : indique si la rubrique est de type Calcul.
- Summary : indique si la rubrique est de type Statistique.
Autres annotations :
- MaxRepetitions : une valeur entière indiquant le nombre maximum de répétitions définies pour une rubrique multivaluée. Si cette annotation n'est pas présente, la rubrique n'est pas une rubrique multivaluée.
- ExternalSecurePath : une chaîne de caractères indiquant le chemin d'accès relatif spécifié pour le stockage sécurisé d'une rubrique Conteneur.
- BestRowID : contient toujours ROWID, une rubrique système qui est explicitement incluse dans un jeu de résultats en spécifiant
$select=ROWID. Cette valeur est identique à celle renvoyée par la fonction Obtenir ( IDEnreg ) pour un enregistrement. - RowVersion : contient toujours ROWMODID, une rubrique système qui est explicitement incluse dans un jeu de résultats en spécifiant
$select=ROWMODID. Cette valeur est identique à celle renvoyée par la fonction Obtenir ( NombreModificationsEnreg ) pour un enregistrement.
Important : OData exige que chaque table définisse une clé primaire. OData utilise des rubriques qui ne sont pas vides et exigent une valeur unique comme clé primaire. Par conséquent, si de telles rubriques ne sont pas définies pour vos tables, la rubrique système ROWID est utilisée comme clé primaire. La rubrique système ROWID contient la même valeur que celle renvoyée par la fonction Obtenir ( IDEnreg ) pour l'enregistrement.
Modifier des données
OData prend en charge les opérations Créer, Mettre à jour et Supprimer pour les enregistrements, selon les privilèges d'accès attribués à un compte.
Créer un enregistrement
Pour créer un enregistrement de table, utilisez la méthode POST. Le corps de POST doit contenir les données d'un enregistrement unique au format JSON.
| Composant | Description |
|---|---|
| Méthode HTTP | POST |
| URL | https://hôte/fmi/odata/version/nom-base/nom-table hôte : nom d'hôte FileMaker Cloud. Exemple : |
| Paramètres | Exemple JSON : {Exemple Atom : |
Informations FileMaker
- Les valeurs des répétitions individuelles d'une rubrique multivaluée sont fournies en spécifiant le nombre de répétitions (par exemple,
Nom[4]). - Si vous créez un enregistrement contenant des objets de données vides au format JSON, au moins une rubrique doit autoriser les valeurs nulles.
- Les rubriques FileMaker de type Global sont en lecture seule et ne peuvent pas être mises à jour avec OData.
Supprimer un enregistrement
Pour supprimer un enregistrement, utilisez la méthode HTTP DELETE en spécifiant le nom de la table et la valeur de clé primaire de l'enregistrement dans l'URL.
| Composant | Description |
|---|---|
| Méthode HTTP | DELETE |
| URL | https://hôte/fmi/odata/version/nom-base/nom-table (valeur-clé-primaire) hôte : nom d'hôte FileMaker Cloud. Exemple : |
Informations FileMaker
- Vous pouvez supprimer plusieurs enregistrements en spécifiant le critère
$filter.
Mettre à jour un enregistrement
Pour mettre à jour un enregistrement, utilisez la méthode HTTP PATCH avec l'enregistrement que vous souhaitez mettre à jour dans l'URL.
| Composant | Description |
|---|---|
| Méthode HTTP | PATCH |
| URL | https://hôte/fmi/odata/version/nom-base/nom-table (valeur-clé-primaire) hôte : nom d'hôte FileMaker Cloud. Exemple : |
| Paramètres | Exemple JSON : { |
Informations FileMaker
- Les valeurs de conteneur sont mises à jour en fournissant une valeur codée au format Base64, comme décrit dans la section Mettre à jour un enregistrement contenant une rubrique Conteneur PDF ou image, ou les données binaires, comme décrit dans la section Mettre à jour un enregistrement contenant une rubrique Conteneur PDF ou image avec des données binaires.
- Les valeurs des répétitions individuelles de rubriques multivaluées sont fournies en spécifiant l'index de répétitions entre crochets (par exemple,
Nom[4]). La spécification d'une répétition de rubrique Conteneur n'est pas prise en charge lors de la mise à jour d'un enregistrement. - Vous pouvez mettre à jour plusieurs enregistrements en spécifiant le critère
$filter.
Utiliser des données de conteneur
Vous pouvez utiliser une méthode HTTP POST ou PATCH pour insérer des images ou des fichiers PDF dans des rubriques Conteneur. Les données des rubriques Conteneur sont intégrées dans la rubrique, stockées sous forme de référence de fichier ou en externe.
Créer un enregistrement contenant une rubrique Conteneur PDF ou image
Pour créer un enregistrement de table contenant une ou plusieurs rubriques, définissez les données de ces dernières au format Base64. Seuls les types de fichiers GIF, PNG, JPEG, TIFF et PDF sont pris en charge. Le corps de POST doit contenir la représentation d'un enregistrement unique valide.
| Composant | Description |
|---|---|
| Méthode HTTP | POST |
| URL | https://hôte/fmi/odata/version/nom-base/nom-table hôte : nom d'hôte FileMaker Cloud. Exemple : |
| Paramètres | Exemple JSON : { |
Informations FileMaker
- Le type de fichier multimédia d'une valeur de conteneur codée au format Base64 est déterminé en comparant les premiers octets des données aux valeurs attendues des types de fichiers multimédia pris en charge.
Mettre à jour un enregistrement contenant une rubrique Conteneur PDF ou image avec des données binaires
La requête dans cette table met à jour la valeur d'une rubrique Photo d'un enregistrement Contacts en utilisant la méthode PATCH avec des octets GIF binaires (non structurés) dans le corps de la requête. L'en-tête Content-Type doit spécifier le type de données contenues dans le corps (image/gif, image/png, image/jpeg, image/tiff, or application/pdf).
| Composant | Description |
|---|---|
| Méthode HTTP | PATCH |
| URL | https://hôte/fmi/odata/version/nom-base/nom-table (valeur-clé-primaire)/nom-rubrique hôte : nom d'hôte FileMaker Cloud. Exemple : |
| Paramètres | "474946383961090009008001007F7F7FFFFFFF21F90401000001002C00000000090009 |
Mettre à jour un enregistrement contenant une rubrique Conteneur PDF ou image
Pour mettre à jour la valeur d'une rubrique de conteneur d'un enregistrement, utilisez la méthode HTTP PATCH avec la valeur codée au format Base64.
| Composant | Description |
|---|---|
| Méthode HTTP | PATCH |
| URL | https://hôte/fmi/odata/version/nom-base/nom-table (valeur-clé-primaire) hôte : nom d'hôte FileMaker Cloud. Exemple : |
| Paramètres | Exemple JSON : { |
Demander des données
Demander les enregistrements d'une table
Pour renvoyer une collection d'enregistrements de la base de données FileMaker, utilisez la méthode HTTP GET et incluez le nom de la table dans l'URL.
| Composant | Description |
|---|---|
| Méthode HTTP | GET |
| URL | https://hôte/fmi/odata/version/nom-base/nom-table hôte : nom d'hôte FileMaker Cloud. Exemple : |
Informations FileMaker
- Les rubriques Conteneur ne sont pas incluses dans le résultat de la réponse lorsque vous obtenez tous les enregistrements ou un seul. Pour plus d'informations sur la requête de valeurs de rubrique Conteneur, consultez la section Demander une valeur de rubrique individuelle.
Demander un enregistrement individuel
Pour demander un enregistrement individuel d'une table de base de données, spécifiez le nom de la base de données et le nom de la table, ainsi que la valeur de clé primaire de l'enregistrement.
| Composant | Description |
|---|---|
| Méthode HTTP | GET |
| URL | https://hôte/fmi/odata/version/nom-base/nom-table (valeur-clé-primaire) hôte : nom d'hôte FileMaker Cloud. Exemple : |
Informations FileMaker
- La valeur de clé primaire spécifiée dans l'URL est la rubrique désignée comme clé primaire ou la rubrique système ROWID si aucune clé primaire n'a été indiquée. Consultez la section Obtenir des métadonnées. Pour les rubriques multivaluées, la valeur de la première répétition est incluse. Pour obtenir des répétitions individuelles, consultez la section Demander une valeur de rubrique individuelle.
Demander une valeur de rubrique individuelle
Pour demander une valeur de rubrique individuelle, spécifiez le nom de la table, la valeur de clé primaire de l'enregistrement et le nom de la rubrique.
| Composant | Description |
|---|---|
| Méthode HTTP | GET |
| URL | https://hôte/fmi/odata/version/nom-base/nom-table (valeur-clé-primaire)/nom-rubrique hôte : nom d'hôte FileMaker Cloud. Exemple : |
Informations FileMaker
- Dans une URL, lors de la requête d'une répétition individuelle, l'utilisation de crochets ([ ]) pour spécifier l'index de répétition n'est pas prise en charge.
- Si la rubrique répétée est une rubrique Conteneur, seule la première répétition est renvoyée. Sinon, toutes les répétitions sont renvoyées.
Demandez la valeur binaire d'une rubrique individuelle
Pour demande une rubrique individuelle stockée en tant que valeur binaire, utilisez l'option de requête $value.
Le format par défaut de la valeur binaire de la rubrique FileMaker est « text/plain ». Pour les rubriques Conteneur, le format par défaut dépend du type de rubrique Conteneur et inclut image/gif, image/png, image/jpeg, image/tiff, application/pdf ou application/octet-stream.
| Composant | Description |
|---|---|
| Méthode HTTP | GET |
| URL | https://hôte/fmi/odata/version/nom-base/nom-table (valeur-clé-primaire)/nom-rubrique/$value hôte : nom d'hôte FileMaker Cloud. Exemple : La requête ci-dessus renvoie la valeur binaire de la rubrique Nom de l'enregistrement Contacts. |
Informations FileMaker
- Lors de la requête de la valeur binaire (brute) d'une rubrique répétée, seule la valeur binaire (brute) de la première répétition est renvoyée.
Naviguer dans les tables liées
Vous pouvez naviguer dans les relations entre les tables FileMaker sans spécifier les rubriques correspondantes pour chaque relation. L'ensemble des opérations et des résultats est associé à la dernière table dans l'URL.
| Composant | Description |
|---|---|
| Méthode HTTP | GET |
| URL | https://hôte/fmi/odata/version/nom-base/nom-table (valeur-clé-primaire)/table-liée hôte : nom d'hôte FileMaker Cloud. Exemple : La requête ci-dessus renvoie tous les produits achetés par un client avec l'ID donné. |
Informations FileMaker
- Lors de l'utilisation de l'option de requête
$filter, les noms de rubriques sont désambiguïsés en faisant précéder le nom de la rubrique du nom de la table dans l'expression (par exemple,$filter=Purchase/ID eq 7).
Demander une jointure croisée de tables non liées
Pour demander une jointure croisée des tables non liées, utilisez le mot-clé $crossjoin et indiquez les tables que vous souhaitez joindre. Lors de l'utilisation de l'option de requête $filter, spécifiez chaque rubrique utilisée pour joindre les deux tables.
Utilisez les options de requête $expand et $select pour vous assurer que des rubriques de données sont renvoyées plutôt qu'une liste d'ID d'enregistrement (comportement par défaut). Consultez la section « Addressing the cross join of entity sets » de la page Conventions d'URL OData 4.0 (anglais).
Remarque : une jointure croisée est le seul contexte dans lequel le mot-clé $expand est pris en charge.
| Composant | Description |
|---|---|
| Méthode HTTP | GET |
| URL | https://hôte/fmi/odata/version/nom-base/$crossjoin (table 1, table 2)?$filter= hôte : nom d'hôte FileMaker Cloud. Exemple : |
Options de requête
OData prend en charge différentes options de requête pour interroger les données.
Option de requête $filter
Utilisez l'option de requête $filter pour filtrer les enregistrements. L'expression spécifiée avec l'option de requête $filter est évaluée pour chaque enregistrement de la collection, et seuls les éléments que l'expression évalue « true » sont inclus dans la réponse.
OData prend en charge un ensemble de fonctions et d'opérateurs intégrés qui sont utilisés dans les opérations $filter. Pour plus d'informations sur les fonctions et opérateurs intégrés disponibles, consultez la page Protocole OData 4.0 (anglais).
| Composant | Description |
|---|---|
| Méthode HTTP | GET |
| URL | https://hôte/fmi/odata/version/nom-base/nom-table?$filter=(expression) hôte : nom d'hôte FileMaker Cloud. Exemple : La requête ci-dessus utilise la méthode GET et l'option de requête système |
Informations FileMaker
Les fonctions intégrées suivantes ne sont pas prises en charge :
- indexof()
- isof()
- geo.distance()
- geo.length()
- geo.intersects()
- fractionalseconds()
- Les formats de date, d'heure et d'horodatage sont conformes à la norme ISO 8601. Les décalages horaires sont relatifs au fuseau horaire du serveur.
- Mettez les noms de rubriques contenant des caractères spéciaux, tels que des espaces ou des traits de soulignement, entre guillemets doubles.
Option de requête $orderby
Utilisez l'option de requête $orderby pour demander des enregistrements par ordre croissant ou décroissant. Si vous ne spécifiez aucun ordre, l'ordre par défaut est croissant.
| Composant | Description |
|---|---|
| Méthode HTTP | GET |
| URL | https://hôte/fmi/odata/version/nom-base/nom-table?$orderby=nom-rubrique {asc/desc} hôte : nom d'hôte FileMaker Cloud. Exemple : La requête ci-dessus trie les enregistrements Contacts par ordre croissant selon la rubrique Société. |
Informations FileMaker
- Mettez les noms de rubriques contenant des caractères spéciaux, tels que des espaces ou des traits de soulignement, entre guillemets doubles.
- L'option de requête
$orderbyne prend pas en charge les fonctions OData intégrées.
Options de requête $top et $skip
Utilisez les options de requête $top et $skip pour parcourir un jeu de résultats plus volumineux. Vous pouvez utiliser ces options de requête seules ou ensemble, selon les enregistrements que vous souhaitez dans votre réponse.
| Composant | Description |
|---|---|
| Méthode HTTP | GET |
| URL | https://hôte/fmi/odata/version/nom-base/nom-table{?$top/?$skip}=nombre hôte : nom d'hôte FileMaker Cloud. Options de requête {?$top/?$skip} : l'option de requête Exemple :
|
Option de requête $count
Utilisez l'option de requête $count (valeur définie sur « true ») pour demander le nombre d'enregistrements correspondants renvoyés avec les enregistrements dans la réponse. L'option de requête $count ignore les options de requête $top ou $skip et renvoie le nombre total de résultats parmi tous les enregistrements, y compris les résultats correspondant au critère $filter si cela est spécifié.
| Composant | Description |
|---|---|
| Méthode HTTP | GET |
| URL | https://hôte/fmi/odata/version/nom-base/nom-table?$count=true hôte : nom d'hôte FileMaker Cloud. Exemple : |
Option de requête $select
Utilisez l'option de requête $select pour demander un jeu limité de rubriques de chaque table. Par défaut, toutes les rubriques sont renvoyées excepté les rubriques Conteneur.
| Composant | Description |
|---|---|
| Méthode HTTP | GET |
| URL | https://hôte/fmi/odata/version/nom-base/nom-table?$select=rubrique 1, rubrique 2 hôte : nom d'hôte FileMaker Cloud. Exemple : La requête ci-dessus renvoie les données Société et SiteWeb pour tous les enregistrements de la table Contacts. |
Informations FileMaker
- Les rubriques système ROWID et ROWMODID sont incluses dans le jeu de résultats en les spécifiant avec l'option de requête
$select. Par exemple :$select=ROWID, ROWMODID. - La valeur de la rubrique ROWID est équivalente à celle renvoyée par la fonction Obtenir ( IDEnreg ) et la valeur de la rubrique ROWMODID est équivalente à celle renvoyée par la fonction Obtenir ( NombreModificationsEnreg ).
Modifier le schéma
OData prend en charge les opérations Créer et Supprimer pour la création et la suppression de tables et d'index, selon les privilèges d'accès définis pour un compte.
Créer une table
Pour créer une nouvelle table, utilisez la méthode HTTP POST. Le corps de POST doit contenir la représentation d'une table valide unique, incluant un identifiant qui est le nom de la table.
| Composant | Description |
|---|---|
| Méthode HTTP | POST |
| URL | https://hôte/fmi/odata/version/nom-base/FileMaker_Tables hôte : nom d'hôte FileMaker Cloud. Exemple : |
| Paramètres | Exemple JSON : { "tableName": "Société", "fields": [ { "name": "ID de société", "type": "int", "primary": true }, { "name": "ID d'utilisateur", "type": "varchar(20)", "unique": true, "default": "CURRENT_USER" }, { "name": "Nom de la société", "type": "varchar(100)", "nullable": false }, { "name": "Remarques", "type": "varchar(2000)", "global": true }, { "name": "Contrat signé", "type": "blob", "externalSecurePath": "Fichiers/GestionDeContact/" } ] } Exemple Atom : <TableDefinition tableName="Société"> <FieldDefinition name="ID de société" type="int" primary="true"/> <FieldDefinition name="ID d'utilisateur" type="varchar(20)" unique="true" default="CURRENT_USER"/> <FieldDefinition name="Nom de la société" type="varchar(100)" nullable="false"/> <FieldDefinition name="Remarques" type="varchar(2000) global="true"/> </TableDefinition> |
Informations FileMaker
- FileMaker_Tables est une table système utilisée pour la création, la modification et la suppression de tables. Le paramètre
typeest l'un des suivants : NUMERIC, DECIMAL, INT, DATE, TIME, TIMESTAMP, VARCHAR, CHARACTER VARYING, BLOB, VARBINARY, LONGVARBINARY ou BINARY VARYING. - Les répétitions sont spécifiées entre crochets après le type (par exemple,
"INT[4]"). Vous pouvez spécifier la longueur maximale d'une rubrique Texte entre des parenthèses (par exemple,"VARCHAR(200)"). Les paramètres facultatifs suivants sont utilisés avec le nom de la rubrique et le type de rubrique :
"primary": « true » ou « false » (si la rubrique est une clé primaire ; la valeur par défaut est « false »)."unique": « true » ou « false » (si la rubrique doit avoir une valeur unique ; la valeur par défaut est « false »)."nullable": « true » ou « false » (si la rubrique doit avoir une valeur ; la valeur par défaut est « true »)."global": « true » ou « false » (si la rubrique est de type Global ; la valeur par défaut est « false »)."default": chaîne de caractères contenant un mot-clé approprié pour le type de données ; mots-clés valides : USER, USERNAME, CURRENT_USER, CURRENT_DATE, CURDATE, CURRENT_TIME, CURTIME, CURRENT_TIMESTAMP et CURTIMESTAMP."externalSecurePath"(rubriques Conteneur uniquement) : chaîne de caractères contenant un chemin d'accès relatif pour les fichiers sécurisés dans "externalSecurePath". Excluez la partie "[emplacement base de données]/" du répertoire de la base. Assurez-vous de définir ce paramètre pour chaque base de données dans FileMaker Pro Advanced. Consultez l'Aide FileMaker Pro Advanced.
Ajouter des rubriques à une table
Pour créer une nouvelle rubrique dans une table existante, envoyez une requête PATCH à la table système FileMaker_Tables, suivie du nom de la table dans l'URL. Le corps de PATCH doit contenir une série de rubriques à ajouter à la table.
Si la requête échoue en raison d'une erreur lors de l'ajout d'une rubrique, d'autres rubriques peuvent encore être ajoutées à la table.
| Composant | Description |
|---|---|
| Méthode HTTP | PATCH |
| URL | https://hôte/fmi/odata/version/nom-base/FileMaker_Tables/nom-table hôte : nom d'hôte FileMaker Cloud. Exemple : La requête ci-dessus crée une rubrique Téléphone dans la table Société. |
| Paramètres | Exemple JSON : { "fields": [ { "name": "Téléphone", "type": "varchar(25)" } ] } Exemple Atom : <TableDefinition tableName="Société"> <FieldDefinition name="Téléphone" type="varchar(25)"/> </TableDefinition>
|
Informations FileMaker
- FileMaker_Tables est une table système utilisée pour la création, la modification et la suppression de tables. Pour connaître les options valides, consultez la section Créer une table.
Supprimer une table
Pour supprimer une table et tous ses enregistrements, utilisez la méthode HTTP DELETE et incluez le nom de la table dans l'URL.
| Composant | Description |
|---|---|
| Méthode HTTP | DELETE |
| URL | https://hôte/fmi/odata/version/nom-base/FileMaker_Tables/nom-table hôte : nom d'hôte FileMaker Cloud. Exemple : |
Informations FileMaker
- FileMaker_Tables est une table système utilisée pour la création, la modification et la suppression de tables.
- Cette opération supprime une table et toutes ses données sans demander confirmation. Pour éviter toute perte de données, créez un compte disposant de privilèges d'accès pour la suppression de tables et utilisez-le exclusivement pour cette opération.
Supprimer une rubrique d'une table
Pour supprimer une rubrique d'une table, utilisez la méthode HTTP DELETE et ajoutez le nom de la rubrique après le nom de la table dans l'URL.
| Composant | Description |
|---|---|
| Méthode HTTP | DELETE |
| URL | https://hôte/fmi/odata/version/nom-base/FileMaker_Tables/nom-table/nom-rubrique hôte : nom d'hôte FileMaker Cloud. Exemple : |
Créer un index de rubrique
Pour créer un nouvel index, envoyez une requête POST au nom de la table après la table système FileMaker_Indexes. Le corps de POST doit contenir la représentation d'un index valide unique, incluant un identifiant qui est le nom de la rubrique.
| Composant | Description |
|---|---|
| Méthode HTTP | POST |
| URL | https://hôte/fmi/odata/version/nom-base/FileMaker_Indexes/nom-table hôte : nom d'hôte FileMaker Cloud. Exemple : |
| Paramètres | Exemple JSON : { Exemple Atom : <IndexDefinition indexName="État"/> |
Informations FileMaker
- FileMaker_Indexes est une table système utilisée pour la création et la suppression d'index.
Supprimer un index
Pour supprimer un index, envoyez une requête HTTP DELETE à la table système FileMaker_Indexes, suivie du nom de la table et du nom de la rubrique dans l'URL.
| Composant | Description |
|---|---|
| Méthode HTTP | DELETE |
| URL | https://hôte/fmi/odata/version/nom-base/FileMaker_Indexes/nom-table/nom-rubrique hôte : nom d'hôte FileMaker Cloud. Exemple : |
Informations FileMaker
- FileMaker_Indexes est une table système utilisée pour la création et la suppression d'index de rubrique.
- Pour supprimer un index, l'URL doit d'abord spécifier le nom de la table, suivi du nom de la rubrique.
Exécuter des scripts
Pour exécuter un script, envoyez une requête POST à la table système Script, suivie du nom du script dans l'URL. Le corps de POST doit être vide si le script n'accepte pas un paramètre, ou il doit contenir une rubrique unique nommée scriptParameterValue si un paramètre est transmis au script. La rubrique scriptParameterValue accepte des valeurs de type chaîne de caractères, nombre et objet JSON.
OData ne prend pas en charge les noms de scripts contenant des caractères spéciaux (par exemple, @, &, /) ou des noms de scripts commençant par un nombre. Si le script contient l'action de script Fin de script, son résultat texte est renvoyé dans une rubrique nommée resultParameter.
Le script ScriptBonjour ajoute la valeur du paramètre à la chaîne de caractères « Bonjour » et renvoie le résultat. OData renvoie le résultat dans le corps de la réponse incluant un en-tête Content-Type dont la valeur est « application/json » :
{
"scriptResult":
{
"code": 0,
"resultParameter": "Bonjour le monde"
}
}
Remarque : OData prend en charge uniquement les scripts exécutés sans intervention de l'utilisateur.
Exécuter un script
Pour exécuter un script, utilisez la méthode HTTP POST.
| Composant | Description |
|---|---|
| Méthode HTTP | POST |
| URL | https://hôte/fmi/odata/version/nom-base/Script.nom-script hôte : nom d'hôte FileMaker Cloud. Exemple : le monde. |
| Paramètres | Exemple JSON : |
Informations FileMaker
- Pour pouvoir être conformes au concept OData d'une action, tous les scripts sont membres d'une table système nommé Script.
Héberger, tester et surveiller OData
Héberger des bases de données pour un accès via OData
- Suivez les étapes Activer l'accès via OData.
- Vérifiez que l'accès via OData aux bases de données FileMaker est activé et correctement configuré dans l'Admin Console de FileMaker Cloud. Consultez la documentation FileMaker Cloud dans le Centre de documentation produit.
- Vérifiez que le serveur Web et le port d'écoute OData sont en cours d'exécution.
-
Cryptez les communications.
OData exige l'utilisation d'une connexion HTTPS. Les connexions HTTPS utilisent le cryptage SSL (Secure Sockets Layer) pour les communications.
La technologie ou le langage de programmation que vous utilisez pour appeler l'API OData doit prendre en charge le protocole TLS (Transport Layer Security) v1.2 pour communiquer avec le serveur Web.
Tester l'accès via OData
Avant de mettre l'API OData en production, vérifiez qu'elle fonctionne comme prévu.
- Testez les fonctions telles que la recherche, l'ajout et la suppression des enregistrements avec différents comptes et jeux de privilèges.
- Vérifiez que les jeux de privilèges fonctionnent comme prévu en les testant avec différents comptes. Assurez-vous que des utilisateurs non autorisés ne peuvent 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 à l'autre.
Surveiller l'accès via OData
L'administrateur serveur utilise FileMaker Customer Console pour démarrer ou arrêter le port d'écoute OData, suivre l'utilisation des appels OData et télécharger le fichier journal OData.
| Pour | Utilisez |
|---|---|
| Démarrer ou arrêter le port d'écoute OData | L'onglet Connecteurs > OData de FileMaker Customer Console. Consultez l'Aide FileMaker Cloud dans le Centre de documentation produit. |
| Suivre l'utilisation des appels de l'API OData | L'onglet Connecteurs > OData de FileMaker Customer Console. Cet onglet affiche la limite annuelle d'OData définie par votre abonnement FileMaker Cloud, la quantité des données transmises depuis la date de réinitialisation annuelle précédente, et la date de réinitialisation annuelle de votre abonnement. Si vous approchez de la limite annuelle, vous pouvez l'augmenter dans l'onglet Abonnement de FileMaker Customer Console. Consultez l'Aide FileMaker Customer Console dans le Centre de documentation produit. |
| Afficher le journal de l'API OData | Les clients OData étant connectés à une base de données, les données statistiques les concernant sont consignées dans le fichier fmodata.log. Consultez l'Aide FileMaker Cloud dans le Centre de documentation produit. |