ArcGIS Enterprise può essere amministrato semplicemente tramite richieste all'ArcGIS REST API. Anche quando si eseguono attività amministrative tramite il server o il portale, vengono effettuate chiamate all'API nel back-end. Per scrivere script che consentono di amministrare ArcGIS Enterprise, è 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.
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.
Introduzione
Per utilizzare l'ArcGIS REST API, è necessario creare una richiesta HTTP per l'operazione da eseguire e includere i parametri obbligatori per l'operazione. È possibile familiarizzare con le operazioni amministrative e i relativi parametri necessari consultando le serie di directory che consentono di interagire con le ArcGIS REST API. Le REST API di ArcGIS Enterprise vengono esposte tramite due directory di Portal e due directory server.
Utilizzare le ArcGIS REST API
Le directory Portal e server forniscono visualizzazioni interattive delle risorse ArcGIS REST API per l'organizzazione. Utilizzare queste directory può aiutare a comprendere come scrivere gli script di amministrazione per la propria organizzazione.
Gli URL alle directory del portale hanno il seguente formato:
- Directory Portal: https://webadaptorhost.domain.com/webadaptorname/sharing/rest
- Directory Portal Administrator—https://webadaptorhost.domain.com/webadaptorname/portaladmin
Gli URL alle directory del server hanno il seguente formato:
- Directory Services— https://gisserver.domain.com:6443/arcgis/rest/services
- Directory Server Administrator— https://gisserver.domain.com:6443/arcgis/admin
Per familiarizzare con le ArcGIS REST API, utilizzare una delle directory per eseguire un'attività amministrativa. Tenere presente i parametri che è necessario immettere e 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 utili quando si prova a costruire richieste amministrative HTTP tramite Python o un altro linguaggio di script.
Generare e utilizzare un token negli script
Quando si amministra l'organizzazione tramite le directory server, portal o rispettive, è necessario fornire il nome utente e password di un account con privilegi adeguati. Lo stesso concetto si applica anche alla creazione di script. Tuttavia, è necessario comprendere come avviene l'autenticazione quando si utilizzano script per amministrare l'organizzazione.
Se l'organizzazione è configurata per utilizzare account predefiniti e l'autenticazione token, è possibile usare gli stessi account amministrativi e URL per gli script che si usano nelle directory server e portal. Se l'organizzazione è configurata con accessi specifici per l'organizzazione e autenticazione a livello Web, si consiglia di fare in modo che gli script ignorino il Web Adaptor. Utilizzare l'account amministratore iniziale creato dopo l'installazione di Portal for ArcGIS per accedere al portale o l'account amministratore del sito principale creato dopo l'installazione di ArcGIS Server per accedere al server.
In entrambi i casi, viene restituito un token, ovvero una speciale stringa di caratteri che comunica al portale o al server l'avvenuta autenticazione dell'utente per l'esecuzione di determinati tipi di azione. È necessario includere questo token in qualsiasi richiesta di servizio Web inoltrata.
Per la seguente funzione di Python è richiesto un token del portale. 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.'''
data = urllib.parse.urlencode({'username' : username,
'password' : password,
'client' : 'referer',
'referer': portalUrl,
'expiration': 60,
'f' : 'json'}).encode('utf-8')
response = urllib.request.urlopen(portalUrl + '/sharing/rest/generateToken',
data).read().decode('utf-8')
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 as e:
print('An unspecified error occurred.')
print(e)Per la seguente funzione di Python è richiesto un token del server. L'URL, il nome utente e la password del server vengono forniti come argomenti.
def generateToken(username, password, serverUrl):
'''Retrieves a token to be used with API requests.'''
data = urllib.parse.urlencode({'username' : username,
'password' : password,
'client' : 'referer',
'referer': serverUrl,
'expiration': 60,
'f' : 'json'}).encode('utf-8')
response = urllib.request.urlopen(serverUrl + '/tokens/generateToken',
data).read().decode('utf-8')
try:
jsonResponse = json.loads(response)
if 'token' in jsonResponse:
return jsonResponse['token']
elif 'error' in jsonResponse:
print(jsonResponse['error']['message'])
print(jsonResponse['error']['details'])
except ValueError as e:
print('An unspecified error occurred.')
print(e)Il 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 è 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 comePython includono librerie in grado di analizzare o leggere una risposta JSON. In alcuni casi è necessario 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.