Guida di FileMaker Data API 18
Informazioni su FileMaker Data API
Panoramica
FileMaker® Data API è un'Application Programming Interface (API) che permette ai servizi Web di accedere ai dati nei database ospitati. Poiché questa API utilizza l'architettura REST (REpresentational State Transfer), FileMaker Data API è un'API REST.
L'applicazione o il servizio Web chiamano FileMaker Data API per ottenere un token di autenticazione per accedere a un database ospitato, quindi utilizzano questo token nelle chiamate successive per creare, aggiornare ed eliminare record e per eseguire richieste di ricerca.
FileMaker Data API restituisce i dati in formato JSON (JavaScript Object Notation), un formato di testo comunemente utilizzato con API REST poiché indipendente da linguaggi di programmazione specifici.
Questa guida suppone che l'utente abbia esperienza con:
- utilizzo di FileMaker Pro Advanced per creare i database. È necessario comprendere le nozioni di base sulla progettazione dei database di FileMaker Pro Advanced e i concetti di campo, relazione, formato, portale e contenitore. Vedere la Guida di FileMaker Pro Advanced.
- utilizzo di FileMaker Server o di un prodotto FileMaker Cloud per ospitare i database. È necessario comprendere come configurare l'host, consentire l'accesso ai database ospitati e monitorare i database ospitati utilizzando l'Admin Console.
- FileMaker Cloud è un servizio che fornisce l'accesso nel cloud ad app personalizzate che utilizzano FileMaker Pro Advanced, FileMaker Go e FileMaker WebDirect. FileMaker Cloud utilizza il sistema di accesso integrato ID FileMaker per autenticare gli utenti. FileMaker Cloud è offerto direttamente da FileMaker, Inc.
- FileMaker Cloud for AWS è un servizio che fornisce l'accesso nel cloud ad app personalizzate che utilizzano FileMaker Pro Advanced, FileMaker Go e FileMaker WebDirect. FileMaker Cloud for AWS viene eseguito sul cloud Amazon Web Services (AWS) ed è disponibile su AWS Marketplace.
- Prodotti FileMaker Cloud indica sia FileMaker Cloud che FileMaker Cloud for AWS.
- utilizzo di API REST in applicazioni lato server o servizi Web che chiamano i metodi POST, GET, PATCH e DELETE con dati in formato JSON. È possibile utilizzare qualsiasi linguaggio o strumento di programmazione desiderato.
In questa guida, il termine Admin Console indica l'Admin Console per FileMaker Server, FileMaker Cloud for AWS e FileMaker Cloud, a meno che non venga descritto un determinato prodotto. FileMaker Cloud Admin Console indica l'Admin Console per entrambi i prodotti FileMaker Cloud, a meno che non venga descritto un determinato prodotto.
Per utilizzare FileMaker Data API, procedere come segue:
- Preparare il database per l'accesso tramite FileMaker Data API utilizzando FileMaker Pro Advanced. È possibile creare un database o prepararne uno esistente. Vedere Preparare i database per l'accesso tramite FileMaker Data API.
- Scrivere il codice per richiamare i metodi di FileMaker Data API per cercare, creare, modificare, duplicare ed eliminare i record in un database ospitato. Vedere Scrivere le chiamate FileMaker Data API.
- Ospitare la soluzione con accesso tramite FileMaker Data API abilitato. Vedere Ospitare una soluzione FileMaker Data API.
- Verificare che l'accesso tramite FileMaker Data API funzioni correttamente. Vedere Testare una soluzione FileMaker Data API.
- Monitorare la soluzione ospitata utilizzando l'Admin Console. Vedere Monitorare le soluzioni FileMaker Data API.
Elaborazione di una chiamata FileMaker Data API
Client API REST
1
6
Server Web
2
5
Motore di FileMaker Data API
3
4
Server database
-
Un client API REST invia una chiamata FileMaker Data API (richiesta HTTPS) al server Web attraverso la porta HTTPS (porta 443). Non è necessario che FileMaker Pro Advanced sia installato o in esecuzione.
- Il server Web invia la richiesta attraverso il Modulo Server Web di FileMaker al Motore di FileMaker Data API.
- Il Motore di FileMaker Data API converte la richiesta HTTPS (URL e dati JSON) in un formato comprensibile per il componente server database e richiede i dati dal database ospitato dal server database.
- Il server database invia i dati FileMaker richiesti al Motore di FileMaker Data API.
- Il Motore di FileMaker Data API converte i dati FileMaker in una risposta HTTPS (URL con dati JSON) per rispondere alla chiamata, passando i dati al server Web.
- Il server Web invia la risposta HTTPS al client API REST che ha inviato la richiesta.
Il Motore di FileMaker Data API richiede che le porte 3000 e 8989 siano disponibili.
Il server database richiede che la porta 5003 sia disponibile.
Alternative per la pubblicazione Web
Se non si ha esperienza con le API REST, considerare le seguenti alternative per pubblicare i dati FileMaker su Internet.
FileMaker WebDirect™: se dispongono dei privilegi di accesso, gli utenti Web si collegano al database ospitato per visualizzare, modificare, ordinare o ricercare i record. Non devono installare un software aggiuntivo, ma semplicemente disporre di un browser Web compatibile e avere accesso a Internet o a una rete intranet. L'interfaccia utente è simile all'applicazione desktop FileMaker Pro Advanced. Le pagine Web e i moduli con cui l'utente Web interagisce dipendono dai formati e dalle visualizzazioni definiti nel database FileMaker Pro Advanced.
Vedere la Guida di FileMaker WebDirect.
Pubblicazione statica: se i dati vengono modificati di rado oppure se non si desidera che gli utenti si connettano dinamicamente al database, è possibile ricorrere alla pubblicazione statica. La pubblicazione statica consente di esportare i dati di FileMaker Pro Advanced per creare una pagina Web personalizzabile con HTML. La pagina Web non riflette le modifiche apportate alle informazioni nel database e gli utenti non si connettono al database.
Vedere Pubblicazione di dati su pagine Web statiche nella Guida di FileMaker Pro Advanced.
Pubblicazione Web personalizzata: per integrare il database FileMaker con un sito Web personalizzato, utilizzare le tecnologie di Pubblicazione Web personalizzata fornite da FileMaker Server.
Vedere la Guida alla Pubblicazione Web personalizzata di FileMaker Server.
Preparare i database per l'accesso tramite FileMaker Data API
Determinare i dati a cui accedere
È possibile creare un database FileMaker Pro Advanced da utilizzare con FileMaker Data API oppure utilizzare un database esistente. Se si crea un database, è possibile progettare i formati e i campi richiesti dalla soluzione FileMaker Data API. Se si utilizza un database esistente, considerare la possibilità di creare un formato specifico per la soluzione FileMaker Data API.
Quando si accede ai dati dei record, le chiamate FileMaker Data API richiedono che si specifichi un formato. FileMaker Data API utilizza la visualizzazione predefinita definita per il formato specificato.
Specificare un formato che definisca Visualizza come modulo come visualizzazione predefinita per il formato. Se si utilizza un formato che definisce Visualizza come tabella come visualizzazione predefinita, FileMaker Data API sarà solo in grado di ricavare i dati del primo record correlato.
Proteggere le soluzioni FileMaker Data API
FileMaker Data API richiede al codice API REST di accedere alla sessione di un database utilizzando un account protetto da password. Assegnare delle password agli account del database utilizzati per l'accesso tramite API REST oppure utilizzare un provider di servizi OAuth per questi account.
Note
- Quando si definiscono nomi account e password per le soluzioni FileMaker Data API, utilizzare caratteri ASCII stampabili, ad esempio a-z, A-Z e 0-9. Per nomi account e password più sicuri, includere caratteri di punteggiatura come "!" e "%", ma non i due punti. Vedere la Guida di FileMaker Pro Advanced.
- Per i database ospitati su FileMaker Cloud, è necessario utilizzare account ID FileMaker. Vedere la documentazione di FileMaker Cloud nel centro documentazione prodotto.
Consentire l'accesso tramite FileMaker Data API
È necessario attivare il privilegio esteso fmrest, Accesso attraverso FileMaker Data API, in ciascun database a cui si desidera accedere utilizzando FileMaker Data API. Se non si attiva il privilegio esteso fmrest, le applicazioni API REST non saranno in grado di utilizzare FileMaker Data API per accedere al database, anche se questo è ospitato.
Nota:per motivi di sicurezza, attivare il privilegio esteso fmrest solo nei set di privilegi per gli account a cui si desidera consentire l'accesso tramite FileMaker Data API.
Vedere "Modifica dei privilegi estesi per un set di privilegi" nella Guida di FileMaker Pro Advanced.
Progettare la soluzione FileMaker Data API
Funzioni di FileMaker Data API
FileMaker Data API fornisce un'API REST per accedere ai dati nei database ospitati. FileMaker Data API permette al codice di:
- ottenere informazioni sull'host; ad esempio, informazioni sul prodotto e nomi dei database ospitati. Vedere Ricavare i metadati.
- ottenere informazioni su un database ospitato; ad esempio, nomi degli script, nomi dei formati o metadati dei formati, inclusi nomi dei campi, nomi delle liste valori e contenuti delle liste valori. Vedere Ricavare i metadati.
- accedere o disconnettersi da un database ospitato. Vedere Accedere o disconnettersi da un database.
- creare, modificare, duplicare, eliminare o ricavare un record; oppure ricavare una serie di record. Vedere Lavorare con i record.
- eseguire richieste di ricerca. Vedere Eseguire una richiesta di ricerca.
- impostare valori di campi globali. Vedere Impostare valori di campi globali.
- eseguire script FileMaker. Vedere Script FileMaker e FileMaker Data API.
- caricare dati nei campi Contenitore. Vedere Caricare dati Contenitore.
- accedere ai dati in tabelle FileMaker esterne. Vedere Accedere a un'origine dati esterna.
- utilizzare un formato diverso per i dati di risposta quando si ricava un record o una serie di record. Vedere Ricavare un singolo record, Ricavare una serie di record e Eseguire una richiesta di ricerca.
FileMaker Data API non supporta:
- accesso ai dati in origini dati ODBC esterne.
- plug-in FileMaker.
- attivazione dei trigger di script attraverso l'interazione dell'utente. Una soluzione FileMaker Data API può attivare i trigger di script solo eseguendo uno script FileMaker.
- accesso al file system della macchina server. Ad esempio, FileMaker Data API non supporta la funzione Get ( PercorsoTemporaneo ) di FileMaker Pro Advanced. Se utilizzata con FileMaker Data API, questa funzione restituisce una stringa vuota. I file possono essere memorizzati in un campo Contenitore, ma non è possibile accedere al file system del server.
FileMaker Data API restituisce i dati dei campi così come memorizzati nel database, non come visualizzati in FileMaker Pro Advanced.
Informazioni sul riferimento di FileMaker Data API
Il riferimento di FileMaker Data API fornisce informazioni dettagliate su tutte le chiamate supportate da FileMaker Data API.
Nota:per visualizzare le informazioni sul riferimento, verificare che l'accesso tramite FileMaker Data API sia stato abilitato nell'Admin Console. Visitare il centro documentazione prodotto.
- Per visualizzare il riferimento su un host FileMaker Cloud, aprire un browser e inserire l'URL
https://host/fmi/data/apidoc/
dovehostè l'indirizzo IP o il nome host dell'host FileMaker Cloud. - Per visualizzare il riferimento su una macchina master FileMaker Server, aprire un browser e inserire l'URL
https://hostlocale/fmi/data/apidoc/ - Per visualizzare il riferimento su una macchina remota FileMaker Server, aprire un browser e inserire l'URL
https://host/fmi/data/apidoc/
dovehostè l'indirizzo IP o il nome host della macchina master su cui è in esecuzione FileMaker Server. Se FileMaker Server è installato su un server Windows, i file del riferimento si trovano nella cartella
[unità]:\Programmi\FileMaker\FileMaker Server\Documentation\Data API Documentation
dove[unità]è l'unità in cui risiede la distribuzione di FileMaker Server.Se l'installazione viene eseguita in una posizione non predefinita in Windows, la posizione di installazione sostituisce l'inizio del percorso di installazione predefinito
[unità]:[posizione_installazione]\FileMaker\FileMaker Server\Documentation\Data API Documentation- Se FileMaker Server è installato su un server macOS, i file del riferimento si trovano nella cartella
/Libreria/FileMaker Server/Documentation/Data API Documentation
Note
- I file del riferimento mostrano le variabili negli URL utilizzando una parola chiave preceduta da due punti (:). Ad esempio:
:database - Questa guida mostra le variabili negli URL utilizzando un font corsivo. Ad esempio:
nome-database
Note su URL e formato dati
- La lunghezza URI massima di FileMaker Data API potrebbe essere influenzata da eventuali differenze in sistemi operativi, server Web e browser Web. Per un utilizzo ottimale su piattaforme diverse, limitare la lunghezza URI a 2000 caratteri.
- Potrebbero esserci URL o parti di URL in cui non viene fatta distinzione tra maiuscole e minuscole, ma, in generale, trattare gli URL come se facessero distinzione tra maiuscole e minuscole. Ad esempio, se si utilizza un nome di database minuscolo per accedere alla sessione di un database, continuare a utilizzare un nome di database minuscolo per tutti gli URL successivi che passano lo stesso token di sessione. In caso contrario, potrebbe essere visualizzato un messaggio di errore token non valido.
- Le stringhe negli URL devono utilizzare la codifica URL, detta anche codifica percentuale, normale per le richieste HTTP. Ad esempio, per specificare il nome di un formato che include un carattere barra, è necessario specificare il carattere barra come valore codificato: "%2F"
- I valori dei dati delle stringhe specificati nei parametri nel corpo della richiesta devono utilizzare la codifica UTF-8.
- In generale, FileMaker Data API tratta i valori dei dati numerici come se fossero in formato a virgola mobile a precisione doppia (binary64). Utilizzare il formato dati corrispondente nel linguaggio di programmazione utilizzato (i valori dei dati numerici non devono essere racchiusi tra virgolette e non devono utilizzare la codifica URL).
- I valori dei dati per i campi Numero, Data, Ora e Indicatore data e ora seguono gli stessi limiti specificati da FileMaker Pro Advanced. Vedere la Guida di FileMaker Pro Advanced.
- I campi e i portali specificati devono trovarsi nel formato specificato.
- Per specificare campi correlati, utilizzare la sintassi
portalData.Nota:la sintassi
nometabella::campo-correlato(numero-ripetizione).id-recorddella release precedente è ancora supportata, ma si preferisce la sintassiportalData. - Nel corpo della risposta, FileMaker Data API restituisce solo il nome dei campi della tabella corrente e il nome completamente qualificato dei campi delle tabelle correlate. Per i campi portale, il nome completamente qualificato utilizza il nome del portale se a questo è stato assegnato un nome nella finestra Impostazioni; in caso contrario, il nome completamente qualificato utilizza il nome della ricorrenza di tabella.
- Per i dati dei campi Contenitore, FileMaker Data API restituisce un URL con il percorso dell'oggetto dati Contenitore.
Script FileMaker e FileMaker Data API
Uno script FileMaker è costituito da una o più istruzioni (istruzioni di script) definite per automatizzare operazioni ripetitive o particolarmente complesse. Se utilizzati con FileMaker Data API, gli script FileMaker possono consentire ai servizi Web di eseguire più operazioni o una serie di operazioni. Vedere Esecuzione di script FileMaker.
Per visualizzare le istruzioni di script supportate da FileMaker Data API, nell'Area di lavoro script di FileMaker Pro Advanced, fare clic sul pulsante Compatibilità e selezionare FileMaker Data API. Le istruzioni di script non disattivate sono supportate da FileMaker Data API. Alcune istruzioni di script funzionano diversamente o potrebbero non essere supportate in FileMaker Data API. Vedere la Guida di FileMaker Pro Advanced.
Gli script eseguiti da FileMaker Data API non possono eseguire script in altri file FileMaker, a meno che i file siano ospitati sullo stesso host. Gli altri file FileMaker devono avere il privilegio esteso fmrest attivato.
In FileMaker Pro Advanced, i trigger di script possono essere attivati sia dagli script che dalle azioni dell'utente (come il clic in un campo). Nelle soluzioni FileMaker Data API, invece, i trigger di script possono essere attivati solo dagli script. Per informazioni sui trigger di script, vedere la Guida di FileMaker Pro Advanced.
Note
- Considerare la quantità di dati e il numero di record che uno script potrebbe restituire e definire gli script di conseguenza. In FileMaker Pro Advanced, uno script può restituire tutti i record di una tabella o del gruppo trovato corrente. Tuttavia, se uno script restituisce tutti i record di una tabella, un servizio Web può esaurire la memoria nel tentativo di elaborarli.
- Utilizzare gli account e i privilegi per limitare il gruppo di script eseguibili da un servizio Web. Verificare che gli script contengano solo istruzioni di script compatibili con il Web e fornire l'accesso solo agli script che possono essere utilizzati da un servizio Web.
- Considerare gli effetti collaterali degli script che eseguono una combinazione di istruzioni controllate dai privilegi di accesso. Ad esempio, se uno script contiene un'istruzione per eliminare i record e il servizio Web non esegue l'accesso con un account che consente tale operazione, lo script non eseguirà l'istruzione di script Elimina record. Tuttavia, l’esecuzione dello script potrebbe continuare, provocando risultati imprevisti.
- Nell'Area di lavoro script, garantire privilegi di accesso completo a uno script per permettere allo script di eseguire operazioni a cui non si desidera consentire l'accesso ai singoli utenti. Ad esempio, è possibile impedire agli utenti di eliminare i record con i rispettivi account e privilegi, ma consentire loro di eseguire uno script che elimini determinati record alle condizioni definite nello script.
- Gli endpoint FileMaker Data API salvano immediatamente le modifiche ai dati, ma gli script potrebbero lasciare i record non salvati. Ad esempio, una sessione potrebbe eseguire uno script che modifica un record, ma non lo salva; la sessione successiva restituirebbe quindi un errore quando si tenta di modificare lo stesso record. Oppure, all'interno di una singola sessione, uno script potrebbe modificare un record, quindi creare una nuova finestra e richiamare un secondo script che tenta di modificare lo stesso record. Assicurarsi di verificare i risultati degli script e che non vi siano errori negli script.
- Tutti gli script che modificano i dati devono includere l'istruzione di script Salva record/richieste perché le modifiche apportate ai dati non sono accessibili finché i dati non vengono salvati sul server. Sono incluse istruzioni di script come Taglia, Copia e Incolla. Molte azioni ad istruzione singola devono essere convertite in script per includere l’istruzione Salva record/richieste. Quando si progettano script che verranno eseguiti da un servizio Web, includere l'istruzione Salva record/richieste al termine di uno script per assicurarsi che vengano salvate tutte le modifiche.
- Aprire tutti gli script che potrebbero essere eseguiti dagli utenti Web e assicurarsi che vengano eseguiti correttamente quando il database è ospitato come una soluzione FileMaker Data API. Verificare che lo script utilizzi solo istruzioni di script supportate da FileMaker Data API, come descritto in precedenza.
Scrivere le chiamate FileMaker Data API
Componenti delle chiamate API REST
Le chiamate FileMaker Data API sono costituite dai seguenti componenti.
| Componente | Descrizione |
|---|---|
Un metodo HTTP (detto anche verbo HTTP) |
FileMaker Data API utilizza i seguenti metodi HTTP:
|
Intestazioni HTTP |
FileMaker Data API utilizza le seguenti intestazioni:
|
| Un URL di chiamata | Gli URL di FileMaker Data API iniziano tutti con:
|
| Dati dei parametri in formato JSON | Non necessari per disconnettersi dalla sessione di un database, ricavare i metadati, eliminare un record, duplicare un record, ricavare un singolo record, ricavare una serie di record o eseguire uno script. |
Accedere o disconnettersi da un database
FileMaker Data API utilizza un token di accesso per definire una connessione a un database. Quel token di accesso deve essere utilizzato nell'intestazione di tutte le successive chiamate per il database ospitato. Il token di accesso è valido fino alla disconnessione dalla sessione di un database o per 15 minuti dopo l'ultima chiamata in cui è stato specificato (mentre il token è valido, ogni chiamata che specifica il token riporta il contatore del timeout della sessione a zero).
Accedere alla sessione di un database
Per accedere a un database ospitato, utilizzare un metodo POST HTTP con endpoint API sessions specificando il nome di un database ospitato. Nome account e password sono specificati in una stringa di intestazione Authorization. Se nome account e password vengono autenticati, il codice riceve un token di accesso che definisce la connessione al database. Questa connessione viene chiamata sessione del database.
| Metodo HTTP | POST |
|---|---|
| URL | /fmi/data/versione/databases/nome-database/sessions
versione – versione di FileMaker Data API richiesta ( |
| Intestazione HTTP | Content-Type: application/json Authorization: una stringa con codifica Base64 che rappresenta il nome account e la password da utilizzare per accedere al database ospitato. Questa stringa con codifica Base64 deve seguire lo schema di autenticazione di base HTTP standard (nome account e password sono separati da due punti). |
| Parametri |
Un gruppo vuoto di parentesi graffe. Ad esempio:
In alternativa, è possibile utilizzare il parametro |
| Risposta | Il token di accesso, un corpo della risposta con il token di accesso e una matrice di messaggi con un codice di errore 0. Come risposta, viene restituita l'intestazione X-FM-Data-Access-Token, ovvero il token di sessione da utilizzare per le chiamate API successive. Ad esempio: Intestazione:
"X-FM-Data-Access-Token": "c4d2e429122e9cdeda19bb23c55cd2a8f282c3cc50c60943a110",
{
Corpo:
"messages": [
{
"message": "OK",
"code": "0"
}
],
"response": {
"token": "c4d2e429122e9cdeda19bb23c55cd2a8f282c3cc50c60943a110"
},
"HTTPMessage": "OK",
"HTTPCode": 200
}
Vedere Risposte di errore. |
Accedere a un'origine dati esterna
Se il database ospitato deve accedere a un'origine dati esterna, il nome del database ospitato è specificato nell'URL, il nome account e la password per il database ospitato sono specificati in una stringa di intestazione Authorization e il nome del database, il nome account e la password per l'origine dati esterna sono specificati nel parametro fmDataSource come matrice JSON.
| Metodo HTTP | POST |
|---|---|
| URL | /fmi/data/versione/databases/nome-database/sessions
versione – versione di FileMaker Data API richiesta ( |
| Intestazione HTTP | Content-Type: application/json Authorization: una stringa con codifica Base64 che rappresenta il nome account e la password da utilizzare per accedere al database ospitato. Questa stringa con codifica Base64 deve seguire lo schema di autenticazione di base HTTP standard |
| Parametri | Il parametro Ad esempio: { "fmDataSource":
[ { "database":"contatti", "username":"admin", "password":"admin" } ]
}
Per utilizzare un account OAuth per accedere all'origine dati esterna, specificare il valore dell'intestazione X-FMS-Request-ID ( { "fmDataSource":
[ { "database":"contatti", "oAuthRequestId": "E65B98BB17429CO643B31119F", "oAuthIdentifier": "B164A3459A776E5177445DR223"} ]
}
|
| Risposta | Il token di accesso, un corpo della risposta vuoto e una matrice di messaggi con un codice di errore 0. Come risposta, viene restituita l'intestazione X-FM-Data-Access-Token, ovvero il token di sessione da utilizzare per le chiamate API successive. Ad esempio: X-FM-Data-Access-Token: c13c0f486780f2187bde6f3859dabd4dcf8ea43be420dfeadf34
{
"response": {},
"messages":[{"code":"0","message":"OK"}]
}
Vedere Risposte di errore. |
Note
- I database FileMaker sono le uniche origini dati esterne supportate. Specificare il nome del database senza l'estensione .fmp12.
- I file elencati nel parametro
fmDataSourceverranno aperti quando necessario, ad esempio quando viene eseguito uno script o quando il contesto passa a un formato che richiede l'origine dati esterna. Di conseguenza, gli errori di accesso all'origine dati esterna si verificano quando si tenta di aprire il file, non quando si accede alla sessione del database.
Accedere alla sessione di un database utilizzando un provider di identità OAuth
Per accedere a un database ospitato utilizzando un provider di identità OAuth, utilizzare un metodo POST HTTP con endpoint API sessions specificando il database. Utilizzare le stringhe X-FM-Data-OAuth-Request-Id e X-FM-Data-OAuth-Identifier nell'intestazione per autenticare l'accesso al database ospitato. Se l'autenticazione è accettata, il codice riceve un token di accesso che definisce la connessione al database. Questa connessione viene chiamata sessione del database.
| Metodo HTTP | POST |
|---|---|
| URL | /fmi/data/versione/databases/nome-database/sessions
versione – versione di FileMaker Data API richiesta ( |
| Intestazione HTTP | Content-Type: application/json X-FM-Data-OAuth-Request-Id: id-richiesta X-FM-Data-OAuth-Identifier: parametro-identificativo |
| Parametri |
Un gruppo vuoto di parentesi graffe. Ad esempio: In alternativa, è possibile utilizzare il parametro |
| Risposta | Il token di accesso, un corpo della risposta vuoto e una matrice di messaggi con un codice di errore 0. Come risposta, viene restituita l'intestazione X-FM-Data-Access-Token, ovvero il token di sessione da utilizzare per le chiamate API successive. Ad esempio: X-FM-Data-Access-Token: 823c0f48bb80f2187bde6f3859dabd4dcf8ea43be420dfeadf34
{
"response": {},
"messages":[{"code":"0","message":"OK"}]
}
Vedere Risposte di errore. |
Per ricavare i parametri OAuth in formato JSON:
-
Ricavare l'elenco dei provider OAuth supportati utilizzando un metodo GET HTTP con questo URL:
https://host/fmws/oauthproviderinfodove host è l'indirizzo IP o il nome di dominio della macchina master nella distribuzione di FileMaker Server o l'indirizzo IP o il nome di dominio dell'host FileMaker Cloud for AWS. L'elenco viene restituito in formato JSON.
- Selezionare un provider OAuth supportato e ricavare un ID di monitoraggio per la sessione.
-
Utilizzare un metodo GET HTTP con questo URL:
http://host/oauth/getoauthurl?trackingID=ID-monitoraggio&provider=provider-OAuth&address=127.0.0.1&X-FMS-OAuth-AuthType=2dove host è l'indirizzo IP o il nome di dominio della macchina master nella distribuzione di FileMaker Server o l'indirizzo IP o il nome di dominio dell'host FileMaker Cloud for AWS, ID-monitoraggio è l'ID di monitoraggio generato dallo sviluppatore per la sessione e provider-OAuth è il nome del provider OAuth selezionato.
L'intestazione HTTP per questa richiesta deve includere quanto segue:
- X-FMS-Application-Type: 9
- X-FMS-Application-Version: 15
- X-FMS-Return-URL: http://127.0.0.1/
- Leggere l'intestazione di risposta per i dati X-FMS-Request-ID. Questa intestazione di risposta contiene l'ID della richiesta OAuth da utilizzare per la stringa X-FM-Data-OAuth-Request-Id nell'intestazione.
- Leggere l'intestazione di risposta per i dati X-FMS-Return-URL. Chiamare l'URL restituito in questo parametro per permettere all'utente di eseguire l'autenticazione con il provider OAuth.
- L'"identificativo" restituito dal provider OAuth è il parametro identificativo OAuth da utilizzare per la stringa X-FM-Data-OAuth-Identifier nell'intestazione.
Vedere "Modifica dell'accesso tramite account OAuth" nella Guida di FileMaker Pro Advanced.
Accedere alla sessione di un database utilizzando un account ID FileMaker
Per i file ospitati da FileMaker Cloud, gli utenti sono autenticati tramite account ID FileMaker. Gli account ID FileMaker vengono definiti nel sistema del provider di identità ID FileMaker.
Per accedere a un database ospitato utilizzando un account ID FileMaker, utilizzare un metodo POST HTTP con endpoint API sessions specificando il nome di un database ospitato. Il token ID FileMaker è specificato in una stringa di intestazione Authorization. Il codice riceve un token di accesso che definisce la connessione al database. Questa connessione viene chiamata sessione del database.
| Metodo HTTP | POST |
|---|---|
| URL | /fmi/data/versione/databases/nome-database/sessions
versione – versione di FileMaker Data API richiesta ( |
| Intestazione HTTP | Content-Type: application/json Authorization: FMID {token-FMID} token-FMID è il token ID FileMaker fornito dal sistema del provider di identità ID FileMaker. Per informazioni sul token ID FileMaker, vedere la Guida della FileMaker Customer Console nel centro documentazione prodotto. Vedere "Modifica dell'accesso tramite account ID FileMaker" nella Guida di FileMaker Pro Advanced. |
| Parametri |
Un gruppo vuoto di parentesi graffe. Ad esempio: |
| Risposta | Il token di accesso, un corpo della risposta vuoto e una matrice di messaggi con un codice di errore 0. Come risposta, viene restituita l'intestazione X-FM-Data-Access-Token, ovvero il token di sessione da utilizzare per le chiamate API successive. Ad esempio: X-FM-Data-Access-Token: 823c0f48bb80f2187bde6f3859dabd4dcf8ea43be420dfeadf34
{
"response": {},
"messages":[{"code":"0","message":"OK"}]
}
Vedere Risposte di errore. |
Disconnettersi dalla sessione di un database
Quando il codice termina l'accesso al database ospitato, utilizzare un metodo DELETE HTTP con endpoint API sessions specificando il nome del database ospitato e il token di accesso per la sessione. Se il codice non esegue la disconnessione dalla sessione del database, il token di accesso rimane valido fino allo scadere della sessione FileMaker Data API, 15 minuti dopo l'ultima chiamata in cui è stato specificato.
| Metodo HTTP | DELETE |
|---|---|
| URL | /fmi/data/versione/databases/nome-database/sessions/token-sessione
versione – versione di FileMaker Data API richiesta ( nome-database – nome del database ospitato token-sessione – X-FM-Data-Access-Token per la sessione del database |
| Intestazione HTTP | Content-Type: application/json |
| Parametri | Nessuno. |
| Risposta |
Un corpo della risposta vuoto e una matrice di messaggi con un codice di errore 0. Ad esempio: {
"response": {},
"messages":[{"code":"0","message":"OK"}]
}
Vedere Risposte di errore. |
Ricavare i metadati
FileMaker Data API supporta il recupero dei seguenti metadati:
- le informazioni di prodotto sull'host. Vedere Ricavare le informazioni di prodotto.
- i nomi dei database ospitati. Vedere Ricavare i nomi dei database.
- i nomi degli script FileMaker disponibili in un database ospitato. Vedere Ricavare i nomi degli script.
- i nomi dei formati disponibili in un database ospitato. Vedere Ricavare i nomi dei formati.
- ulteriori metadati relativi a formati specifici in un database ospitato. Vedere Ricavare i metadati dei formati.
Ricavare le informazioni di prodotto
Per recuperare le informazioni di prodotto sull'host, utilizzare un metodo GET HTTP con endpoint API productInfo.
| Metodo HTTP | GET |
|---|---|
| URL |
Formato: /fmi/data/versione/productInfo
|
| Intestazione HTTP | Nessuna. |
| Parametri | Nessuno. |
| Risposta |
Una matrice di messaggi con un codice di errore 0. Vedere Risposte di errore. Un corpo della risposta con i seguenti metadati:
Ad esempio: {
"response": {
"productInfo": {
"buildDate": "01/30/2020",
"dateFormat": "MM/dd/yyyy",
"timeStampFormat": "MM/dd/yyyy HH:mm:ss",
"version": "18.0.1.30",
"timeFormat": "HH:mm:ss",
"name": "FileMaker Data API Engine"
}
},
"messages": [
{
"code": "0",
"message": "OK"
}
]
}
|
Ricavare i nomi dei database
Per recuperare i nomi di tutti i database ospitati e abilitati per l'accesso tramite FileMaker Data API, utilizzare un metodo GET HTTP con endpoint API databases.
| Metodo HTTP | GET |
|---|---|
| URL | Formato: fmi/data/versione/databases
|
| Intestazione HTTP |
L'intestazione Authorization dipende dall'impostazione Filtrare i database nelle applicazioni client nell'Admin Console.
|
| Parametri | Nessuno. |
| Risposta |
Una matrice di database con un elenco dei nomi dei database e una matrice di messaggi con un codice di errore 0. Ad esempio: {
"response": {
"databases": [{
"name": "Clienti"
}, {
"name": "Vendite"
}]
},
"messages": [{
"code": "0",
"message": "OK"
}]
}
Vedere Risposte di errore. |
Ricavare i nomi degli script
Per recuperare i nomi di tutti gli script disponibili per un determinato database, utilizzare un metodo GET HTTP con endpoint API scripts.
| Metodo HTTP | GET |
|---|---|
| URL | Formato: /fmi/data/versione/databases/nome-database/scripts
|
| Intestazione HTTP | Authorization: token-sessione di connessione, dove token-sessione è il valore X-FM-Data-Access-Token univoco per la sessione del database |
| Parametri | Nessuno. |
| Risposta |
Una matrice di script con un elenco dei nomi e delle cartelle degli script e una matrice di messaggi con un codice di errore 0. Ad esempio: {
"response": {
"scripts": [
{
"name": "VaialPrimo",
"isFolder": false
},
{
"name": "Una cartella",
"isFolder": true,
"folderScriptNames": [
{
"name": "script1",
"isFolder": false
},
{
"name": "-",
"isFolder": false
},
{
"name": "script2",
"isFolder": false
},
{
"name": "Un'altra cartella",
"isFolder": true,
"folderScriptNames": [
{
"name": "script3",
"isFolder": false
}
]
},
{
"name": "script4",
"isFolder": false
}
]
}
]
},
"messages": [
{
"message": "OK",
"code": "0"
}
]
}
Vedere Risposte di errore. |
Ricavare i nomi dei formati
Per recuperare i nomi di tutti i formati disponibili per un determinato database, utilizzare un metodo GET HTTP con endpoint API layouts.
| Metodo HTTP | GET |
|---|---|
| URL | Formato: /fmi/data/versione/databases/nome-database/layouts
|
| Intestazione HTTP | Authorization: token-sessione di connessione, dove token-sessione è il valore X-FM-Data-Access-Token univoco per la sessione del database |
| Parametri | Nessuno. |
| Risposta |
Una matrice di formati con un elenco dei nomi dei formati e una matrice di messaggi con un codice di errore 0. Ad esempio: {
"messages": [
{
"message": "OK",
"code": "0"
}
],
"response": {
"layouts": [
{
"name": "Clienti"
},
{
"name": "Dettagli"
},
{
"folderLayoutNames": [
{
"name": "Segna come inviato"
},
{
"name": "Trova non inviato"
}
],
"isFolder": true,
"name": "Gestione pacchetto"
}
]
}
}
Vedere Risposte di errore. |
Ricavare i metadati dei formati
Per recuperare i metadati dei formati, inclusi campi di un formato, portali e liste valori, utilizzare un metodo GET HTTP con endpoint API layouts e specificare il nome di un formato.
| Metodo HTTP | GET |
|---|---|
| URL | Formato 1: /fmi/data/versione/databases/nome-database/layouts/nome-formato
Formato 2: /fmi/data/versione/databases/nome-database/layouts/nome-formato?recordId=id-record
|
| Intestazione HTTP | Authorization: token-sessione di connessione, dove token-sessione è il valore X-FM-Data-Access-Token univoco per la sessione del database |
| Parametri | Nessuno. |
| Risposta |
Un corpo della risposta con matrici fieldMetaData, portalMetaData e valueLists e una matrice di messaggi con un codice di errore 0. Ad esempio: {
"response": {
"fieldMetaData": [
{
"name": "NomeCliente",
"type": "normal",
"displayType": "editText",
"result": "text",
"valueList": "Testo",
"global": false,
"autoEnter": false,
"fourDigitYear": false,
"maxRepeat": 1,
"maxCharacters": 0
"notEmpty": false,
"numeric": false,
"timeOfDay": false,
"repetitionStart": 1,
"repetitionEnd": 1
}
],
"portalMetaData": {},
"valueLists": [
{
"name": "Regione",
"type": "customList",
"values": [
{
"displayValue": "Ovest",
"value": "Ovest"
}
,
{
"displayValue": "Est",
"value": "Est"
}
]
}
]
},
"messages": [
{
"code": "0",
"message": "OK"
}
]
}
Vedere Risposte di errore. |
Note
- Per le liste valori dinamiche, viene restituita una lista valori vuota quando la richiesta non include un parametro
recordIdcome parte dell'URL.
Lavorare con i record
Creare un record
Per creare un record, utilizzare un metodo POST HTTP con endpoint API records specificando il nome del database e il formato.
| Metodo HTTP | POST |
|---|---|
| URL |
/fmi/data/versione/databases/nome-database/layouts/nome-formato/records
versione – versione di FileMaker Data API richiesta ( |
| Intestazione HTTP | Content-Type: application/json Authorization: token-sessione di connessione, dove token-sessione è il valore X-FM-Data-Access-Token univoco per la sessione del database |
| Parametri | I dati del record in formato JSON contenenti coppie campo-valore che specificano i valori per i campi che si trovano nel formato di destinazione. I dati possono specificare record correlati o portali che si trovano nel formato utilizzando la specifica portalData. Il nome di un portale può essere il nome oggetto visualizzato nella finestra Impostazioni di FileMaker Pro Advanced o il nome della tabella correlata. Ad esempio: {"fieldData":
{
"Campo stringa": "valore_1",
"Campo numero": 99,99,
"campoRipetizione(1)" : "valoreCampo"
}
}
Nota:per creare un record vuoto con valori predefiniti per ciascun campo, specificare un oggetto dati vuoto in formato JSON come parametro. Ad esempio: {"fieldData":
{
}
}
È possibile eseguire script FileMaker come parte di questa richiesta includendo i parametri |
| Risposta |
L'ID del record creato e una matrice di messaggi con un codice di errore 0. Ad esempio: {
"response": {
"recordId":"147",
"modId":"0"
},
"messages": [
{
"code": "0",
"message":"OK"
}
]
}
Vedere Risposte di errore. |
Note
- Quando si creano record con FileMaker Data API, la verifica dei campi è imposta. Se i dati non superano la verifica dei campi, viene visualizzato un messaggio di errore e il record non viene creato.
Modificare un record
Per modificare un record, utilizzare un metodo PATCH HTTP con endpoint API records specificando il nome del database, il formato e l'ID del record.
| Metodo HTTP | PATCH |
|---|---|
| URL |
/fmi/data/versione/databases/nome-database/layouts/nome-formato/records/id-record
versione – versione di FileMaker Data API richiesta ( |
| Intestazione HTTP |
Content-Type: application/json Authorization: token-sessione di connessione, dove token-sessione è il valore X-FM-Data-Access-Token univoco per la sessione del database |
| Parametri | I dati del record in formato JSON contenenti coppie campo-valore da aggiornare. I dati possono specificare record correlati o portali che si trovano nel formato utilizzando la specifica portalData. Il nome di un portale può essere il nome oggetto visualizzato nella finestra Impostazioni di FileMaker Pro Advanced o il nome della tabella correlata. Vengono aggiornati solo i campi specificati; gli altri campi nel record non vengono modificati. Se come valore Parametro facoltativo: ID di modifica ( Ad esempio: {
"fieldData":
{
"Nome": "Mario"
},
"portalData":
{
"JobsTable": [
{
"recordId": "70",
"modId": "4",
"JobsTable::Name": "Fornitore esterno"
}
]
}
}
È possibile eseguire script FileMaker come parte di questa richiesta includendo i parametri |
| Risposta |
Il corpo della risposta e una matrice di messaggi con un codice di errore 0. Ad esempio: {
"response": {
"modId": "3"
},
"messages": [
{
"code": "0",
"message": "OK"
}
]
}
Vedere Risposte di errore. |
Note
- Quando si modificano record con FileMaker Data API, la verifica dei campi è imposta. Se i dati non superano la verifica dei campi, viene visualizzato un messaggio di errore e il record non viene aggiornato.
-
Per eliminare un record correlato, utilizzare la sintassi
deleteRelated.Ad esempio, per eliminare un singolo record:
"deleteRelated" : "Orders.3"Ad esempio, per eliminare più record:
"deleteRelated" : ["Orders.7", "Orders.9"]
Duplicare un record
Per duplicare un record, utilizzare un metodo POST HTTP con endpoint API records specificando il nome del database, il nome del formato e l'ID del record.
| Metodo HTTP | POST |
|---|---|
| URL |
/fmi/data/versione/databases/nome-database/layouts/nome-formato/records/id-record
versione – versione di FileMaker Data API richiesta ( |
| Intestazione HTTP |
Content-Type: application/json Authorization: token-sessione di connessione, dove token-sessione è il valore X-FM-Data-Access-Token univoco per la sessione del database |
| Parametri | Nessuno. È possibile eseguire script FileMaker come parte di questa richiesta includendo i parametri |
| Risposta |
L'ID del nuovo record e una matrice di messaggi con un codice di errore 0. Ad esempio: {
"response": {
"recordId": "7",
"modId": "0"
},
"messages": [
{
"code": "0",
"message": "OK"
}
]
}
Vedere Risposte di errore. |
Eliminare un record
Per eliminare un record, utilizzare un metodo DELETE HTTP con endpoint API records specificando il nome del database, il formato e l'ID del record.
| Metodo HTTP | DELETE |
|---|---|
| URL | /fmi/data/versione/databases/nome-database/layouts/nome-formato/records/id-record
versione – versione di FileMaker Data API richiesta ( È possibile eseguire script FileMaker come parte di questa richiesta includendo i parametri |
| Intestazione HTTP | Authorization: token-sessione di connessione, dove token-sessione è il valore X-FM-Data-Access-Token univoco per la sessione del database |
| Parametri | Nessuno. |
| Risposta |
Un corpo della risposta vuoto e una matrice di messaggi con un codice di errore 0. Ad esempio: {
"response": {},
"messages":[{"code":"0","message":"OK"}]
}
Vedere Risposte di errore. |
Ricavare un singolo record
Per ricavare un record, utilizzare un metodo GET HTTP con endpoint API records specificando il nome del database, il formato e l'ID del record. È anche possibile specificare informazioni sui portali per limitare il numero di record correlati restituiti.
| Metodo HTTP | GET |
|---|---|
| URL | Formato 1: /fmi/data/versione/databases/nome-database/layouts/nome-formato/records/id-record
versione – versione di FileMaker Data API richiesta ( Per la parola chiave del portale: La parte dell'URL relativa ai portali è facoltativa. Se il formato contiene dei portali, specificarne i nomi per risultati migliori. Se la parte relativa ai portali non viene specificata, la chiamata restituirà tutti i record correlati in tutti i portali nel formato. Per Per Per i dati di risposta nel contesto di un formato diverso, utilizzare il parametro È possibile eseguire script FileMaker come parte di questa richiesta includendo i parametri |
| Intestazione HTTP | Authorization: token-sessione di connessione, dove token-sessione è il valore X-FM-Data-Access-Token univoco per la sessione del database |
| Parametri | Nessuno. |
| Risposta | I dati del record in formato JSON e una matrice di messaggi con un codice di errore 0. Ad esempio: {
"response": {
"data": [
...
]
},
"messages": [{"code":"0","message":"OK"}]
}
Vedere Risposte di errore. |
Note
- Per restituire i dati di determinate righe del portale, utilizzare
_offset.nome-portalee_limit.nome-portale. Il nome di un portale può essere il nome oggetto visualizzato nella finestra Impostazioni di FileMaker Pro Advanced o il nome della tabella correlata. Se non si specificano i valori offset e limit per le righe del portale, i valori predefiniti per offset e limit per i record del portale sono rispettivamente 1 e 50.
Ricavare una serie di record
Per ricavare una serie di record, utilizzare un metodo GET HTTP con endpoint API records specificando il nome del database, il formato e informazioni aggiuntive per specificare un record iniziale e il numero di record. Se lo si desidera, è possibile specificare il criterio di ordinamento dei record. È anche possibile specificare informazioni sui portali per limitare il numero di record correlati restituiti.
| Metodo HTTP | GET |
|---|---|
| URL |
Formato 1 (restituisce fino ai primi 100 record):
versione – versione di FileMaker Data API richiesta ( Per Per Per Per la parola chiave del portale: La parte dell'URL relativa ai portali è facoltativa. Se il formato contiene dei portali, si potrebbero voler specificare i nomi per risultati migliori. Se la parte relativa ai portali non viene specificata, la chiamata restituirà tutti i record correlati in tutti i portali nel formato. Per Per Per i dati di risposta nel contesto di un formato diverso, utilizzare il parametro È possibile eseguire script FileMaker come parte di questa richiesta includendo i parametri |
| Intestazione HTTP | Authorization: token-sessione di connessione, dove token-sessione è il valore X-FM-Data-Access-Token univoco per la sessione del database |
| Parametri | Nessuno. |
| Risposta |
I dati del record in formato JSON e una matrice di messaggi con un codice di errore 0. Ad esempio: {
"response": {
"data": [
...
]
},
"messages": [{"code":"0","message":"OK"}]
}
Vedere Risposte di errore. |
Note
- Se non si specificano i valori offset e limit, i valori predefiniti per offset e limit per i record sono rispettivamente 1 e 100:
_offset=1&_limit=100 - Se non si specifica la parola chiave sortOrder, il valore predefinito è
ascend. Ad esempio,&_sort=[{ "fieldName": "idRecord" }]viene trattato come:&_sort=[{ "fieldName": "idRecord", "sortOrder": "ascend" }] - Per restituire i dati di determinate righe del portale, utilizzare
_offset.nome-portalee_limit.nome-portale. Il nome di un portale può essere il nome oggetto visualizzato nella finestra Impostazioni di FileMaker Pro Advanced o il nome della tabella correlata. Se non si specificano i valori offset e limit per le righe del portale, i valori predefiniti per offset e limit per i record del portale sono rispettivamente 1 e 50.
Caricare dati Contenitore
Per caricare dati Contenitore, utilizzare un metodo POST HTTP con endpoint API containers specificando il nome del database, il nome del formato, l'ID del record, il nome del campo e la ripetizione di un campo.
| Metodo HTTP | POST |
|---|---|
| URL | Formato: /fmi/data/versione/databases/nome-database/layouts/nome-formato/records/id-record/containers/nome-campo/ripetizione-campo
|
| Intestazione HTTP | Content-Type: multipart/form-data Authorization: token-sessione di connessione, dove token-sessione è il valore X-FM-Data-Access-Token univoco per la sessione del database |
| Parametri | Un flusso di dati MIME multiparte (Content-Type: multipart/form-data) dove l'oggetto del campo Contenitore è definito come una parte con Utilizzare una libreria che supporti la specifica di multipart/form-data. |
| Risposta |
Un corpo della risposta vuoto e una matrice di messaggi con un codice di errore 0. Ad esempio: {
"response": {},
"messages":[{"code":"0","message":"OK"}]
}
Vedere Risposte di errore. |
Note
- Il campo Contenitore deve essere un campo nella ricorrenza di tabella del formato specificato. Non può essere un campo Contenitore in una tabella correlata.
- FileMaker Data API supporta tutti i tipi MIME. I tipi MIME non vengono controllati per essere limitati ai tipi supportati dal software FileMaker o dal server Web.
- FileMaker Data API memorizza i dati dei campi Contenitore in una cartella cache sulla macchina master durante il caricamento, ma i dati memorizzati nella cache vengono eliminati al termine della richiesta.
Eseguire una richiesta di ricerca
Per eseguire una richiesta di ricerca, utilizzare un metodo POST HTTP con endpoint API _find specificando il nome del database, il formato e informazioni aggiuntive per specificare campi e criteri della query, criterio di ordinamento, record iniziale e numero di record. È anche possibile specificare informazioni sui portali per limitare il numero di record correlati restituiti.
| Metodo HTTP | POST |
|---|---|
| URL |
/fmi/data/versione/databases/nome-database/layouts/nome-formato/_find
versione – versione di FileMaker Data API richiesta ( |
| Intestazione HTTP |
Content-Type: application/json Authorization: token-sessione di connessione, dove token-sessione è il valore X-FM-Data-Access-Token univoco per la sessione del database |
| Parametri | Una query in formato JSON che specifica campi e criteri di ricerca. Parametri facoltativi che specificano richieste di omissione, criterio di ordinamento, record iniziale (offset), numero di record (limit) e portali per limitare il numero di record correlati restituiti. Per i dati di risposta nel contesto di un formato diverso, utilizzare il parametro Ad esempio: {
"query":[
{"Group": "=Chirurgo"},
{"Città lavoro" : "Roma", "omit" : "true"}],
"sort":[
{"fieldName": "Città lavoro","sortOrder": "ascend"},
{"fieldName": "Nome", "sortOrder": "ascend"} ]
}
Esempio con parametri offset, limit e portal: {
"query":[
{"Group": "=Chirurgo"},
{"Città lavoro" : "Roma", "omit" : "true"}],
"portal": ["Portale1","Portale2"],
"limit": "10",
"offset": "1",
"offset.Portale1": "1",
"limit.Portale1": "5",
"layout.response": "Medici"
}
È possibile eseguire script FileMaker come parte di questa richiesta includendo i parametri |
| Risposta |
I dati del record in formato JSON e una matrice di messaggi con un codice di errore 0. Ad esempio: {
"response": {
"data": [
...
]
},
"messages": [{"code":"0","message":"OK"}]
}
Vedere Risposte di errore. |
Note
- L'ordinamento e la restituzione dei record potrebbe richiedere molto tempo. Ridurre il tempo per il download dei record limitando il numero di campi sul formato richiesto e omettendo i campi che contengono commenti.
- Per limitare il numero di record e righe da visualizzare in un gruppo correlato, specificare i parametri offset.nome-portale e limit.nome-portale.
- Non è possibile specificare campi globali come criteri di ricerca. Se si specifica un campo globale con una richiesta di ricerca, viene visualizzato un messaggio di errore. Impostare invece il valore del campo globale prima della richiesta di ricerca. Vedere Impostare valori di campi globali.
Impostare valori di campi globali
Per impostare i valori per i campi globali, utilizzare un metodo PATCH HTTP con endpoint API globals specificando il nome del database.
| Metodo HTTP | PATCH |
|---|---|
| URL | /fmi/data/versione/databases/nome-database/globals
versione – versione di FileMaker Data API richiesta ( |
| Intestazione HTTP |
Content-Type: application/json Authorization: token-sessione di connessione, dove token-sessione è il valore X-FM-Data-Access-Token univoco per la sessione del database |
| Parametri | Un oggetto JSON con coppie campo-valore che specificano i campi globali da impostare. I campi globali devono essere specificati utilizzando nomi di campo completamente qualificati (nome tabella::nome campo). Ad esempio: { "globalFields":
{
"tabellaBase::gAzienda":"FileMaker",
"tabellaBase::gCodice":"95054"
}
}
|
| Risposta |
Un corpo della risposta vuoto e una matrice di messaggi con un codice di errore 0. Ad esempio: {
"response": {},
"messages":[{"code":"0","message":"OK"}]
}
|
Esecuzione di script FileMaker
FileMaker Data API può eseguire gli script FileMaker:
- utilizzando un metodo GET HTTP con endpoint API
script. Vedere Esecuzione di uno script. - come parte di un'altra richiesta includendo i parametri
script.prerequest,script.presortescriptnel corpo della richiesta. Vedere Esecuzione di uno script con un'altra richiesta.
Esecuzione di uno script
Per eseguire uno script FileMaker in modo indipendente, utilizzare un metodo GET HTTP con endpoint API script.
| Metodo HTTP | GET |
|---|---|
| URL | /fmi/data/versione/databases/nome-database/layouts/nome-formato/script/nome-script
versione – versione di FileMaker Data API richiesta ( |
| Intestazione HTTP | Content-Type: application/json |
| Parametri | script.param - stringa di testo da utilizzare come parametro per lo script riportato in nome-script. |
| Risposta |
Un corpo della risposta vuoto e una matrice di messaggi con un codice di errore 0. Ad esempio: {
"response": {},
"messages":[{"code":"0","message":"OK"}]
}
Vedere Risposte di errore. |
Note
- Quando si utilizza FileMaker Data API per eseguire uno script, assicurarsi che lo script abbia un nome univoco. Se vi sono più script con lo stesso nome, FileMaker Data API non può controllare quale script verrà richiamato, anche se gli script si trovano in cartelle diverse.
Esecuzione di uno script con un'altra richiesta
Per eseguire uno script FileMaker come parte di un'altra richiesta, includere i parametri script.prerequest, script.presort e script nel corpo della richiesta.
| Parametro | Valore |
|---|---|
script |
Il nome dello script da eseguire dopo l'azione specificata dalla chiamata API (ricava, crea, modifica, duplica, elimina, trova) e il successivo ordinamento. |
script.param |
La stringa di testo da utilizzare come parametro per lo script riportato in script. |
script.prerequest |
Il nome dello script da eseguire prima dell'azione specificata dalla chiamata API e il successivo ordinamento. |
script.prerequest.param |
La stringa di testo da utilizzare come parametro per lo script riportato in script.prerequest. |
script.presort |
Il nome dello script da eseguire dopo l'azione specificata dalla chiamata API, ma prima del successivo ordinamento. |
script.presort.param |
La stringa di testo da utilizzare come parametro per lo script riportato in script.presort. |
Ordine di esecuzione degli script
È possibile specificare i parametri script.prerequest, script.presort e script in una singola chiamata API. Ogni parola chiave può essere specificata solo una volta. L'host elabora questi parametri come parte della chiamata API nel seguente ordine:
- Andare al formato specificato nell'URL.
- Eseguire lo script riportato in
script.prerequest, se specificato. - Eseguire l'azione specificata dalla chiamata API (ricava, crea, modifica, duplica, elimina, trova).
- Eseguire lo script riportato in
script.presort, se specificato. - Eseguire l'ordinamento specificato nella chiamata API:
- Per ricavare una serie di record, eseguire l'ordinamento specificato dal parametro
_sort. - Per eseguire una richiesta di ricerca, eseguire l'ordinamento specificato dal parametro
sort.
- Per ricavare una serie di record, eseguire l'ordinamento specificato dal parametro
- Eseguire lo script riportato in
script, se specificato. - Restituire il gruppo di risultati per la chiamata API, con i parametri offset e limit applicati, se specificato.
Note
- Per le chiamate che utilizzano i metodi GET HTTP e DELETE HTTP, i parametri di script sono inclusi come parametri URL; vedere Ricavare un singolo record, Ricavare una serie di record ed Eliminare un record.
- Per le chiamate che utilizzano i metodi POST HTTP e PATCH HTTP, i parametri di script sono inclusi nel corpo della richiesta; vedere Creare un record, Modificare un record ed Eseguire una richiesta di ricerca.
- Per i parametri di script
script.param,script.prerequest.paramescript.presort.param, è possibile specificare solo una singola stringa di testo. Per trasferire più parametri, è possibile creare una stringa che delimita i parametri e fare in modo che lo script analizzi il singolo parametro. Ad esempio, trasferire "param1|param2|param3" come elenco con il carattere "|" con codifica URL:param1%7Cparam2%7Cparam3 - I risultati degli script vengono restituiti utilizzando i parametri
scriptResult,scriptResult.prerequestescriptResult.presortnei dati JSON. Gli errori degli script vengono restituiti utilizzando i parametriscriptError,scriptError.prerequestescriptError.presortnei dati JSON (gli errori degli script non vengono restituiti utilizzando un codice di stato HTTP).
Ad esempio:
https://<host>/fmi/data/v1/databases/clienti/layouts/inserimento/records/14?script=AggiornaElaborazione&script.param=14
Ad esempio:
{"query":[{"Titolo":"Responsabile ufficio"}], "script.prerequest":"Elimina duplicati"}
Risposte di errore
Quando si verifica un errore, FileMaker Data API restituisce:
- un codice di stato HTTP di categoria 4xx per errori HTTP standard
- un codice di stato HTTP di categoria 5xx per errori FileMaker
| Codice di stato HTTP | Categoria HTTP | Descrizione |
|---|---|---|
| 400 | Richiesta non valida | Si verifica quando il server non può elaborare la richiesta perché incompleta o non valida. |
| 401 | Non autorizzato | Si verifica quando il client non è autorizzato ad accedere all'API. Se questo errore si verifica quando si tenta di accedere alla sessione di un database, vi è un problema con l'account utente o la password specificati. Se questo errore si verifica con altre chiamate, il token di accesso non è specificato o non è valido. |
| 403 | Accesso negato | Si verifica quando il client è autorizzato, ma la chiamata tenta un'azione vietata per un motivo diverso. |
| 404 | Pagina non trovata | Si verifica se la chiamata utilizza un URL con uno schema non valido. Verificare eventuali errori di sintassi nell'URL specificato. |
| 405 | Metodo non consentito | Si verifica quando viene utilizzato un metodo HTTP non corretto con una chiamata. |
| 415 | Tipo di media non supportato | Si verifica se l'intestazione richiesta manca o non è corretta per la richiesta:
|
| 500 | Errore FileMaker | Include messaggi e codici di errore di FileMaker. Vedere Codici di errore di FileMaker nella Guida di FileMaker Pro Advanced. |
Note
- Se il Motore di FileMaker Data API non è in esecuzione o non è raggiungibile, i messaggi o i codici di errore restituiti variano in base al server Web (Apache o IIS).
- Per informazioni su altri codici di stato HTTP restituiti, vedere www.w3.org.
Ospitare, testare e monitorare le soluzioni FileMaker Data API
Ospitare una soluzione FileMaker Data API
- Completare tutti i passi in Preparare i database per l'accesso tramite FileMaker Data API.
- Verificare che l'accesso tramite FileMaker Data API sia stato abilitato e configurato correttamente nell'Admin Console. Visitare il centro documentazione prodotto.
- Verificare che il server Web e il Motore di FileMaker Data API siano in esecuzione.
-
Utilizzare la crittografia per la comunicazione.
FileMaker Data API richiede alle applicazioni API REST di utilizzare una connessione HTTPS. Le connessioni HTTPS utilizzano la crittografia SSL (Secure Sockets Layer) per la comunicazione.
FileMaker Server fornisce un certificato SSL standard firmato da FileMaker, Inc. che non verifica il nome del server. Il certificato predefinito di FileMaker è destinato solo ai test. Per l'uso in un ambiente di produzione è richiesto un certificato SSL personalizzato. Vedere la Guida all'installazione e alla configurazione di FileMaker Server.
La lingua o la tecnologia utilizzate per chiamare FileMaker Data API devono supportare il protocollo TLS (Transport Layer Security) v1.2 per comunicare con il server Web.
Testare una soluzione FileMaker Data API
Prima della messa in produzione, verificare che la soluzione FileMaker Data API funzioni nel modo previsto.
- Testare le funzioni come ad esempio la ricerca, l'aggiunta e l'eliminazione dei record con account e set di privilegi diversi.
- Verificare che i set di privilegi funzionino come previsto testandoli con account diversi. Assicurarsi che gli utenti non autorizzati non possano accedere ai dati né modificarli.
- Verificare che la soluzione si comporti allo stesso modo quando richiamata da sistemi operativi diversi.
Monitorare le soluzioni FileMaker Data API
L'amministratore server può utilizzare l'Admin Console per avviare o arrestare il Motore di FileMaker Data API, monitorare i client FileMaker Data API, tenere traccia dell'utilizzo delle chiamate FileMaker Data API e scaricare il file di registro di FileMaker Data API.
| Per | Utilizzare |
|---|---|
| Avviare o arrestare il Motore di FileMaker Data API |
Connettori > scheda FileMaker Data API nell'Admin Console. Vedere "Avvio o arresto dei componenti di FileMaker Server" nella Guida di FileMaker Server o la documentazione dei prodotti FileMaker Cloud nel centro documentazione prodotto. Con FileMaker Server, è possibile utilizzare anche un comando CLI. Vedere la Guida CLI. |
| Monitorare i client FileMaker Data API |
L'elenco dei client nella pagina Database dell'Admin Console. Questa pagina mostra informazioni dettagliate sui client e sui database ai quali si accede. In questa pagina, è possibile disconnettere i client FileMaker Data API, ma non inviare loro dei messaggi. Vedere "Amministrazione dei client" nella Guida di FileMaker Server o la documentazione dei prodotti FileMaker Cloud nel centro documentazione prodotto. |
| Tenere traccia dell'utilizzo delle chiamate FileMaker Data API |
Connettori > scheda FileMaker Data API nell'Admin Console. Questa scheda visualizza il limite annuale FileMaker Data API stabilito dalla licenza, la quantità di dati trasmessa dalla data di azzeramento annuale precedente e la data di azzeramento annuale della licenza.
|
| Visualizzare il registro di FileMaker Data API |
Quando i client FileMaker Data API sono collegati a un database, i relativi dati statistici vengono registrati nel file fmdapi.log. Vedere "Registro di FileMaker Data API" nella Guida di FileMaker Server o la documentazione dei prodotti FileMaker Cloud nel centro documentazione prodotto. |
Integrazione di FileMaker Data API con Tableau
Informazioni sull'integrazione con Tableau
Utilizzare un Web Data Connector per definire una connessione tra un database FileMaker ospitato e Tableau. Il Web Data Connector è un'implementazione di esempio che accetta chiamate API REST in formato JSON. La connessione utilizza FileMaker Data API per importare in Tableau i dati di un database FileMaker ospitato.
Utilizzare FileMaker Server o un prodotto FileMaker Cloud per ospitare il database FileMaker. Questi host possono integrarsi con i seguenti prodotti Tableau:
Tableau Desktop, versione minima 10, per Windows o macOS. Utilizzare Web Data Connector per FileMaker di Tableau Desktop per definire una connessione a Tableau Desktop.
Tableau Server, installato in locale o ospitato dal cliente. Ospitare Web Data Connector per FileMaker di Tableau Server su Tableau Server.
Tableau Cloud. Eseguire un'istanza Tableau Server locale per trasmettere tramite proxy i dati a Tableau Cloud. Ospitare Web Data Connector per FileMaker di Tableau Server su Tableau Server.
Tableau Online. Richiede l'uso di Tableau Bridge.
Requisiti per il Web Data Connector
Web Data Connector per FileMaker di Tableau richiede:
- Un database FileMaker Pro Advanced protetto da password contenente i dati da importare. Il database deve essere ospitato su FileMaker Server o un prodotto FileMaker Cloud. FileMaker Server e FileMaker Cloud for AWS supportano l'autenticazione tramite File FileMaker e OAuth. FileMaker Cloud richiede l'autenticazione tramite ID FileMaker.
-
Un endpoint API REST valido.
Con FileMaker Server, l'endpoint è un punto di connessione HTML che fornisce le informazioni necessarie per i servizi Web. Il formato dell'endpoint è
https://<nomehost>/fmi/data/versione/tableau/fm_connector.html
dovenomehostè il nome host completamente qualificato di FileMaker Server.Ad esempio:
https://mioserver.miaazienda.com/fmi/data/v1/tableau/fm_connector.html Un certificato SSL personalizzato valido sull'host. Web Data Connector per FileMaker di Tableau non consentirà l'importazione dei dati senza un certificato SSL personalizzato valido.
Nota:se l'host utilizza un certificato con nome alternativo del soggetto (SAN), il nome host deve corrispondere al nome comune utilizzato nel certificato SAN.
Prepararsi all'importazione dei dati in Tableau
Seguire i passi in Preparare i database per l'accesso tramite FileMaker Data API per definire il formato per l'importazione e abilitare il database per l'accesso tramite FileMaker Data API.
Nota:per importare i dati in Tableau, la tabella deve contenere almeno un record con relativi dati.
I seguenti tipi di campo FileMaker vengono importati come tipi di dati Tableau.
| Tipo di campo FileMaker | Tipo di dati Tableau |
|---|---|
| Testo | string |
| Data | date |
| Ora | string |
| Indicatore data e ora | datetime |
| Numero | float |
I seguenti tipi di campo FileMaker non sono supportati nell'importazione in Tableau:
- Campi Contenitore.
- Campi Riassunto. È possibile creare un campo Riassunto in Tableau sulla base dei dati importati da FileMaker.
- Campi Calcolo. È possibile creare un campo Calcolo in Tableau sulla base dei dati importati da FileMaker.
- Dati dei grafici.
- Dati dei portali FileMaker Pro Advanced. Per importare i dati di record correlati, creare un formato in FileMaker Pro Advanced basato sulla tabella correlata o importare in Tableau i dati di tabelle separate di FileMaker Pro Advanced, quindi collegare queste ultime in Tableau.
- Ripetizioni di campo in cui la visualizzazione di campi multipli per Mostra ripetizioni include valori multipli. Una singola ripetizione è supportata.
- Valori non numerici nei campi Numero. Se Tableau trova valori non numerici nei campi Numero, i dati non verranno importati.
Non utilizzare parole riservate come nomi dei campi in FileMaker Pro Advanced.
Configurare la connessione dati in Tableau
Nella Guida in linea del prodotto Tableau, seguire le istruzioni che descrivono come utilizzare i Web Data Connector.
Ad esempio, per configurare la connessione dati con Web Data Connector per FileMaker Server di Tableau Desktop:
- In Tableau Desktop, sotto Connect (a sinistra nella schermata), selezionare More > Web Data Connector.
- Inserire l'URL per l'endpoint FileMaker Server
https://<nomehost>/fmi/data/v1/tableau/fm_connector.html
dove<nomehost>è il nome host completamente qualificato di FileMaker Server. -
Nella finestra di dialogo Importazione dei dati da file FileMaker:
-
Accedere al database FileMaker Pro Advanced inserendo le seguenti informazioni o utilizzando un provider di identità OAuth.
- Nome database origine: il nome del database FileMaker Pro Advanced
- Nome formato origine: il nome del formato FileMaker Pro Advanced
- Nome account: il nome dell'account FileMaker Pro Advanced con privilegio fmrest
- Password: la password per l'account FileMaker Pro Advanced
- Selezionare Abilita aggiornamento incrementale per abilitare l'aggiornamento incrementale.
-
- Fare clic su Importa dati FileMaker.
Tableau importa i dati. Il tempo di elaborazione varia in base al numero di record importati, al carico del server e al throughput di rete. Tableau associa dati e nomi dei campi di FileMaker Pro Advanced a dimensioni e misure. In genere le stringhe di dati sono associate a dimensioni, mentre i dati numerici sono associati a misure. La mappatura avviene automaticamente durante l'importazione, ma è possibile personalizzarla.
Note
-
Quando si specifica Nome formato origine, assicurarsi che il nome del formato sia univoco. Se il database ha due formati con lo stesso nome, la connessione dati Tableau non riesce a distinguerli. Tableau visualizza solo un nome che potrebbe non corrispondere a quello del formato desiderato.
- Quando si configura la connessione dati in Tableau, non selezionare l'opzione per richiedere l'autenticazione dell'utente.
-
Utilizzare Abilita aggiornamento incrementale per importare solo i record nuovi.
- Dopo aver importato i dati FileMaker con aggiornamento incrementale abilitato, selezionare la scheda Sheet in Tableau per andare al foglio di lavoro.
- Selezionare Data > FM: nome-database / nome-formato > Extract > Refresh (Incremental).
- Selezionare la scheda Data Source.
- Fare clic su Update Now per visualizzare i nuovi record.
- L'abilitazione dell'aggiornamento incrementale non crea una connessione live costante tra Tableau e il database FileMaker ospitato. È necessario eseguire manualmente l'aggiornamento incrementale.
- L'aggiornamento incrementale importa solo i record nuovi. I record di FileMaker Pro Advanced che sono stati modificati o eliminati non vengono aggiornati. Per ricavare i dati modificati o per rimuovere i record eliminati, è necessario creare una nuova cartella di lavoro in Tableau e reimportare i dati.
- L'aggiornamento incrementale crea un campo -idRecord. Se si apportano modifiche a questo campo, si potrebbe non essere in grado di eseguire un aggiornamento incrementale.
- In Tableau, è possibile modificare lo schema e i dati importati. Ma se si modificano lo schema o i dati in Tableau, queste modifiche non vengono ritrasmesse al file FileMaker Pro Advanced.
- Se si modifica lo schema nel file FileMaker Pro Advanced, è necessario creare una nuova cartella di lavoro in Tableau e reimportare i dati.
- Se si chiude la cartella di lavoro in Tableau e la si riapre, l'importazione incrementale non è più abilitata.
- Dopo aver stabilito la connessione dati a Tableau, Web Data Connector per FileMaker memorizza account utente e password nella cache fino a quando la cartella di lavoro non verrà chiusa, tenendo presente le seguenti considerazioni:
- Se la sessione FileMaker scade mentre si è connessi a Tableau, Web Data Connector per FileMaker tenta di riconnettere l'utente al database ospitato.
- Se la connessione a Tableau scade, Web Data Connector per FileMaker tenta di riconnettersi al database ospitato finché la cartella di lavoro in Tableau è aperta.
- Se il token di aggiornamento di Tableau scade, è necessario ripubblicare l'origine dati in Tableau Desktop.
- Se la cartella di lavoro viene chiusa e poi riaperta, è necessario inserire nuovamente nome account e password durante l'importazione iniziale dei dati.
- La pagina Data Source di Tableau visualizza fino a 1.000.000 (un milione) di righe, anche se si importano più record.
- L'utilizzo di caratteri speciali nei nomi di database, tabelle o formati potrebbe impedire a Tableau di stabilire una connessione dati.