Istnieje możliwość zarządzania oprogramowaniem Portal for ArcGIS wyłącznie za pośrednictwem żądań zgłaszanych w interfejsie ArcGIS REST API. Nawet w sytuacji, gdy do zarządzania portalem używane jest oprogramowanie Portal for ArcGIS, wywołania interfejsu API są wykonywane wewnętrznie. Aby móc pisać skrypty umożliwiające zarządzanie oprogramowaniem Portal for ArcGIS, 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.
Warto zauważyć, że 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 do zarządzania portalem za pomocą interfejsu ArcGIS REST API
Aby skorzystać z interfejsu ArcGIS REST API, należy utworzyć żądanie HTTP dotyczące operacji, która ma zostać wykonana, zamieszczając w nim wymagane dla tej operacji parametry. Prostym sposobem na zapoznanie się z dostępnymi operacjami administracyjnymi oraz parametrami, które są dla nich wymagane, jest skorzystanie z aplikacji ArcGIS Portal Directory.
Korzystanie z aplikacji ArcGIS Portal Directory
ArcGIS Portal Directory to katalog dostępny z poziomu dwóch aplikacji internetowych, który może być pomocny w nauce pisania skryptów administracyjnych dla portalu. Aplikacja ArcGIS Portal Directory koncepcyjnie przypomina aplikacje ArcGIS Server Administrator Directory oraz Services Directory. Dostępne zadania różnią się w zależności od aplikacji, szczegółowe informacje w tym zakresie można znaleźć w temacie Informacje o aplikacji ArcGIS Portal Directory. Adresy URL do wspomnianych aplikacji mają następujący format:
- https://webadaptorhost.domain.com/webadaptorname/portaladmin
- https://webadaptorhost.domain.com/webadaptorname/sharing/rest
Aplikację ArcGIS Portal Directory można postrzegać jako listę zasobów oprogramowania Portal for ArcGIS, która jest uwidaczniana za pośrednictwem interfejsu REST API. Możesz spróbować nawigacji za pomocą łączy dostępnych w aplikacji ArcGIS Portal Directory, aby dowiedzieć się, których adresów URL i parametrów należy użyć w żądaniach administracyjnych do usługi internetowej. Następnie możesz utworzyć te żądania i przesłać je za pomocą protokołu HTTP, używając wybranego języka skryptowego.
Spróbuj skorzystać z aplikacji ArcGIS Portal Directory do wykonania zadania administracyjnego. Zapisz parametry, które trzeba będzie wprowadzić, i przyglądaj się uważnie postaci adresu URL widocznego 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ą niezwykle 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.
Aplikacja ArcGIS Portal Directory może służyć do interaktywnego wykonywania bieżących zadań administracyjnych, jednak najlepiej sprawdza się ona w roli narzędzia do nauki obsługi interfejsu REST API. Aplikacją internetową przeznaczoną do zarządzania portalem jest oprogramowanie Portal for ArcGIS.
Uzyskiwanie tokena i używanie go w skryptach
Gdy zarządzasz portalem za pośrednictwem witryny portalu lub aplikacji ArcGIS Portal Directory, musisz podać nazwę użytkownika i hasło powiązane z kontem mającym odpowiednie uprawnienia do portalu. Ta sama zasada obowiązuje podczas pisania skryptów.
Jednak w przeciwieństwie do uzyskiwania dostępu do witryny portalu lub aplikacji ArcGIS Portal Directory za pomocą przeglądarki, która przejmuje obsługę procesu uwierzytelniania, w przypadku używania skryptów do zarządzania portalem konieczne jest zapoznanie z przebiegiem procesu uwierzytelniania.
Jeżeli portal został skonfigurowany tak, aby używane były konta wbudowane oraz uwierzytelnianie za pomocą tokenów, możliwe jest korzystanie ze skryptów z wykorzystaniem tych samych kont administratorów i adresów URL, które są używane z poziomu aplikacji ArcGIS Portal Directory. Jeżeli portal został skonfigurowany do używania loginów instytucji oraz uwierzytelniania w warstwie sieci, zalecana jest modyfikacja skryptów tak, aby omijały aplikację Web Adaptor i korzystanie z początkowego konta administratora utworzonego po zainstalowaniu oprogramowania Portal for ArcGIS.
W obu przypadkach portal generuje dla użytkownika token, który jest specjalnym ciągiem znaków będącym dla portalu potwierdzeniem, że użytkownik otrzymał autoryzację do wykonania określonych czynności. Konieczne jest zawarcie tego tokena w każdym żądaniu do usługi internetowej przesyłanej do portalu.
Następująca funkcja języka Python umożliwia zgłoszenie żądania tokena. 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.'''
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 eToken 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 wykonywania 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ć wykonywanie 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 w portalu zabezpieczonym 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 rejestr komunikatów, który czasem trzeba dalej przeanalizować lub sprawdzić.
Zapoznaj się z różnymi przykładami kodów w tym temacie pomocy, aby zrozumieć, w jaki sposób można programowo wysyłać żądania do oprogramowania Portal for ArcGIS i pracować z odpowiedziami.