Portal for ArcGIS può essere amministrato semplicemente tramite richieste all'API REST di ArcGIS. Anche quando si utilizza il sito Web di Portal for ArcGIS per amministrare il portale, le chiamate all'API vengono effettuate nel back-end. Per scrivere script che consentono di amministrare Portal for ArcGIS, è necessario scegliere un linguaggio di scripting che supporta la costruzione di URL, la creazione di richieste HTTP e l'analisi di risposte HTTP. Negli esempi di questo sistema di Guida viene utilizzato Python.
È importante notare che per utilizzare l'API non è necessario che sia presente software Esri nel computer da cui si esegue lo script. È sufficiente un sistema in cui è possibile effettuare richieste HTTP al portale.
Informazioni preliminari sull'amministrazione del portale tramite l'API REST di ArcGIS
Per utilizzare l'API REST di ArcGIS, è necessario creare una richiesta HTTP per l'operazione da eseguire e includere i parametri obbligatori per l'operazione. Per familiarizzare con le operazioni amministrative disponibili e i parametri obbligatori, è possibile utilizzare la directory di Portal for ArcGIS.
Utilizzo della directory di Portal for ArcGIS
La directory di Portal for ArcGIS è disponibile tramite due applicazioni e può facilitare la creazione di script di amministrazione per il portale. La directory di Portal for ArcGIS è concettualmente simile ad Administrator Directory e a Services Directory di ArcGIS Server. Le attività disponibili variano a seconda delle applicazioni, come descritto in Informazioni sulla directory di Portal for ArcGIS. Il formato degli URL delle applicazioni è il seguente:
- https://webadaptorhost.domain.com/webadaptorname/portaladmin
- https://webadaptorhost.domain.com/webadaptorname/sharing/rest
Si può immaginare la directory di Portal for ArcGIS come un elenco di risorse di Portal for ArcGIS esposte tramite l'API REST. È possibile spostarsi tra i collegamenti della directory di Portal for ArcGIS per informazioni sugli URL e i parametri da utilizzare nelle richieste amministrative di servizi Web. È quindi possibile formulare queste richieste e inviarle tramite HTTP utilizzando il linguaggio di script desiderato.
Provare a utilizzare la directory di Portal for ArcGIS per eseguire un'attività amministrativa. Tenere presente i parametri che è necessario immettere ed osservare l'URL nella barra degli indirizzi del browser quando si effettua la richiesta al server. Per visualizzare interamente la richiesta e la risposta, è possibile utilizzare strumenti per sviluppatori Web quali Fiddler o Firebug. Queste informazioni sono estremamente utili quando si prova a costruire richieste amministrative HTTP tramite Python o un altro linguaggio di script.
Anche se è possibile utilizzare la directory di Portal for ArcGIS in modo interattivo per eseguire effettivamente attività amministrative, è consigliabile utilizzarla come strumento per familiarizzare con l'API REST. L'applicazione Web prevista per l'amministrazione del portale è il sito Web di Portal for ArcGIS.
Recuperare e utilizzare token negli script
Ogni volta che si amministra il portale tramite il sito Web o la directory di Portal for ArcGIS, è necessario specificare il nome utente e la password di un account che dispone di privilegi appropriati per il portale. Lo stesso concetto si applica anche alla creazione di script.
Tuttavia, a differenza dell'accesso al Portale Web o alla directory di Portal for ArcGIS in cui il browser gestisce in modo trasparente il processo di autenticazione, quando si utilizzano gli script per amministrare il portale è necessario comprendere il meccanismo di autenticazione.
Se il portale è configurato per l'autenticazione basata su account incorporati e token, sarà possibile utilizzare gli script con gli stessi account e URL di amministrazione utilizzati dalla directory di Portal for ArcGIS. Se il portale è configurato con accessi aziendali e autenticazione a livello Web, è consigliabile che gli script ignorino Web Adaptor e usino l'account amministratore iniziale creato dopo l'installazione di Portal for ArcGIS.
In entrambi i casi il portale restituisce quindi un token, ovvero una speciale stringa di caratteri che comunica al portale l'avvenuta autenticazione dell'utente per l'esecuzione di determinati tipi di azione. È necessario includere questo token in qualsiasi richiesta di servizio Web inoltrata al portale.
Per la seguente funzione di Python è richiesto un token. L'URL, il nome utente e la password del portale vengono forniti come argomenti.
def generateToken(username, password, portalUrl):
'''Retrieves a token to be used with API requests.'''
parameters = urllib.urlencode({'username' : username,
'password' : password,
'client' : 'referer',
'referer': portalUrl,
'expiration': 60,
'f' : 'json'})
response = urllib.urlopen(portalUrl + '/sharing/rest/generateToken?',
parameters).read()
try:
jsonResponse = json.loads(response)
if 'token' in jsonResponse:
return jsonResponse['token']
elif 'error' in jsonResponse:
print jsonResponse['error']['message']
for detail in jsonResponse['error']['details']:
print detail
except ValueError, e:
print 'An unspecified error occurred.'
print eIl token non ha durata illimitata; prevede infatti una scadenza in modo che non possa essere rubato e utilizzato a tempo indeterminato da un utente malintenzionato. È in genere necessario richiedere un nuovo token ogni volta che si esegue lo script, ma non ogni volta che si effettua una richiesta. In alcuni casi eccezionali i token possono scadere prima che termini l'esecuzione dello script. Se la richiesta include un token scaduto, la risposta del server includerà un errore per indicare tale situazione. In tale circostanza aggiornare il token e continuare con l'esecuzione dello script.
Gestire richieste e risposte
Per effettuare una richiesta di servizio Web, è necessario formulare l'URL per l'azione da eseguire, oltre ai parametri obbligatori dell'azione. Uno dei parametri obbligatori per un portale protetto è un token simile a quello generato in precedenza.
Tutte le azioni amministrative producono una risposta di servizio Web, che viene in genere richiesta in formato JSON (JavaScript Object Notation). I linguaggi di script, come Python, includono librerie in grado di analizzare o leggere una risposta JSON. In alcuni casi si desidera solo ottenere il codice di stato HTTP per sapere se la richiesta è stata completata (ad esempio il codice 200 indica OK). In altri casi è possibile che la risposta contenga dati, come messaggi di log che si desidera analizzare ed esaminare ulteriormente.
Per informazioni su come inviare a livello di programmazione una richiesta a Portal for ArcGIS e gestire una risposta, fare riferimento ai diversi esempi di codice inclusi in questa Guida.