Istnieje możliwość zarządzania oprogramowaniem ArcGIS Enterprise wyłącznie za pośrednictwem żądań zgłaszanych w interfejsie ArcGIS REST API. Nawet podczas wykonywania zadań administracyjnych za pośrednictwem serwera lub portalu wywołania interfejsu API są wykonywane w środowisku zaplecza. Aby móc pisać skrypty umożliwiające zarządzanie oprogramowaniem ArcGIS Enterprise, konieczne jest dokonanie wyboru języka skryptowego, który zapewnia możliwość budowy adresów URL, wykonywania żądań HTTP oraz przeprowadzania analiz odpowiedzi HTTP. W przykładach z tego tematu pomocy użyto języka Python.
Korzystanie z interfejsu API nie wymaga instalacji oprogramowania firmy Esri na komputerze, z poziomu którego uruchamiane są skrypty. Wystarczy środowisko umożliwiające wykonywanie żądań HTTP zgłaszanych do portalu.
Wprowadzenie
Aby skorzystać z interfejsu ArcGIS REST API, należy utworzyć żądanie HTTP dla operacji, która ma zostać wykonana, zamieszczając w nim wymagane dla tej operacji parametry. Możesz zapoznać się z operacjami administracyjnymi i z ich wymaganymi parametrami, przeglądając katalogi, które umożliwiają interakcje z interfejsami ArcGIS REST API. Interfejsy ArcGIS Enterprise REST API są dostępne w dwóch katalogach portalu i dwóch katalogach serwera.
Korzystanie z interfejsów ArcGIS REST API
Katalogi portalu i serwera udostępniają interaktywne widoki zasobów interfejsu ArcGIS REST API dla instytucji. Korzystanie z tych katalogów może pomóc w nauce pisania skryptów administracyjnych dla instytucji.
Adresy URL katalogów portalu mają następujący format:
- Katalog portalu — https://webadaptorhost.domain.com/webadaptorname/sharing/rest
- Katalog administratora portalu — https://webadaptorhost.domain.com/webadaptorname/portaladmin
Adresy URL katalogów serwera mają następujący format:
- Katalog usług — https://gisserver.domain.com:6443/arcgis/rest/services
- Katalog administratora serwera — https://gisserver.domain.com:6443/arcgis/admin
Aby zaznajomić się z interfejsem ArcGIS REST API, użyj jednego z tych katalogów do wykonania zadania administracyjnego. Zanotuj parametry, które trzeba będzie wprowadzić i sprawdź adres URL widoczny na pasku adresu przeglądarki podczas wykonywania żądania zgłaszanego do serwera. Narzędzia dla deweloperów witryn internetowych, takie jak Fiddler i Firebug, mogą być przydatne przy wyświetlaniu pełnej treści żądania i odpowiedzi. Te informacje są użyteczne w sytuacji, gdy użytkownik podejmuje próbę utworzenia własnego administracyjnego żądania HTTP za pomocą języka Python lub innego języka skryptowego.
Generowanie i użycie tokena w skryptach
Administrując instytucją za pośrednictwem portalu, serwera lub ich odpowiednich katalogów, musisz podać nazwę użytkownika i hasło konta mającego odpowiednie uprawnienia. Ta sama zasada obowiązuje podczas pisania skryptów. Używając skryptów do administrowania instytucją, trzeba jednak dokładnie rozumieć, w jaki sposób przebiega uwierzytelnianie.
Jeśli w instytucji skonfigurowano użycie kont wbudowanych i tokena uwierzytelniania, można na potrzeby skryptów używać tych samych kont administracyjnych i adresów URL, które byłyby używane z katalogami portalu i serwera. Jeżeli w instytucji skonfigurowano użycie loginów instytucji oraz uwierzytelnianie w warstwie sieci, zalecana jest modyfikacja skryptów tak, aby omijały aplikację Web Adaptor. Użyj początkowego konta administratora utworzonego po zainstalowaniu oprogramowania Portal for ArcGIS, aby uzyskać dostęp do portalu, lub konta głównego administratora witryny utworzonego po instalacji serwera ArcGIS Server, aby uzyskać dostęp do serwera.
W obu przypadkach zwracany jest token, który jest specjalnym ciągiem znaków będącym dla portalu lub serwera potwierdzeniem, że użytkownik otrzymał autoryzację do wykonania określonych czynności. Konieczne jest dołączenie tego tokena do każdego żądania kierowanego do usługi internetowej.
Poniższa funkcja języka Python umożliwia zgłoszenie żądania tokena portalu. Adres URL portalu, nazwa użytkownika oraz hasło zostały podane w formie argumentów.
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)Poniższa funkcja języka Python umożliwia zgłoszenie żądania tokena serwera. Adres URL serwera, nazwa użytkownika oraz hasło zostały podane w formie argumentów.
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)Token nie jest jednak ważny przez czas nieokreślony. Został utworzony tak, aby tracić ważność po upływie określonego czasu, dzięki czemu nie może zostać skradziony ani być stale używany przez złośliwego użytkownika. Zwykle konieczne jest zgłaszanie żądania wygenerowania nowego tokena za każdym razem, gdy uruchamiany jest skrypt (jednak nie za każdym razem, gdy zgłaszane jest żądanie). W niektórych wyjątkowych sytuacjach zdarza się, że token wygasa przed zakończeniem działania skryptu. Jeżeli zgłaszane żądanie zawiera nieważny token, odpowiedź serwera będzie zawierała komunikat o błędzie informującym o wygaśnięciu tokena. W takim przypadku należy odświeżyć token i kontynuować działanie skryptu.
Praca z żądaniami i odpowiedziami
Aby zgłosić żądanie do usługi internetowej, należy utworzyć adres URL czynności, która ma zostać wykonana, oraz wymagane parametry dla tej czynności. Jednym z wymaganych parametrów jest token, taki jak ten wygenerowany powyżej.
Wszystkie czynności administracyjne wiążą się z uzyskaniem odpowiedzi usługi sieciowej, której żądanie zwykle ma format pliku JSON (JavaScript Object Notation). Języki skryptowe, takie jak Python, mają biblioteki, które analizują (inaczej mówiąc odczytują) odpowiedź JSON. Czasem wystarczy wyłącznie uzyskanie kodu stanu HTTP, który umożliwia sprawdzenie, czy żądanie zostało wykonane pomyślnie (na przykład, kod 200 oznacza OK). W innych przypadkach odpowiedź ma formę danych, takich jak komunikaty dziennika, które czasem trzeba dalej przeanalizować lub sprawdzić.