Guida di FileMaker Admin API 18

Questa guida fornisce informazioni sull'utilizzo di FileMaker Admin API versione 2 (v2) per eseguire operazioni di amministrazione sui prodotti FileMaker Cloud e su FileMaker Server (per informazioni su FileMaker Admin API versione 1 (v1), consultare il riferimento di FileMaker Admin API installato con i prodotti supportati).

Questa guida suppone che l'utente abbia esperienza con:

• l'utilizzo di FileMaker Pro Advanced per caricare i database. Vedere la Guida di FileMaker Pro Advanced.
• utilizzo di FileMaker Server o di un prodotto FileMaker Cloud per ospitare e gestire i database. Vedere la Guida di FileMaker Server o la documentazione dei prodotti FileMaker Cloud nel centro documentazione prodotto.
• l'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.

Note

• 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 ed è 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 indicano sia FileMaker Cloud che FileMaker Cloud for AWS.
• 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.
• App personalizzata, soluzione, database e file sono tutti termini che indicano ciò che l'utente crea e ciò con cui lavora utilizzando i prodotti FileMaker.
• In questa guida, il termine token di accesso indica il JSON Web Token richiesto per l'autenticazione.

FileMaker^® Admin API è un'Application Programming Interface (API) che permette ai servizi Web di eseguire operazioni di amministrazione sui prodotti FileMaker Cloud e su FileMaker Server. Poiché questa API utilizza l'architettura REST (REpresentational State Transfer), FileMaker Admin API è un'API REST.

FileMaker Admin 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.

Per utilizzare FileMaker Admin API:

1. Scrivere il codice per utilizzare le chiamate FileMaker Admin API per eseguire operazioni di amministrazione.
2. Verificare che l'accesso tramite FileMaker Admin API funzioni correttamente.
3. Monitorare i risultati rivedendo il file gateway.log (per un prodotto FileMaker Cloud) o il file fac.log (per FileMaker Server) in cui sono registrate tutte le chiamate API. Il file gateway.log può essere scaricato dalla FileMaker Cloud Admin Console. Il file fac.log si trova nella seguente cartella: .../FileMaker Server/Admin/FAC/logs.

Note

• Per accedere ai dati nei database ospitati, vedere la Guida di FileMaker Data API.

Client API REST

1

6

Server Web

2

5

Motore di FileMaker Admin API

3

4

Server database

Alcune delle chiamate FileMaker Admin API, come quelle di autenticazione, vengono elaborate solo in base ai primi due passi riportati di seguito. Altre, come quelle relative alla creazione di programmi o all'aggiornamento della configurazione, vengono elaborate in base a tutti i passi riportati di seguito.

1. Un client API REST invia una chiamata FileMaker Admin API (richiesta HTTPS) al server Web.
2. Il server Web invia la richiesta attraverso il Modulo Server Web di FileMaker al Motore di FileMaker Admin API.
3. Il Motore di FileMaker Admin API converte la richiesta HTTPS (URL e dati JSON) in un formato compatibile con il server database di FileMaker.
4. Il server database reinvia i risultati della richiesta al Motore di FileMaker Admin API.
5. Il Motore di FileMaker Admin API converte i risultati in una risposta HTTPS (URL con dati JSON) e trasferisce la risposta nuovamente al server Web.
6. Il server Web invia la risposta HTTPS al client API REST che ha inviato la richiesta.

Il riferimento di FileMaker Admin API è installato con FileMaker Server e con i prodotti FileMaker Cloud. Il riferimento fornisce informazioni dettagliate su tutte le chiamate supportate da FileMaker Admin API.

Per visualizzare il riferimento per il prodotto FileMaker Cloud, inserire in una finestra del browser il seguente URL:

https://host/fmi/admin/apidoc/

dove host è il nome host o l'indirizzo IP del server virtuale che esegue il prodotto FileMaker Cloud.

Per accedere al riferimento per FileMaker Server:

• Per visualizzare il riferimento in una finestra del browser sulla macchina master, inserire il seguente URL:

  https://hostlocale/fmi/admin/apidoc/

• Per visualizzare il riferimento in una finestra del browser su una macchina remota, inserire il seguente URL:

  https://host/fmi/admin/apidoc/

• Su un server Windows, il riferimento si trova nella seguente cartella:

  [unità]:\Programmi\FileMaker\FileMaker Server\Documentation\Admin 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\Admin API Documentation

• Su un server macOS, i file del riferimento si trovano nella seguente cartella:

  /Libreria/FileMaker Server/Documentation/Admin API Documentation

Note

• Se si utilizzano gli esempi di URL nel riferimento di Admin API e si apre il file del riferimento dall'unità locale, tutti gli esempi iniziano con file:///. Per utilizzare gli URL, sostituire file:/// con https://NomeHost/fmi/admin/api/v2.

