Guida di FileMaker Data API 16
Informazioni su FileMaker Data API
Panoramica
FileMaker® Data API è un'Application Programming Interface (API) che permette ai servizi Web di accedere ai dati nelle soluzioni ospitate. Poiché questa API utilizza l'architettura REST (REpresentational State Transfer), FileMaker Data API è un'API REST.
Il servizio Web o l'applicazione chiamano FileMaker Data API per ottenere un token di autenticazione per accedere a una soluzione ospitata, 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 per creare i database. È necessario comprendere le nozioni di base sulla progettazione dei database di FileMaker Pro e i concetti di campo, relazione, formato, portale e contenitore. Vedere la Guida di FileMaker Pro.
- utilizzo di FileMaker Server per ospitare le soluzioni. È necessario comprendere come distribuire FileMaker Server, come consentire l'accesso alle soluzioni ospitate e come monitorare le soluzioni ospitate utilizzando la FileMaker Server Admin Console. Vedere la Guida di FileMaker Server.
- utilizzo di API REST in applicazioni lato server o servizi Web che chiamano i metodi POST, GET, PUT e DELETE con dati in formato JSON. È possibile utilizzare qualsiasi linguaggio o strumento di programmazione desiderato.
Per utilizzare FileMaker Data API, procedere come segue:
- Preparare il database per l'accesso tramite FileMaker Data API utilizzando FileMaker Pro. È possibile creare un database o prepararne uno esistente. Vedere Preparare i database per l'accesso tramite FileMaker Data API.
- Scrivere il codice per chiamare i metodi di FileMaker Data API per cercare, creare, modificare ed eliminare i record in una soluzione ospitata. Vedere Scrivere le chiamate FileMaker Data API.
- Ospitare la soluzione utilizzando FileMaker Server 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 FileMaker Server attraverso la porta HTTPS. Non è necessario che FileMaker Pro sia installato o in esecuzione.
La porta HTTPS predefinita è la 443, ma l'amministratore server può specificare una porta diversa con l'installazione di FileMaker Server.
- 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 dalla soluzione ospitata 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 alla soluzione ospitata su FileMaker Server 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. Le pagine Web e i moduli con cui l'utente Web interagisce dipendono dai formati e dalle visualizzazioni definiti nel database FileMaker Pro.
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 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 collegano al database.
Vedere Pubblicazione di dati su pagine Web statiche nella Guida di FileMaker Pro.
Pubblicazione Web personalizzata: per integrare il database FileMaker con un sito Web personalizzato, utilizzare le tecnologie di Pubblicazione Web personalizzata.
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 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.
Le chiamate FileMaker Data API che accedono ai dati dei record 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 non sarà in grado di ricavare i dati dei record correlati.
Proteggere le soluzioni ospitate
FileMaker Data API richiede al codice API REST di accedere a una soluzione 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.
Nota: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.
Consentire l'accesso tramite FileMaker Data API
È necessario attivare il privilegio esteso Accesso attraverso FileMaker Data API in ciascun database a cui si desidera accedere utilizzando FileMaker Data API. Se non si attiva il privilegio esteso per FileMaker Data API nel database, le applicazioni API REST non saranno in grado di utilizzare FileMaker Data API per accedere al database, anche se questo è ospitato da FileMaker Server.
Per consentire l'accesso tramite FileMaker Data API per un database:
- In FileMaker Pro, aprire il database utilizzando un account con set di privilegi Accesso completo. In alternativa, si può aprire il database utilizzando un account che dispone dei privilegi di accesso Gestisci privilegi estesi.
- Nella scheda Privilegi estesi della finestra di dialogo Gestisci sicurezza, selezionare il privilegio esteso fmrest per attivarlo.
- Assegnare i set di privilegi con privilegio esteso fmrest a uno o più account.
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 alla soluzione ospitata.
Vedere Creazione e modifica dei set di privilegi nella Guida di FileMaker Pro.
Scrivere le chiamate FileMaker Data API
Funzioni di FileMaker Data API
FileMaker Data API fornisce un'API REST per accedere ai dati nelle soluzioni ospitate. FileMaker Data API permette al codice di:
- accedere o disconnettersi da una soluzione ospitata. Vedere Chiamate che accedono o si disconnettono da un database.
- creare, modificare, eliminare o ricavare un record; oppure ricavare una serie di record. Vedere Chiamate che lavorano con i record.
- eseguire richieste di ricerca. Vedere Chiamate che eseguono richieste di ricerca.
- impostare valori di campi globali. Vedere Chiamate che impostano valori di campi globali.
FileMaker Data API non supporta:
- caricamento dei dati nei campi Contenitore
- accesso ai dati nelle origini dati ODBC esterne
- plug-in FileMaker
- esecuzione degli script FileMaker
- attivazione dei trigger di script
FileMaker Data API restituisce i dati dei campi così come memorizzati nel database, non come visualizzati in FileMaker Pro.
Informazioni sul riferimento di FileMaker Data API
Installando FileMaker Server, si sono installati i file del riferimento di FileMaker Data API. Questo riferimento fornisce informazioni dettagliate su tutte le chiamate supportate da FileMaker Data API.
- Per visualizzare il riferimento in una finestra del browser sulla macchina master, inserire l'URL
https://hostlocale/fmi/rest/apidoc/ - Per visualizzare il riferimento in una finestra del browser su una macchina remota, inserire l'URL
https://host/fmi/rest/apidoc/
dovehostè l'indirizzo IP o il nome host della macchina master su cui è in esecuzione FileMaker Server. 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
[posizione_installazione]:\Documentation\Data API Documentation- Su un server macOS, i file del riferimento si trovano nella cartella
/Libreria/FileMaker Server/Documentation/Data API Documentation
Note sul formato dati
- Tutti i valori dei dati 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 campi e i portali specificati devono trovarsi nel formato specificato.
- Per specificare campi correlati, è necessario utilizzare la sintassi
nometabella::campo-correlato - Per utilizzare ripetizioni di campo pari o superiori a 2, è necessario utilizzare la sintassi
nometabella::campo-correlato(numero-ripetizione) - Quando si modificano i record, è necessario utilizzare la sintassi per l'ID del record
nometabella::campo-correlato(numero-ripetizione).id-record - Per i dati dei campi Contenitore, FileMaker Data API restituisce un URL con il percorso dell'oggetto dati Contenitore.
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:
|
Un'intestazione HTTP |
FileMaker Data API utilizza le seguenti intestazioni:
|
| Un URL di chiamata | Gli URL di FileMaker Data API iniziano tutti con: /fmi/rest/api/ |
| Dati dei parametri in formato JSON | Non necessari per disconnettersi da una soluzione, eliminare un record, ricavare un singolo record o ricavare una serie di record |
Chiamate che accedono o si disconnettono 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 la soluzione ospitata. Il token di accesso è valido fino alla disconnessione da una soluzione 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 a una soluzione
Per accedere a una soluzione ospitata, utilizzare un metodo POST HTTP con URL auth specificando il nome di una soluzione ospitata.
Se nome account e password vengono autenticati, il codice riceve un token di accesso che definisce la connessione alla soluzione.
| Metodo HTTP | POST |
|---|---|
| URL | /fmi/rest/api/auth/soluzione soluzione – nome del database ospitato |
| Intestazione HTTP | Content-Type: application/json |
| Parametri | Il nome account e la password per accedere alla soluzione ospitata e il formato a cui passare dopo aver eseguito l'accesso, in formato JSON. Ad esempio: {
"user":"admin",
"password":"admin",
"layout":"Attività"
} |
| Risposta | Il token di accesso, il formato corrente e un codice di errore 0. Ad esempio: {
"errorCode": "0",
"layout": "Attività",
"token": "fdde29fa175eb1cc8347512ca327b191619fc32ed65efaab26d8"
}
Vedere Risposte di errore. |
Accedere a una soluzione utilizzando un provider di identità OAuth
Per accedere a una soluzione ospitata, utilizzare un metodo POST HTTP con URL auth specificando il nome di una soluzione ospitata.
Se nome account e password vengono autenticati, il codice riceve un token di accesso che definisce la connessione alla soluzione.
| Metodo HTTP | POST |
|---|---|
| URL | /fmi/rest/api/auth/soluzione soluzione – nome del database ospitato |
| Intestazione HTTP | Content-Type: application/json X-FM-Data-Login-Type: oauth |
| Parametri | L'ID della richiesta OAuth (contenente l'URL di callback per l'autenticazione), l'identificativo OAuth restituito dal provider di identità OAuth e il formato a cui passare dopo aver eseguito l'accesso. Tutti i dati devono essere in formato JSON. Ad esempio: {
"oAuthRequestId":"E65B98CC17429CO643A31119F",
"oAuthIdentifier":"B164A4629A776E5177445DR223",
"layout":"Contatti"
} |
| Risposta | Il token di accesso, il formato corrente e un codice di errore 0. Ad esempio: {
"errorCode": "0",
"layout": "Contatti",
"token": "fdde35fa175eb1cc8621782fd327b191619fc32ed65efaab26d8"
}
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. L'elenco viene restituito in formato JSON.
- Selezionare un provider OAuth supportato e ricavare un ID di monitoraggio per la soluzione.
-
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, ID-monitoraggio è l'ID di monitoraggio generato dallo sviluppatore per la soluzione 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 eseguire l'accesso.
- 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 eseguire l'accesso.
Vedere Creazione di account che eseguono l'autenticazione tramite un provider di identità OAuth nella Guida di FileMaker Pro.
Disconnettersi da una soluzione
Quando il codice termina l'accesso alla soluzione ospitata, utilizzare un metodo DELETE HTTP con URL auth specificando il nome della soluzione ospitata.
Il token della sessione viene inviato nell'intestazione di richiesta.
Se il codice non esegue la disconnessione dalla soluzione ospitata, 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/rest/api/auth/soluzione soluzione – nome del database ospitato |
| Intestazione HTTP | FM-Data-token che specifica il token di accesso restituito alla chiamata che ha eseguito l'accesso alla soluzione |
| Parametri | Nessuno |
| Risposta | Un codice di errore 0. Ad esempio: {
"errorCode": "0"
}
Vedere Risposte di errore. |
Chiamate che lavorano con i record
Creare un record
Per creare un record, utilizzare un metodo POST HTTP con URL record specificando il nome della soluzione e il formato.
| Metodo HTTP | POST |
|---|---|
| URL | /fmi/rest/api/record/soluzione/formato soluzione – nome del database ospitato |
| Intestazione HTTP | Content-Type: application/json FM-Data-token che specifica il token di accesso restituito alla chiamata che ha eseguito l'accesso alla soluzione |
| 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. Ad esempio: {"data":
{
"campo_1": "valore_1",
"campo_2": "valore_2",
"campoRipetizione(1)" : "valoreCampo",
"Ordini::DataOrdine.0":"12/22/2015"
}
}
Nota:per creare un record vuoto con valori predefiniti per ciascun campo, specificare un oggetto dati vuoto in formato JSON come parametro. Ad esempio: {"data":
{
}
} |
| Risposta | Un codice di errore 0 e l'ID del record creato. Ad esempio: {
"errorCode": "0",
"recordId": "25"
}
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.
-
Per creare un record correlato, omettere l'ID del record o utilizzare il valore 0 (zero) come ID del record correlato seguito dal nuovo valore del campo.
Ad esempio, utilizzare uno dei seguenti metodi per creare un record correlato:
"Ordini::DataOrdine" : "12/22/2017" "Ordini::DataOrdine.0" : "12/22/2017"È possibile creare solo un record correlato per chiamata.
Modificare un record
Per modificare un record, utilizzare un metodo PUT HTTP con URL record specificando il nome della soluzione, il formato e l'ID del record.
| Metodo HTTP | PUT |
|---|---|
| URL | /fmi/rest/api/record/soluzione/formato/idrecord soluzione – nome del database ospitato |
| Intestazione HTTP | Content-Type: application/json FM-Data-token che specifica il token di accesso restituito alla chiamata che ha eseguito l'accesso alla soluzione |
| 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. Vengono aggiornati solo i campi specificati; gli altri campi nel record non vengono modificati. Se come valore dei dati viene specificato "{}", il record di destinazione non verrà aggiornato. Parametro facoltativo: ID di modifica. Specificando un ID di modifica, si è sicuri di modificare la versione corrente di un record. Se il valore dell'ID di modifica non corrisponde al valore dell'ID di modifica corrente nel database, il record non viene modificato. Ad esempio: {"data":
{
"nome": "Mario",
"cognome": "Rossi",
"apparecchiatura(2)" : "PC",
"Ordini::DataOrdine.2":"12/20/2017",
"Ordini::DataOrdine.0":"12/22/2017", // creare un record "Ordini" correlato con 0 come recordId
"deleteRelated": "Ordini.3" // eliminare un record "Ordini" correlato con la stringa "deleteRelated"
},
modId: "3"
} |
| Risposta | Un codice di errore 0 e l'ID del record modificato. Ad esempio: {
"errorCode": "0",
"recordId": "53"
}
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 creare un record correlato, omettere l'ID del record o utilizzare il valore 0 (zero) come ID del record correlato seguito dal nuovo valore del campo.
Ad esempio, utilizzare uno dei seguenti metodi per creare un record correlato:
"Ordini::DataOrdine" : "12/22/2017" "Ordini::DataOrdine.0" : "12/22/2017"È possibile creare solo un record correlato per chiamata. -
Per eliminare un record correlato, utilizzare la stringa "deleteRelated" seguita dal record correlato da eliminare.
Ad esempio:
"deleteRelated" : "Ordini.3"È possibile eliminare solo un record correlato per chiamata.
Eliminare un record
Per eliminare un record, utilizzare un metodo DELETE HTTP con URL record specificando il nome della soluzione, il formato e l'ID del record.
| Metodo HTTP | DELETE |
|---|---|
| URL | /fmi/rest/api/record/soluzione/formato/idrecord soluzione – nome del database ospitato |
| Intestazione HTTP | FM-Data-token che specifica il token di accesso restituito alla chiamata che ha eseguito l'accesso alla soluzione |
| Parametri | Nessuno |
| Risposta | Un codice di errore 0. Ad esempio: {
"errorCode": "0"
}
Vedere Risposte di errore. |
Ricavare un singolo record
Per ricavare un record, utilizzare un metodo GET HTTP con URL record specificando il nome della soluzione, 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/rest/api/record/soluzione/formato/idrecord soluzione – nome del database ospitato 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. |
| Intestazione HTTP | FM-Data-token che specifica il token di accesso restituito alla chiamata che ha eseguito l'accesso alla soluzione |
| Parametri | Nessuno |
| Risposta | Un codice di errore 0 e i dati del record in formato JSON. Ad esempio: {
"errorCode": "0",
"record": "{...}"
}
Vedere Risposte di errore. |
Note
- Per limitare il numero di record correlati restituiti, FileMaker Data API supporta l'opzione Consenti scorrimento verticale nella finestra di dialogo Impostazione portale. Se questa opzione è selezionata, FileMaker Data API restituisce le prime 50 righe del portale. Se questa opzione non è selezionata, FileMaker Data API restituisce il numero di righe specificato per l'opzione Numero di righe.
- Per scorrere le righe del portale, utilizzare la sintassi
offset.<nome-portale>erange.<nome-portale>, dove<nome-portale>è il valore specificato per il portale nella finestra Impostazioni di FileMaker Pro. Se non si specificano i valori offset e range per le righe del portale, i valori predefiniti per offset e range sono rispettivamente 1 e 50.
Ricavare una serie di record
Per ricavare una serie di record, utilizzare un metodo GET HTTP con URL record specificando il nome della soluzione, 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:
/fmi/rest/api/record/soluzione/formato?offset=record-iniziale&range=numero-di-record soluzione – nome del database ospitato Per il criterio di ordinamento, l'informazione deve essere specificata in formato JSON. nome-campo è il nome di un campo da utilizzare come base per l'ordinamento dei record. È possibile specificare più nomi di campo. Per il criterio di ordinamento, specificare la parola chiave "ascend" o "descend" oppure specificare il nome di una lista valori per nome-lista-valori. 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. |
| Intestazione HTTP | FM-Data-token che specifica il token di accesso restituito alla chiamata che ha eseguito l'accesso alla soluzione |
| Parametri | Nessuno |
| Risposta | Un codice di errore 0 e i dati della serie di record in formato JSON. Ad esempio: {
"errorCode": "0",
"records": "[...]"
}
Vedere Risposte di errore. |
Note
- Se non si specificano i valori offset e range, i valori predefiniti per offset e range sono rispettivamente 1 e 100:
offset=1&range=100 - Se non si specificano i valori per il criterio di ordinamento, i valori predefiniti sono
&sort=[{ "fieldName": "idRecord", "sortOrder": "ascend" }] - Per limitare il numero di record correlati restituiti, FileMaker Data API supporta l'opzione Consenti scorrimento verticale nella finestra di dialogo Impostazione portale. Se questa opzione è selezionata, FileMaker Data API restituisce le prime 50 righe del portale. Se questa opzione non è selezionata, FileMaker Data API restituisce il numero di righe specificato per l'opzione Numero di righe.
- Per scorrere le righe del portale, utilizzare la sintassi
offset.<nome-portale>erange.<nome-portale>, dove<nome-portale>è il valore specificato per il portale nella finestra Impostazioni di FileMaker Pro. Se non si specificano i valori offset e range per le righe del portale, i valori predefiniti per offset e range sono rispettivamente 1 e 50.
Chiamate che eseguono richieste di ricerca
Per eseguire una richiesta di ricerca, utilizzare un metodo POST HTTP con URL find specificando il nome della soluzione, 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 trovare record correlati.
| Metodo HTTP | POST |
|---|---|
| URL | /fmi/rest/api/find/soluzione/formato soluzione – nome del database ospitato |
| Intestazione HTTP | FM-Data-token che specifica il token di accesso restituito alla chiamata che ha eseguito l'accesso alla soluzione |
| 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 (range) e portali per limitare il numero di record correlati restituiti. Ad esempio: {
"query":[
{"Group": "=Chirurgo", "Lavoro - Regione" : "Lazio"},
{"Group": "=Chirurgo", "Lavoro - Città" : "Roma", "omit" : "true"}],
"sort":[
{"fieldName": "Lavoro - Regione", "sortOrder": "ascend"},
{"fieldName": "Nome", "sortOrder": "ascend"} ]
}
Esempio con parametri offset, range e portal: {
"query":[
{"Group": "=Chirurgo", "Lavoro - Regione" : "Lazio"},
{"Group": "=Chirurgo", "Lavoro - Città" : "Roma", "omit" : "true"}],
"portal": ["Portale1","Portale2"],
"range": "10",
"offset": "1",
"offset.Portal1": "1",
"range.Portal1": "5"
} |
| Risposta | Un codice di errore 0 e la rappresentazione JSON del gruppo trovato. Ad esempio: {
"errorCode": "0",
"data": [record1, record2, ...]
}
Vedere Risposte di errore. |
Note
- In una soluzione con molti record correlati, l'interrogazione e l'ordinamento dei record del portale potrebbe richiedere molto tempo. Per limitare il numero di record e righe da visualizzare in un gruppo correlato, specificare i parametri offset e range.
- 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 Chiamate che impostano valori di campi globali.
Chiamate che impostano valori di campi globali
Per impostare i valori per i campi globali, utilizzare un metodo PUT HTTP con URL global specificando il nome della soluzione e il formato.
| Metodo HTTP | PUT |
|---|---|
| URL | /fmi/rest/api/global/soluzione/formato/ soluzione – nome del database ospitato |
| Intestazione HTTP | FM-Data-token che specifica il token di accesso restituito alla chiamata che ha eseguito l'accesso alla soluzione |
| Parametri | Un oggetto JSON con coppie campo-valore che specificano i campi globali da impostare. Ad esempio: { "globalFields":
{
"gAzienda":"FileMaker",
"gCodice":"95054"
}
} |
| Risposta | Un codice di errore 0. Ad esempio: {
"errorCode": "0"
}
Vedere Risposte di errore. |
Risposte di errore
In genere, quando si verifica un errore, FileMaker Data API restituisce un codice di stato HTTP di categoria 4xx con informazioni aggiuntive in un oggetto JSON.
| Codice di stato HTTP | Categoria HTTP | Formato dell'errore JSON | Descrizione |
|---|---|---|---|
| 400 | Richiesta non valida | {
"errorMessage": "dettagli errore"
} |
Si verifica quando il server non può elaborare la richiesta a causa di un errore client. |
| 401 | Non autorizzato | {
"errorMessage": "Non autorizzato"
} |
Si verifica quando il client non è autorizzato ad accedere all'API. Se questo errore si verifica quando si tenta di accedere a una soluzione ospitata, 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. |
| 404 | Pagina non trovata | {
"errorMessage": "Pagina non trovata"
} |
Si verifica se la chiamata utilizza un URL con uno schema non valido. Verificare eventuali errori di sintassi nell'URL specificato. |
| 415 | Tipo di supporto non supportato | {
"errorMessage": "Tipo di supporto non supportato"
} |
Si verifica se l'intestazione "Content/Type: application/json" non è specificata o se è stato specificato un tipo di contenuto diverso da "application/json". |
| 477 | Errore servizio FileMaker | {
"errorMessage": "Messaggio di errore di FileMaker",
"errorCode": "Codice di errore di FileMaker"
} |
Include messaggi e codici di errore di FileMaker. Vedere Codici di errore di FileMaker nella Guida di FileMaker Pro. |
Note
- Se il Motore di FileMaker Data API non è in esecuzione o non è raggiungibile, può essere restituito il codice di stato 0 (zero) senza un messaggio di errore.
- 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 nella FileMaker Server Admin Console. Vedere la Guida di FileMaker Server.
- Verificare che il server Web, il Motore per la Pubblicazione 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, modificare le impostazioni di FileMaker Data API, monitorare i client FileMaker Data API, tenere traccia dell'utilizzo delle chiamate FileMaker Data API e visualizzare il file di registro di FileMaker Data API.
| Per | Utilizzare |
|---|---|
| Avviare o arrestare il Motore di FileMaker Data API | Riquadro Stato nell'Admin Console o un comando CLI. Vedere Avvio o arresto dei componenti di FileMaker Server e Utilizzo dell'interfaccia a riga di comando nella Guida di FileMaker Server. |
| Modificare le impostazioni di FileMaker Data API | Pubblicazione Web > scheda FileMaker Data API nell'Admin Console. In questa scheda, consentire l'utilizzo di FileMaker Data API, consentire la registrazione delle chiamate FileMaker Data API, impostare le dimensioni massime per il file di registro di FileMaker Data API e impostare il livello di registrazione per i messaggi scritti sul file di registro. Vedere Impostazioni di FileMaker Data API nella Guida di FileMaker Server. |
| Monitorare i client FileMaker Data API | Attività > scheda Client nell'Admin Console. Questa scheda mostra informazioni dettagliate sul client e sulle soluzioni alle quali si accede. Vedere Amministrazione dei client nella Guida di FileMaker Server. In questa scheda, è possibile disconnettere i client FileMaker Data API, ma non inviare loro dei messaggi. Quando i client FileMaker Data API sono collegati a una soluzione, in Statistiche > scheda Client nell'Admin Console vengono visualizzati i dati statistici relativi ai client. Vedere Visualizzazione delle statistiche sui client nella Guida di FileMaker Server. |
| Tenere traccia dell'utilizzo delle chiamate FileMaker Data API | Pubblicazione Web > scheda FileMaker Data API nell'Admin Console. Questa scheda visualizza il numero di chiamate FileMaker Data API consentite dalla licenza FileMaker Server, il numero di chiamate utilizzate nel mese corrente e il numero di chiamate utilizzate nel mese precedente. Se si sta raggiungendo il limite di chiamate, è anche possibile acquistare più chiamate utilizzando questa scheda. Vedere Impostazioni di FileMaker Data API nella Guida di FileMaker Server. |
| Visualizzare il registro di FileMaker Data API | Scheda Visualizzatore registro nell'Admin Console. I componenti di FileMaker Data API generano informazioni di registro relative ai client che accedono a soluzioni ospitate tramite FileMaker Data API. Vedere Registro di FileMaker Data API nella Guida di FileMaker Server. |
Integrazione di FileMaker Data API con Tableau
Informazioni sull'integrazione con Tableau
FileMaker Server include Tableau Web Data Connector, un'implementazione di esempio che accetta chiamate API REST in formato JSON. Utilizzare Tableau Web Data Connector per definire una connessione tra FileMaker Server e Tableau Desktop. La connessione utilizza FileMaker Data API per importare in Tableau Desktop i dati di soluzioni FileMaker ospitate.
Requisiti per Tableau Web Data Connector
- Tableau Desktop, versione minima 9.1, per Windows o Mac.
- Un database FileMaker Pro protetto da password contenente i dati da importare. Il database deve essere ospitato su FileMaker Server.
-
Un endpoint API REST valido. Per 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/rest/tableau/fm_connector.html
dovenomehostè il nome host completamente qualificato di FileMaker Server.Ad esempio:
https://mioserver.miaazienda.com/fmi/rest/tableau/fm_connector.html - Un certificato SSL personalizzato valido su FileMaker Server. Tableau Web Data Connector non consentirà l'importazione dei dati da FileMaker Server senza un certificato SSL personalizzato valido.
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. Per importare i dati di record correlati, creare un formato in FileMaker Pro basato sulla tabella correlata o importare in Tableau i dati di tabelle separate di FileMaker Pro, 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.
Configurare la connessione dati in 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/rest/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 alla soluzione FileMaker Pro inserendo le seguenti informazioni o utilizzando un provider di identità OAuth.
- Nome database origine: il nome della soluzione FileMaker Pro
- Nome formato origine: il nome del formato FileMaker Pro
- Nome account: il nome dell'account FileMaker Pro con privilegio fmrest
- Password: la password per l'account FileMaker Pro
- 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 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.
-
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_soluzione / 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 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.
- Se si modifica lo schema nel file FileMaker Pro, è necessario creare una nuova cartella di lavoro in Tableau e reimportare i dati.
- Il database Tableau Desktop può essere ospitato su Tableau Server per Windows.
- 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 a FileMaker Server.
- Se la connessione a Tableau scade, Web Data Connector per FileMaker tenta di riconnettersi a FileMaker Server finché la cartella di lavoro in Tableau è aperta.
- 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.