Guida di FileMaker Cloud OData 2.18
Utilizzo di OData con i database FileMaker
Panoramica
Il Protocollo Open Data (OData) è un'implementazione API conforme agli standard industriali che fornisce un metodo standard per interrogare e aggiornare i dati, permettendo ai client API REST di accedere ai dati FileMaker® ospitati da FileMaker Cloud®. OData utilizza l'architettura REST (REpresentational State Transfer) ed è quindi un'API REST. OData è simile alle tecnologie Open Database Connectivity (ODBC) e Java Database Connectivity (JDBC) poiché fornisce alle applicazioni di terze parti, come Excel, un metodo standard per accedere ai dati FileMaker. Vedere Protocollo OData 4.0.
Inoltre, OData restituisce i dati in formato JSON (JavaScript Object Notation) e Atom (Atom Syndication Format). JSON è un formato di testo comunemente utilizzato con API REST poiché è compatto e leggibile. Atom è un formato XML utilizzato per creare e aggiornare le risorse Web ed è supportato per le applicazioni che utilizzano dati in una struttura XML invece che JSON.
Questa guida suppone che l'utente abbia esperienza con:
- utilizzo di FileMaker Pro Advanced per creare i database. È necessario comprendere le nozioni di base della progettazione dei database FileMaker Pro Advanced e i concetti di campo, tabella, relazione e contenitore. Vedere la Guida di FileMaker Pro Advanced.
- utilizzo di FileMaker Cloud per ospitare i database. È necessario comprendere come configurare FileMaker Cloud, consentire l'accesso ai database ospitati e monitorare i database ospitati utilizzando la FileMaker Cloud Admin Console. Vedere la documentazione di FileMaker Cloud nel centro documentazione prodotto.
- utilizzo di API REST in applicazioni lato server o servizi Web che chiamano i metodi POST, GET, PATCH e DELETE.
Istruzioni generali per utilizzare OData con i database FileMaker
- Preparare i database FileMaker per l'accesso tramite OData utilizzando FileMaker Pro Advanced. Vedere Consentire l'accesso tramite OData.
- Scrivere il codice per chiamare i metodi di OData per cercare e modificare i record, eseguire gli script FileMaker e modificare lo schema di un database ospitato. Vedere Scrivere le chiamate OData.
- Ospitare il database FileMaker utilizzando FileMaker Cloud con accesso tramite OData abilitato. Vedere Ospitare i database per l'accesso tramite OData.
- Verificare che l'accesso tramite OData funzioni correttamente. Vedere Testare l'accesso tramite OData.
- Monitorare il database ospitato utilizzando la FileMaker Cloud Admin Console. Vedere Monitorare l'accesso tramite OData.
Elaborazione delle chiamate OData
Client API REST
1
6
Server Web
2
5
OData Listener
3
4
Server database
- Un client API REST invia una chiamata OData (richiesta HTTPS) al server Web attraverso la porta HTTPS (porta 443).
- Il server Web invia la richiesta attraverso il Modulo Server Web di FileMaker all'OData Listener di FileMaker.
- L'OData Listener converte la richiesta HTTPS (URL con dati JSON o Atom) 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 all'OData Listener.
- L'OData Listener converte i dati FileMaker in una risposta HTTPS (URL con dati JSON o Atom) alla chiamata, restituendo i dati al Server Web.
- Il server Web invia la risposta HTTPS al client API REST che ha inviato la richiesta.
Confronto tra soluzioni API
La piattaforma FileMaker fornisce due API REST per accedere ai dati nei database FileMaker ospitati. Stabilire la soluzione più adatta in base a obiettivi professionali e ambiente.
| Soluzione | Utilizzarla quando | Vantaggi |
|---|---|---|
| Standard OData |
|
|
| FileMaker Data API |
|
|
Terminologia OData e FileMaker
Dove possibile, questa guida utilizza la terminologia FileMaker. A volte, per una maggiore chiarezza, insieme al termine FileMaker viene utilizzato il termine OData. La tabella di seguito mostra termini e definizioni corrispondenti.
Per informazioni sulla terminologia FileMaker, vedere il centro documentazione prodotto.
| Termine OData | Termine FileMaker |
|---|---|
| entity | record |
| entity set | tabella |
| entity container | gruppo di campi che non corrispondono necessariamente a un record (come il nome di un database e un URL) |
| collection of entity containers | elenco di un gruppo di campi (ad esempio, un elenco di nomi di database) |
| property | campo |
| path segment | valore tra due caratteri barra (in un URL) |
| raw value | un valore binario che corrisponde a una stringa di byte e non a un valore JSON o Atom strutturato leggibile |
Preparare i database per l'accesso tramite OData
Consentire l'accesso tramite OData
Per consentire l'accesso tramite OData ai dati FileMaker, è necessario attivare il privilegio esteso fmodata in FileMaker Pro Advanced. Se non si attiva il privilegio esteso fmodata, le applicazioni OData non saranno in grado di utilizzare le chiamate OData per accedere al database, anche se questo è ospitato.
Nota:per motivi di sicurezza, attivare il privilegio esteso fmodata solo nei set di privilegi per gli account a cui si desidera consentire l'accesso tramite OData.
Vedere "Modifica dei privilegi estesi per un set di privilegi" nella Guida di FileMaker Pro Advanced.
Conformità allo standard OData e supporto delle funzioni
Funzioni OData supportate
OData utilizza convenzioni compatibili con gli standard esistenti (REST, JSON, XML, Atom) per la rappresentazione di funzionalità comuni. La piattaforma FileMaker supporta OData al livello di conformità intermedio, con alcune eccezioni. Vedere la specifica Protocollo OData 4.0 e la guida di riferimento.
È possibile utilizzare OData API per:
- recuperare informazioni su FileMaker Cloud; ad esempio, nomi dei database ospitati e nomi delle tabelle e metadati per un database. Vedere Metadati e struttura dei database.
- creare, modificare o eliminare un record. Vedere Modificare i dati.
- trovare un record o tutti i record. Vedere Richiedere i dati.
- specificare i criteri per trovare un gruppo di record. Vedere Opzioni di interrogazione.
- eseguire script FileMaker. Vedere Eseguire gli script.
- caricare dati Contenitore. Vedere Lavorare con i dati Contenitore.
Funzioni OData non supportate
Queste funzioni OData del livello di conformità intermedio non sono supportate:
- opzione di interrogazione
$search $expand(supportata solo all'interno di un'operazione$crossjoin)- operatori
lambdaanyeall $filterin entità espansefunzioni e operatori canonici integrati:
- indexof()
- fractionalseconds()
- isof()
- geo.distance()
- geo.length()
- geo.intersects()
Inoltre, non sono supportate le seguenti azioni:
- accesso ai dati in origini dati ODBC esterne
- utilizzo dei plug-in FileMaker
- attivazione dei trigger di script attraverso l'interazione dell'utente; OData attiva i trigger di script solo eseguendo uno script FileMaker
- accesso al file system della macchina server; ad esempio, OData non supporta la funzione Get ( PercorsoTemporaneo )
Informazioni sul riferimento di OData
Vari riferimenti API forniscono specifiche per OData:
Note su URL e formato dati
- La lunghezza massima degli URL potrebbe essere influenzata da eventuali differenze in sistemi operativi, server Web e browser Web. Per un utilizzo ottimale su piattaforme diverse, limitare la lunghezza degli URL a 2.000 caratteri.
- Le stringhe negli URL devono utilizzare la codifica URL, detta anche codifica percentuale, normale per le richieste HTTP.
- I valori dei dati delle stringhe specificati nei parametri nel corpo della richiesta devono utilizzare la codifica UTF-8.
Script FileMaker e OData
Uno script FileMaker è un set denominato di istruzioni di script che consentono di combinare operazioni diverse e di automatizzare quelle eseguite più di frequente. Se utilizzati con OData, gli script FileMaker consentono ai servizi Web di eseguire più operazioni o una serie di operazioni. Vedere Eseguire gli script.
Note
- 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 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, concedere il set di privilegi Accesso completo a uno script per permettere allo script di eseguire operazioni che non si desidera concedere 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.
- 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. Convertire le singole azioni in script per includere l'istruzione di script 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 per l'accesso tramite OData. Verificare che lo script utilizzi solo istruzioni di script supportate da OData, come descritto in precedenza.
Scrivere le chiamate OData API
Componenti delle chiamate OData
Le chiamate OData sono costituite dai seguenti componenti.
| Componente | Descrizione |
|---|---|
| Metodo HTTP | OData utilizza i seguenti metodi HTTP:
|
| Intestazioni HTTP | OData utilizza le seguenti intestazioni:
|
| URL | https://host/fmi/odata/versione/nome-database host – nome host FileMaker Cloud Esempio: |
| Esempio di dati dei parametri in JSON e Atom | Solo per i metodi POST e PATCH. |
Creare una connessione autenticata all'host FileMaker
OData richiede l'autenticazione tramite un account ID FileMaker.
Per definire una connessione all'host FileMaker:
- Generare un token ID FileMaker per l'autenticazione esterna. Vedere la Guida della FileMaker Customer Console.
- Includere il token ID FileMaker al passo 1 nell'intestazione Authorization per tutte le chiamate OData.
Ad esempio, utilizzare il seguente URL e la seguente intestazione:
- URL:
https://host/fmi/odata/v4/nome-database/$metadatahost - nome host FileMaker Cloud
nome-database - nome del database FileMaker - Intestazione:
Authorization FMID Token_ID_FileMaker
- URL:
Metadati e struttura dei database
Le informazioni sui database ospitati e sulla relativa struttura sono disponibili eseguendo i metodi GET HTTP.
Ricavare i nomi dei database
Per restituire un elenco dei nomi dei database, utilizzare il metodo GET senza specificare il nome di un database nell'URL.
| Componente | Descrizione |
|---|---|
| Metodo HTTP | GET |
| URL | https://host/fmi/odata/versione host – nome host FileMaker Cloud Esempio: |
Informazioni FileMaker
- OData restituisce un elenco dei nomi dei database e i relativi URL degli endpoint.
Ricavare un elenco delle tabelle
Per recuperare un elenco delle tabelle in un database, utilizzare il metodo GET HTTP con il nome del database nell'URL.
| Componente | Descrizione |
|---|---|
| Metodo HTTP | GET |
| URL | https://host/fmi/odata/versione/nome-database host – nome host FileMaker Cloud Esempio: |
Ricavare i metadati
Per richiedere informazioni sui metadati delle tabelle, utilizzare il metodo GET HTTP.
Utilizzare la parola chiave $metadata con la radice del servizio di database per richiedere un elenco completo dei metadati per il database.
| Componente | Descrizione |
|---|---|
| Metodo HTTP | GET |
| URL | https://host/fmi/odata/versione/nome-database/$metadata host – nome host FileMaker Cloud Esempio: |
Informazioni FileMaker
Per fornire informazioni sulle tabelle FileMaker nel database, vengono aggiunte delle annotazioni (informazioni non definite nello standard OData) ai risultati dei metadati, come il numero della versione del prodotto FileMaker.
Le annotazioni di seguito, se presenti, hanno un valore booleano Vero. In caso contrario, il valore è Falso.
- AutoGenerated: se il valore del campo è generato automaticamente da FileMaker Pro Advanced
- Index: se i valori del campo sono indicizzati
- VersionID: se il campo è di tipo Indicatore data e ora e, quando viene modificato il record, viene generato un nuovo valore indicatore data e ora
- Global: se il campo contiene un valore globale
- Calculation: se il campo è di tipo Calcolo
- Summary: se il campo è di tipo Riassunto
Altre annotazioni:
- MaxRepetitions: un valore intero che indica il numero massimo di ripetizioni definito per un campo multiplo. Se questa annotazione non è presente, il campo non è un campo multiplo.
- ExternalSecurePath: una stringa che indica il percorso relativo specificato per la memoria protetta di un campo Contenitore.
- BestRowID: contiene sempre ROWID, un campo di sistema esplicitamente incluso in un gruppo di risultati specificando
$select=ROWID. Il valore nel gruppo di risultati è lo stesso della funzione Get ( IDRecord ) per un record. - RowVersion: contiene sempre ROWMODID, un campo di sistema esplicitamente incluso in un gruppo di risultati specificando
$select=ROWMODID. Il valore nel gruppo di risultati è lo stesso della funzione Get ( ContoModificaRecord ) per un record.
Importante: OData richiede che ogni tabella definisca una chiave primaria. OData utilizza i campi che non sono vuoti e che richiedono un valore univoco come chiave primaria. Pertanto, se per le tabelle non sono definiti questi campi, come chiave primaria viene utilizzato il campo di sistema ROWID. Il campo di sistema ROWID contiene lo stesso valore della funzione Get ( IDRecord ) per il record.
Modificare i dati
OData supporta le operazioni di creazione, aggiornamento ed eliminazione per i record in base ai privilegi di accesso assegnati a un account.
Creare un record
Per creare un record per una tabella, utilizzare il metodo POST. Il corpo POST deve contenere i dati di un singolo record in formato JSON.
| Componente | Descrizione |
|---|---|
| Metodo HTTP | POST |
| URL | https://host/fmi/odata/versione/nome-database/nome-tabella host – nome host FileMaker Cloud Esempio: |
| Parametri | Esempio JSON: {Esempio Atom: |
Informazioni FileMaker
- I valori per le singole ripetizioni in un campo multiplo vengono forniti specificando il numero di ripetizioni tra parentesi quadre (ad esempio,
Nome[4]). - Se si crea un record con oggetti dati vuoti in formato JSON, almeno un campo deve consentire valori nulli.
- I campi globali FileMaker sono di sola lettura e non possono essere aggiornati con OData.
Eliminare un record
Per eliminare un record, utilizzare il metodo DELETE HTTP specificando il nome della tabella e il valore della chiave primaria del record nell'URL.
| Componente | Descrizione |
|---|---|
| Metodo HTTP | DELETE |
| URL | https://host/fmi/odata/versione/nome-database/nome-tabella (valore-chiave-primaria) host – nome host FileMaker Cloud Esempio: |
Informazioni FileMaker
- È possibile eliminare più record specificando criteri
$filter.
Aggiornare un record
Per aggiornare un record, utilizzare un metodo PATCH HTTP con il record da aggiornare nell'URL.
| Componente | Descrizione |
|---|---|
| Metodo HTTP | PATCH |
| URL | https://host/fmi/odata/versione/nome-database/nome-tabella (valore-chiave-primaria) host – nome host FileMaker Cloud Esempio: |
| Parametri | Esempio JSON: { |
Informazioni FileMaker
- I valori Contenitore vengono aggiornati fornendo un valore con codifica Base64 come descritto in Aggiornare un record con un campo Contenitore immagine o PDF oppure fornendo i dati binari descritti in Aggiornare un record con un campo Contenitore immagine o PDF con dati binari.
- I valori per le singole ripetizioni nei campi multipli vengono forniti specificando il numero di ripetizioni tra parentesi quadre (ad esempio,
Nome[4]). Non è possibile specificare una ripetizione di un campo Contenitore quando si aggiorna un record. - È possibile aggiornare più record specificando criteri
$filter.
Lavorare con i dati Contenitore
È possibile inviare un metodo POST o PATCH HTTP per inserire immagini o file PDF nei campi Contenitore. I dati nei campi Contenitore sono incorporati nel campo, memorizzati come riferimento al file o memorizzati esternamente.
Creare un record con un campo Contenitore immagine o PDF
Per creare un record per una tabella con uno o più campi Contenitore, impostare il campo con dati con codifica Base64. Sono supportati solo i tipi di file GIF, PNG, JPEG, TIFF e PDF. Il corpo POST deve contenere la rappresentazione di un singolo record valido.
| Componente | Descrizione |
|---|---|
| Metodo HTTP | POST |
| URL | https://host/fmi/odata/versione/nome-database/nome-tabella host – nome host FileMaker Cloud Esempio: |
| Parametri | Esempio JSON: { |
Informazioni FileMaker
- Il tipo di supporto di un valore Contenitore con codifica Base64 viene determinato confrontando i primi byte dei dati con i valori previsti per i tipi di supporto supportati.
Aggiornare un record con un campo Contenitore immagine o PDF con dati binari
La richiesta in questa tabella aggiorna il valore in un campo Foto di un record Contatti utilizzando il metodo PATCH con byte GIF binari (non strutturati) nel corpo della richiesta. L'intestazione Content-Type deve specificare il tipo di dati contenuti nel corpo (image/gif, image/png, image/jpeg, image/tiff o application/pdf).
| Componente | Descrizione |
|---|---|
| Metodo HTTP | PATCH |
| URL | https://host/fmi/odata/versione/nome-database/nome-tabella (valore-chiave-primaria)/nome-campo host – nome host FileMaker Cloud Esempio: |
| Parametri | "474946383961090009008001007F7F7FFFFFFF21F90401000001002C00000000090009 |
Aggiornare un record con un campo Contenitore immagine o PDF
Per aggiornare il valore di un campo Contenitore per un record, utilizzare il metodo PATCH HTTP con valore con codifica Base64.
| Componente | Descrizione |
|---|---|
| Metodo HTTP | PATCH |
| URL | https://host/fmi/odata/versione/nome-database/nome-tabella (valore-chiave-primaria) host – nome host FileMaker Cloud Esempio: |
| Parametri | Esempio JSON: { |
Richiedere i dati
Richiedere i record di una tabella
Per restituire un insieme di record del database FileMaker, utilizzare il metodo GET HTTP con il nome della tabella nell'URL.
| Componente | Descrizione |
|---|---|
| Metodo HTTP | GET |
| URL | https://host/fmi/odata/versione/nome-database/nome-tabella host – nome host FileMaker Cloud Esempio: |
Informazioni FileMaker
- Se si ricavano tutti i record o un singolo record, i campi Contenitore non sono inclusi nel risultato della risposta. Per informazioni sulla richiesta dei valori dei campi Contenitore, vedere Richiedere il valore di un singolo campo.
Richiedere un singolo record
Per richiedere un singolo record in una tabella di database, specificare il nome del database, il nome della tabella e il valore della chiave primaria del record.
| Componente | Descrizione |
|---|---|
| Metodo HTTP | GET |
| URL | https://host/fmi/odata/versione/nome-database/nome-tabella (valore-chiave-primaria) host – nome host FileMaker Cloud Esempio: |
Informazioni FileMaker
- Il valore della chiave primaria specificato nell'URL corrisponde al campo designato come chiave primaria o, se non è stata designata nessuna chiave primaria, al campo di sistema ROWID. Vedere Ricavare i metadati. Per i campi multipli, il valore della prima ripetizione è incluso. Per ricavare singole ripetizioni, vedere Richiedere il valore di un singolo campo.
Richiedere il valore di un singolo campo
Per richiedere il valore di un singolo campo, specificare il nome della tabella, il valore della chiave primaria del record e il nome del campo.
| Componente | Descrizione |
|---|---|
| Metodo HTTP | GET |
| URL | https://host/fmi/odata/versione/nome-database/nome-tabella (valore-chiave-primaria)/nome-campo host – nome host FileMaker Cloud Esempio: |
Informazioni FileMaker
- In un URL, quando si richiede una singola ripetizione, l'utilizzo delle parentesi quadre ([ ]) per specificare il numero di ripetizioni non è supportato.
- Se il campo ripetuto è un campo Contenitore, viene restituita solo la prima ripetizione. In caso contrario, vengono restituite tutte le ripetizioni.
Richiedere il valore binario di un singolo campo
Per richiedere un singolo campo memorizzato come valore binario, utilizzare l'opzione di interrogazione $value.
Il formato predefinito del valore binario per il campo FileMaker è text/plain. Per i campi Contenitore, il formato predefinito varia in base al tipo di campo Contenitore e include image/gif, image/png, image/jpeg, image/tiff, application/pdf o application/octet-stream.
| Componente | Descrizione |
|---|---|
| Metodo HTTP | GET |
| URL | https://host/fmi/odata/versione/nome-database/nome-tabella (valore-chiave-primaria)/nome-campo/$value host – nome host FileMaker Cloud Esempio: Questa richiesta restituisce il valore binario del campo Nome per il record Contatti. |
Informazioni FileMaker
- Quando si richiede il valore (non elaborato) binario di un campo ripetuto, viene restituito solo il valore (non elaborato) binario della prima ripetizione.
Esplorare le tabelle correlate
È possibile esplorare le relazioni tra le tabelle FileMaker senza specificare i campi di confronto per ciascuna relazione. Tutte le operazioni e i risultati sono associati all'ultima tabella nell'URL.
| Componente | Descrizione |
|---|---|
| Metodo HTTP | GET |
| URL | https://host/fmi/odata/versione/nome-database/nome-tabella (valore-chiave-primaria)/tabella-correlata host – nome host FileMaker Cloud Esempio: Questa richiesta restituisce tutti i prodotti acquistati da un cliente con l'ID indicato. |
Informazioni FileMaker
- Quando si utilizza l'opzione di interrogazione
$filter, è possibile evitare ambiguità nei nomi dei campi anteponendo il nome della tabella al nome del campo nell'espressione (ad esempio,$filter=Acquisto/ID eq 7).
Richiedere una cross join di tabelle non correlate
Per richiedere una cross join di tabelle non correlate, utilizzare la parola chiave $crossjoin ed elencare le tabelle da unire. Quando si utilizza l'opzione di interrogazione $filter, specificare ogni campo utilizzato per unire le due tabelle.
Utilizzare le opzioni di interrogazione $expand e $select per assicurarsi che vengano restituiti i campi dati e non il comportamento predefinito, ovvero un elenco degli ID dei record. Vedere "Gestione della cross join di set di entità" in Convenzioni per gli URL OData 4.0.
Nota: una cross join è l'unico contesto in cui la parola chiave $expand è supportata.
| Componente | Descrizione |
|---|---|
| Metodo HTTP | GET |
| URL | https://host/fmi/odata/versione/nome-database/$crossjoin (tabella 1, tabella 2)?$filter= host – nome host FileMaker Cloud Esempio: |
Opzioni di interrogazione
OData supporta diverse opzioni di interrogazione per interrogare i dati.
Opzione di interrogazione $filter
Utilizzare l'opzione di interrogazione $filter per filtrare i record. L'espressione specificata con $filter viene valutata per ogni record nell'insieme e solo le voci valutate vere dall'espressione vengono incluse nella risposta.
OData supporta una serie di funzioni e operatori integrati utilizzati nelle operazioni $filter. Per ulteriori informazioni sulle funzioni e sugli operatori integrati disponibili, vedere Protocollo OData 4.0.
| Componente | Descrizione |
|---|---|
| Metodo HTTP | GET |
| URL | https://host/fmi/odata/versione/nome-database/nome-tabella?$filter=(espressione) host – nome host FileMaker Cloud Esempio: Questa richiesta utilizza il metodo GET e l'opzione di interrogazione |
Informazioni FileMaker
Le seguenti funzioni integrate non sono supportate:
- indexof()
- isof()
- geo.distance()
- geo.length()
- geo.intersects()
- fractionalseconds()
- I formati data, ora e indicatore data e ora sono conformi ai requisiti della norma ISO 8601. Le differenze di fuso orario sono rispetto al fuso orario del server.
- Racchiudere i nomi dei campi che includono caratteri speciali, come spazi o caratteri di sottolineatura, tra virgolette doppie.
Opzione di interrogazione $orderby
Utilizzare l'opzione di interrogazione $orderby per richiedere i record in ordine crescente o decrescente. Se non si specifica un criterio, l'ordine predefinito è quello crescente.
| Componente | Descrizione |
|---|---|
| Metodo HTTP | GET |
| URL | https://host/fmi/odata/versione/nome-database/nome-tabella?$orderby=nome-campo {asc/desc} host – nome host FileMaker Cloud Esempio: Questa richiesta riporta i record Contatti in ordine decrescente in base al campo Società. |
Informazioni FileMaker
- Racchiudere i nomi dei campi che includono caratteri speciali, come spazi o caratteri di sottolineatura, tra virgolette doppie.
- L'opzione di interrogazione
$orderbynon supporta le funzioni OData integrate.
Opzioni di interrogazione $top e $skip
Utilizzare le opzioni di interrogazione $top e $skip per eseguire il paging di un gruppo di risultati. È possibile utilizzare queste opzioni di interrogazione da sole o insieme, in base a quali record si desidera avere nella risposta.
| Componente | Descrizione |
|---|---|
| Metodo HTTP | GET |
| URL | https://host/fmi/odata/versione/nome-database/nome-tabella{?$top/?$skip}=numero host – nome host FileMaker Cloud Opzioni di interrogazione {?$top/?$skip} - l'opzione di interrogazione Esempio:
|
Opzione di interrogazione $count
Utilizzare l'opzione di interrogazione $count (valore impostato su vero) per richiedere il numero di record corrispondenti restituiti insieme ai record nella risposta. L'opzione di interrogazione $count ignora eventuali opzioni di interrogazione $top o $skip e restituisce il numero totale di risultati per tutti i record, inclusi i risultati che corrispondono ai criteri $filter (se specificati).
| Componente | Descrizione |
|---|---|
| Metodo HTTP | GET |
| URL | https://host/fmi/odata/versione/nome-database/nome-tabella?$count=true host – nome host FileMaker Cloud Esempio: |
Opzione di interrogazione $select
Utilizzare l'opzione di interrogazione $select per richiedere un gruppo limitato di campi per ciascuna tabella. L'impostazione predefinita prevede la restituzione di tutti i campi, tranne quelli Contenitore.
| Componente | Descrizione |
|---|---|
| Metodo HTTP | GET |
| URL | https://host/fmi/odata/versione/nome-database/nome-tabella?$select=campo 1, campo 2 host – nome host FileMaker Cloud Esempio: Questa richiesta restituisce i dati Società e Sito Web per tutti i record nella tabella Contatti. |
Informazioni FileMaker
- I campi di sistema ROWID e ROWMODID vengono inclusi nel gruppo di risultati specificandoli con l'opzione di interrogazione
$select. Ad esempio:$select=ROWID, ROWMODID. - ROWID corrisponde al valore restituito dalla funzione Get ( IDRecord ), mentre ROWMODID a quello restituito dalla funzione Get ( ContoModificaRecord ).
Modificare lo schema
OData supporta le operazioni di creazione ed eliminazione di tabelle e indici in base ai privilegi di accesso definiti per un account.
Creare una tabella
Per creare una nuova tabella, utilizzare il metodo POST HTTP. Il corpo POST deve contenere la rappresentazione di una singola tabella valida che includa un identificativo corrispondente al nome della tabella.
| Componente | Descrizione |
|---|---|
| Metodo HTTP | POST |
| URL | https://host/fmi/odata/versione/nome-database/FileMaker_Tables host – nome host FileMaker Cloud Esempio: |
| Parametri | Esempio JSON: { "tableName": "Società", "fields": [ { "name": "ID società", "type": "int", "primary": true }, { "name": "ID utente", "type": "varchar(20)", "unique": true, "default": "CURRENT_USER" }, { "name": "Nome società", "type": "varchar(100)", "nullable": false }, { "name": "Appunti", "type": "varchar(2000)", "global": true }, { "name": "Contratto firmato", "type": "blob", "externalSecurePath": "File/GestContatti/" } ] } Esempio Atom: <TableDefinition tableName="Società"> <FieldDefinition name="ID società" type="int" primary="true"/> <FieldDefinition name="ID utente" type="varchar(20)"unique="true" default="CURRENT_USER"/> <FieldDefinition name="Nome società" type="varchar(100)" nullable="false"/> <FieldDefinition name="Appunti" type="varchar(2000) global="true"/> </TableDefinition> |
Informazioni FileMaker
- FileMaker_Tables è una tabella di sistema utilizzata per creare, modificare ed eliminare le tabelle. Il parametro
typecorrisponde a uno dei seguenti valori: NUMERIC, DECIMAL, INT, DATE, TIME, TIMESTAMP, VARCHAR, CHARACTER VARYING, BLOB, VARBINARY, LONGVARBINARY o BINARY VARYING. - Le ripetizioni sono specificate tra parentesi quadre dopo il valore (ad esempio,
"INT[4]"). È possibile specificare la lunghezza massima di un campo Testo tra parentesi (ad esempio,"VARCHAR(200)"). Con il nome del campo e il tipo di campo vengono utilizzati parametri facoltativi:
"primary": true o false (se il campo è una chiave primaria; il valore predefinito è false)"unique": true o false (se il campo deve avere un valore univoco; il valore predefinito è false)"nullable": true o false (se il campo deve avere un valore; il valore predefinito è true)"global": true o false (se il campo è globale; il valore predefinito è false)"default": una stringa contenente una parola chiave adatta al tipo di dati; le parole chiave valide sono USER, USERNAME, CURRENT_USER, CURRENT_DATE, CURDATE, CURRENT_TIME, CURTIME, CURRENT_TIMESTAMP e CURTIMESTAMP"externalSecurePath"(solo campo Contenitore): una stringa contenente un percorso relativo per i file protetti in "externalSecurePath". Escludere la parte "[posizione database]/" della directory di base. Assicurarsi di eseguire questa impostazione per ogni database FileMaker in FileMaker Pro Advanced. Vedere la Guida di FileMaker Pro Advanced.
Aggiungere campi in una tabella
Per creare un campo nuovo in una tabella esistente, inviare una richiesta PATCH alla tabella di sistema FileMaker_Tables, seguita dal nome della tabella nell'URL. Il corpo PATCH deve contenere un elenco dei campi da aggiungere alla tabella.
Se la richiesta non riesce a causa di un errore durante l'aggiunta di un campo, è comunque ancora possibile aggiungere altri campi alla tabella.
| Componente | Descrizione |
|---|---|
| Metodo HTTP | PATCH |
| URL | https://host/fmi/odata/versione/nome-database/FileMaker_Tables/nome-tabella host – nome host FileMaker Cloud Esempio: Questa richiesta crea un campo Telefono nella tabella Società. |
| Parametri | Esempio JSON: { "fields": [ { "name": "Telefono", "type": "varchar(25)" } ] } Esempio Atom: <TableDefinition tableName="Società"> <FieldDefinition name="Telefono" type="varchar(25)"/> </TableDefinition>
|
Informazioni FileMaker
- FileMaker_Tables è una tabella di sistema utilizzata per creare, modificare ed eliminare le tabelle. Per le opzioni valide, vedere Creare una tabella.
Eliminare una tabella
Per eliminare una tabella e tutti i relativi record, utilizzare il metodo DELETE HTTP e indicare il nome della tabella nell'URL.
| Componente | Descrizione |
|---|---|
| Metodo HTTP | DELETE |
| URL | https://host/fmi/odata/versione/nome-database/FileMaker_Tables/nome-tabella host – nome host FileMaker Cloud Esempio: |
Informazioni FileMaker
- FileMaker_Tables è una tabella di sistema utilizzata per creare, modificare ed eliminare le tabelle.
- Questa operazione elimina una tabella e tutti i relativi dati senza chiedere conferma. Per impedire la perdita dei dati, creare un account con privilegi di accesso per l'eliminazione delle tabelle e utilizzarlo esclusivamente per questa operazione.
Eliminare un campo da una tabella
Per eliminare un campo da una tabella, utilizzare il metodo DELETE HTTP aggiungendo il nome del campo al nome della tabella nell'URL.
| Componente | Descrizione |
|---|---|
| Metodo HTTP | DELETE |
| URL | https://host/fmi/odata/versione/nome-database/FileMaker_Tables/nome-tabella/nome-campo host – nome host FileMaker Cloud Esempio: |
Creare un indice di campo
Per creare un nuovo indice, inviare una richiesta POST al nome della tabella dopo la tabella di sistema FileMaker_Indexes. Il corpo POST deve contenere la rappresentazione di un singolo indice valido che sia un identificativo corrispondente al nome del campo.
| Componente | Descrizione |
|---|---|
| Metodo HTTP | POST |
| URL | https://host/fmi/odata/versione/nome-database/FileMaker_Indexes/nome-tabella host – nome host FileMaker Cloud Esempio: |
| Parametri | Esempio JSON: { Esempio Atom: <IndexDefinition indexName="Stato"/> |
Informazioni FileMaker
- FileMaker_Indexes è una tabella di sistema utilizzata per creare ed eliminare gli indici.
Eliminare un indice
Per eliminare un indice, inviare una richiesta DELETE HTTP alla tabella di sistema FileMaker_Indexes, seguita dal nome della tabella e dal nome del campo nell'URL.
| Componente | Descrizione |
|---|---|
| Metodo HTTP | DELETE |
| URL | https://host/fmi/odata/versione/nome-database/FileMaker_Indexes/nome-tabella/nome-campo host – nome host FileMaker Cloud Esempio: |
Informazioni FileMaker
- FileMaker_Indexes è una tabella di sistema utilizzata per creare ed eliminare gli indici nei campi.
- Per eliminare un indice, l'URL deve specificare prima il nome della tabella, seguito dal nome del campo.
Eseguire gli script
Per eseguire uno script, inviare una richiesta POST alla tabella di sistema Script, seguita dal nome dello script nell'URL. Il corpo POST deve essere completamente vuoto se lo script non riceve nessun parametro, oppure deve contenere un singolo campo scriptParameterValue se viene passato un parametro allo script. scriptParameterValue accetta valori di tipo stringa, numero e oggetto JSON.
OData non supporta nomi di script con caratteri speciali (ad esempio, @, &, /) o nomi di script che iniziano con un numero. Se lo script contiene l'istruzione di script Esci dallo script, il risultato di testo di Esci dallo script viene restituito in un campo resultParameter nei risultati.
Lo script ScriptCiao aggiunge il valore del parametro alla stringa "Ciao" e restituisce il risultato. OData restituisce il risultato nel corpo della risposta con un Content-Type di "application/json":
{
"scriptResult":
{
"code": 0,
"resultParameter": "Ciao a tutti"
}
}
Nota: OData supporta solo gli script che vengono eseguiti senza interazione dell'utente.
Eseguire uno script
Per eseguire uno script, utilizzare il metodo POST HTTP.
| Componente | Descrizione |
|---|---|
| Metodo HTTP | POST |
| URL | https://host/fmi/odata/versione/nome-database/Script.nome-script host – nome host FileMaker Cloud Esempio: a tutti. |
| Parametri | Esempio JSON: |
Informazioni FileMaker
- Per uniformarsi al concetto OData di azione, tutti gli script fanno parte di una tabella di sistema Script.
Ospitare, testare e monitorare OData
Ospitare i database per l'accesso tramite OData
- Completare i passi in Consentire l'accesso tramite OData.
- Verificare che l'accesso tramite OData ai database FileMaker sia abilitato e configurato correttamente nella FileMaker Cloud Admin Console. Vedere la documentazione di FileMaker Cloud nel centro documentazione prodotto.
- Verificare che il server Web e l'OData Listener siano in esecuzione.
-
Utilizzare la crittografia per la comunicazione.
OData richiede di utilizzare una connessione HTTPS. Le connessioni HTTPS utilizzano la crittografia SSL (Secure Sockets Layer) per la comunicazione.
Il linguaggio o la tecnologia di programmazione utilizzati per chiamare OData API devono supportare il protocollo TLS (Transport Layer Security) v1.2 per comunicare con il server Web.
Testare l'accesso tramite OData
Prima della messa in produzione, verificare che OData 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 o modificare i dati.
- Verificare che la soluzione si comporti allo stesso modo quando eseguita in sistemi operativi diversi.
Monitorare l'accesso tramite OData
L'amministratore server utilizza la FileMaker Customer Console per avviare o arrestare l'OData Listener, tenere traccia dell'utilizzo delle chiamate OData e scaricare il file di registro di OData.
| Per | Utilizzare |
|---|---|
| Avviare o arrestare l'OData Listener | La FileMaker Customer Console Connettori > scheda OData. Vedere la Guida di FileMaker Cloud nel centro documentazione prodotto. |
| Tenere traccia dell'utilizzo delle chiamate OData API | La FileMaker Customer Console Connettori > scheda OData . Questa scheda visualizza il limite annuale OData stabilito dall'abbonamento a FileMaker Cloud, la quantità di dati trasmessa dalla data di azzeramento annuale precedente e la data di azzeramento annuale dell'abbonamento. Se si sta raggiungendo il limite annuale, è possibile aumentare il limite utilizzando la scheda Abbonamento nella FileMaker Customer Console. Vedere la Guida della FileMaker Customer Console nel centro documentazione prodotto. |
| Visualizzare il registro di OData API | Mentre i client OData sono collegati a un database, i relativi dati statistici vengono registrati nel file fmodata.log. Vedere la Guida di FileMaker Cloud nel centro documentazione prodotto. |