FileMaker Admin API fornisce un'API REST che permette di automatizzare alcune operazioni di amministrazione di routine utilizzando degli script al posto dell'Admin Console.

FileMaker Admin API tiene traccia dello stato delle interazioni. È possibile iniziare con una chiamata di autenticazione oppure utilizzare altre chiamate per l'autenticazione. Quindi è possibile utilizzare il token di accesso restituito per chiamate successive.

Il token è valido fino a quando non viene invalidato utilizzando la chiamata Invalida token di accesso 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).

Le chiamate API relative ai database e le chiamate API di programma, tranne quelle per la creazione e la modifica/esecuzione di programmi, sono asincrone e non attendono una risposta dal prodotto FileMaker Cloud o da FileMaker Server. Potrebbe essere utile far seguire una chiamata asincrona da una chiamata GET per verificare che lo stato del file sia cambiato. Ad esempio, far seguire una chiamata per la chiusura di database da una chiamata GET databases per verificare che il database sia chiuso. Se lo stato non cambia immediatamente, continuare a controllare.

Le altre chiamate API sono sincrone e attendono una risposta dal prodotto FileMaker Cloud o da FileMaker Server.

FileMaker Admin API utilizza un token di accesso per definire una connessione all'host. Utilizzare la chiamata di autenticazione per richiedere un token di accesso dall'host utilizzando nome account e password dell'amministratore principale. Includere un'intestazione Authorization con valore Basic stringa con codifica Base64. La stringa con codifica Base64 deve essere generata sulla base di nomeutente:password. Lo schema di autenticazione Basic può essere utilizzato anche per altre chiamate.

Se si utilizza lo schema di autenticazione Basic per la chiamata di autenticazione, la richiesta restituisce il token di accesso nel corpo della risposta. Se si utilizza lo schema di autenticazione Basic per altre chiamate, la richiesta restituisce il token di accesso nel campo X-FM-Access-Token nell'intestazione di risposta.

Per chiamate API successive, utilizzare lo schema di autenticazione Bearer e includere un'intestazione Authorization con valore Bearer token di accesso.

Note

• Ogni volta che si utilizza lo schema di autenticazione Basic per ricavare un token di accesso, viene creata una nuova sessione API. Per evitare di avere più sessioni API, utilizzare lo stesso token di accesso con lo schema di autenticazione Bearer per tutte le chiamate API.

FileMaker Admin API utilizza un token di accesso per definire una connessione all'host.

Per autenticare gli account per FileMaker Cloud:

1. Generare il token ID FileMaker. Vedere la Guida della FileMaker Customer Console nel centro documentazione prodotto.

2. Includere il token ID FileMaker al passo 1 nella chiamata di autenticazione o in qualsiasi altra chiamata per generare un token di accesso.

   Ad esempio, per la chiamata di autenticazione utilizzare l'URL e l'intestazione riportati di seguito:

   • URL: https://host/fmi/admin/api/v2/user/auth

     dove host è il nome host o l'indirizzo IP del server virtuale che esegue FileMaker Cloud.

   • Intestazione: Authorization FMID Token_ID_FileMaker

   Se si utilizza la chiamata di autenticazione, il token di accesso viene restituito nel corpo della risposta. Se si utilizzano altre chiamate, il token viene restituito nel campo X-FM-Access-Token nell'intestazione di risposta.

3. Per chiamate API successive, includere la seguente intestazione Authorization per la chiamata di autenticazione:

   Intestazione: Authorization Bearer token di accesso

Note

• Ogni volta che si utilizza lo schema di autenticazione ID FileMaker per ricavare un token di accesso, viene creata una nuova sessione API. Per evitare di avere più sessioni API, utilizzare lo stesso token di accesso con lo schema di autenticazione Bearer per tutte le chiamate API.

La tabella di seguito mostra le chiamate FileMaker Admin API supportate per FileMaker Server e per i prodotti FileMaker Cloud.

• Il parametro startupRestorationLogPath per FileMaker Server Admin API specifica il percorso della cartella per il salvataggio dei registri di ripristino. Per risultati migliori, spostare la cartella del registro di ripristino su un'unità disco distinta.
• I prodotti FileMaker Cloud utilizzano il formato UTC per il parametro startTimeStamp.
• Per filemakerScriptType, è necessario fornire entrambi i parametri fmScriptAccount e fmScriptPassword per poter eseguire lo script.
• In FileMaker Cloud, per filemakerScriptType, utilizzare il parametro fmScriptAccount per specificare il token ID FileMaker e il parametro fmScriptPassword per specificare il token di aggiornamento ID FileMaker. Se non si specifica il token di aggiornamento, non è possibile eseguire lo script dopo la scadenza del token ID FileMaker. Per informazioni su come generare il token, vedere la Guida della FileMaker Customer Console nel centro documentazione prodotto.
• Se il valore restituito per il parametro di stato per la chiamata Elenca database è Normale, il database è aperto.