L'API di Qlik NPrinting è un'API REST utilizzata per gestire gli oggetti di Qlik NPrinting programmaticamente. Attraverso l'API è disponibile un sottogruppo delle funzionalità presenti nella console Web di Qlik NPrinting.
Gli oggetti manipolati nella console Web di Qlik NPrinting sono rappresentati nell'API come entità JSON. Queste entità hanno proprietà che corrispondono alle impostazioni presenti nella console Web di Qlik NPrinting. L'API ha un insieme di endpoint che consentono di creare, recuperare, aggiornare ed eliminare entità per app, utenti, gruppi, report e così via. Per tutte le richieste, i dati restituiti sono filtrati in base alle autorizzazioni dell'utente, ovvero, se un utente non è autorizzato ad accedere a una determinata entità, tale entità non viene restituita nella risposta.
Per accedere all'API come utente Windows autenticato, è necessario disporre di un account di dominio associato. Per ulteriori informazioni sulla configurazione di un account di dominio, vedere Creazione di utenti.
Come aiuto per acquisire familiarità con l'API, si vedranno alcuni semplici esempi che utilizzano un client REST denominato Postman. Verrà spiegato come:
- Connettersi e autenticare le proprie credenziali utente
- Recuperare un elenco di app
- Aggiornare un'entità
- Creare un filtro
Prima di cominciare, è necessario:
-
Installare Postman da:
- Conoscere l'URL del computer dove è installato Qlik NPrinting Server.
Autenticazione Windows
L'autenticazione Windows deve essere attivata al fine di consentire alle connessioni esterne come le connessioni GET e POST REST di funzionare normalmente. Questa impostazione può essere attivata e disattivata in Console web Qlik NPrinting sotto Amministratore> Impostazioni > Autenticazione.
Connessione alle API di Qlik NPrinting
Per impostazione predefinita, Qlik NPrinting Server ascolta le richieste REST sulla porta 4993, quindi l'URL è:
https://NPrinting.server.name:4993/api/v1/<path>
Autenticazione delle credenziali utente
Prima di poter utilizzare l'API di NPrinting, è necessario autenticare le proprie credenziali utente.
Nell'esempio che segue si effettuerà l'autenticazione con il nome utente Windows corrente.
Aprire Postman e compilare i campi come mostrato in basso. Sostituire NPrinting.server.name con l'URL del computer in cui è installato Qlik NPrinting Server.
Recupero di un elenco di app
L'endpoint seguente restituisce l'elenco completo delle app Qlik NPrinting che l'utente corrente è autorizzato a vedere.
Aprire Postman e compilare i campi come mostrato sotto, sostituendo NPrinting.server.name con l'URL del computer dove è installato Qlik NPrinting Server:
La risposta comprende ID, titolo e altri dettagli relativi a ogni app.
Aggiornamento di un'entità
È possibile aggiornare determinate entità tramite l'API utilizzando il metodo PUT. Quando si aggiorna un'entità, Qlik NPrinting Server potrebbe sostituire eventuali proprietà omesse con valori predefiniti, pertanto si raccomanda di includere sempre l'intera entità quando si effettua un aggiornamento.
In questo esempio si aggiornerà la proprietà email dell'entità users.
Per aggiornare l'entità:
- Se non si conosce l'ID dell'utente che si desidera aggiornare, immettere il percorso seguente in Postman e inviare una richiesta GET:
/users
Cercare l'ID utente nella risposta.
- Aggiungere l'ID utente al percorso users in Postman e inviare una richiesta GET:
/users/{id}
La risposta sarà simile alla seguente:
}{ "data": { "id": "113ac265-163e-4feb-854e-ade3cdafc837", "email": "abc@example.com", "created": "2018-02-22T16:17:18Z", "lastUpdate": "2018-02-28T18:20:57Z", "enabled": true, "userName": "Test", "domainAccount": "domain\\test", "timezone": "Europe/Rome", "locale": "En", "folder": "test folder", "subFolder": "test subFolder" }
- Dall'entità restituita, copiare il contenuto racchiuso dalle parentesi interne e incollarlo nel corpo di una nuova richiesta PUT.
- Modificare il valore di email.
- Aggiungere all'entità la proprietà password e il valore corrispondente. Il corpo della richiesta sarà simile al seguente:
{ "password": "test", "id": "113ac265-163e-4feb-854e-ade3cdafc837", "email": "xyz@example.com", "created": "2018-02-22T16:17:18Z", "lastUpdate": "2018-02-28T18:20:57Z", "enabled": true, "userName": "Test", "domainAccount": "domain\\test", "timezone": "Europe/Rome", "locale": "En", "folder": "test folder", "subFolder": "test subFolder" } -
Con l'entità aggiornata nel corpo, inviare una richiesta PUT utilizzando il percorso seguente:
users/{id}
In questo esempio, {id} sarà 113ac265-163e-4feb-854e-ade3cdafc837.
- Inviare una richiesta GET utilizzando lo stesso percorso per verificare la modifica.
Creazione di un filtro
È possibile creare filtri per attività, report, utenti e oggetti tramite l'API utilizzando il metodo POST. In questo esempio si creerà un filtro semplice per CategoryName, un campo nella sorgente dati di un'applicazione di vendita.
- Per creare un filtro, è necessario conoscere gli ID dell'app e della connessione alla quale si desidera applicare il filtro.
Per recuperare gli ID, inviare una richiesta GET utilizzando Postman per ognuno dei percorsi seguenti:
/apps
/connections
Ad esempio, per ottenere l'ID dell'app, inviare una richiesta GET a NPrinting.server.name:4993/api/v1/apps.
Cercare gli ID nelle risposte.
- Di seguito è riportato un esempio del codice che comprende gli ID dell'app e della connessione nel corpo di una richiesta POST /filters:
{ "appId": "de867383-3d6a-4f37-8fe5-387552c60d3f", "enabled": true, "name": "AverageSaleByCategory", "description": null, "fields": [ { "connectionId": "9a7b1016-8d22-46ac-a384-158f715547a7", "name": "CategoryName", "overrideValues": false, "values": [ { "value": "Bath Clothes", "type": "text" }, { "value": "Men´s Clothes", "type": "text" }] }] }
La risposta comprende l'ID del filtro appena creato, restituito nell'intestazione location.
Attività successive
Dopo avere visto alcune richieste nell'API di Qlik NPrinting, provare alcuni degli altri endpoint API, ad esempio, per avviare una nuova esecuzione di un'attività.
Queste risorse aggiuntive possono essere di aiuto: