3.1. Administering ArcGIS for Server site: edit service properties

Now when we know how to establish connection to the site and access its resources and operations, let's look into how ArcGIS for Server services can be administered.

from arcrest import AGSTokenSecurityHandler
from arcrest.manageags._services import AGSService

We are already familiar with the AGSTokenSecurityHandler which as we know takes care of token request and log-in process. AGSService is however a new class we haven't looked at earlier. By using this class, we will be able to obtain an object that will represent those resources and operations that are accessible when you navigate to the Administrator Directory service page, such as at http://localhost:6080/arcgis/admin/services/SampleWorldCities.MapServer. There you can check its statistics, stop or start the service, or edit its capabilities. This is the code you need to get the service object:

ags_admin_url = r"http://localhost:6080/arcgis/admin"
admin_service_url = r"http://localhost:6080/arcgis/admin/services/SampleWorldCities.MapServer"

ags_security_handler = AGSTokenSecurityHandler(username="psa",
	                                           password="psa",
	                                           org_url=ags_admin_url)

ags_service_obj = AGSService(url=admin_service_url,securityHandler=ags_security_handler)

Note: Keep in mind that the operations accessible for a service will vary depending on whether you access it via Administrator Directory or via Services Directory. The latter one, accessible at http://localhost:6080/arcgis/rest/services/SampleWorldCities/MapServer will not provide any administrative access to the service. You would most likely use Services Directory for consuming service resources (querying map services, doing routing with network analysis services, etc.). In ArcREST, there are methods for "just" using services and they are accessible at arcrest.ags.server.Server class. Learn more about using service REST operations in ArcREST here.

Now we have ags_service_obj, which represents an arcrest.manageags._services.AGSService object. Another useful way of getting information about the attributes of an object (apart from using the __dict__ method) is converting it to a string. Many of the ArcREST classes provide a built-in __str__ method which will compute the "informal" string representation of an object: str(ags_service_obj)

Warning: for most of the samples in this documentation, SampleWorldCities map service is used. This is to let any user who has just completed a brand new ArcGIS for Server installation and don't have any other services published to follow along. Keep in mind though that since it's a system service, some of its properties (such as 'filePath') will be defined in another format which will be different from the map services you will publish using your own data.

The recommended way of accessing service properties is by getting the attribute of the ags_service_obj, such as:

ags_service_obj.maxIdleTime
>>> 1800

However, should any of the attributes be missing in the available properties, you can always try to access it from the dictionary representation of the AGSService object. It might be helpful when you need to access all of the object attributes.

ags_service_dict = ags_service_obj.__dict__
ags_service_dict['_json_dict']['maxIdleTime']
>>> 1800

We want to edit the service by modifying the maximum idle time value. To edit a service, you need to submit the complete JSON representation of the service, which includes the updates to the service properties. Editing a service causes the service to be restarted with updated properties.

First, let's get JSON representation of the service. You could browse to http://localhost:6080/arcgis/admin/services/SampleWorldCities.MapServer/edit page and copy the service properties in JSON format. Alternatively, you can load into JSON a string representation of the ags_service_obj.

import json
ags_service_json = json.loads(str(ags_service_obj))
print ags_service_json['maxIdleTime']
>>> 1800

Because ags_service_json is of dict type, we can modify its 'maxIdleTime' value (maximum time an idle instance can be kept running); let's make it 2400 seconds and apply this change. We can do this by calling the edit method for the ags_service_obj and supplying the service parameter. Because the service will be restarted, the edit method will take a while to complete.

ags_service_json['maxIdleTime'] = 2400
ags_service_obj.edit(service=ags_service_json)
>>> {'status': 'success'}

Let's make sure the edit was applied.

ags_service_obj.maxIdleTime
>>> 1800

What is going on here? It looks first as if the edit was not applied correctly. Let's take a look at the Administrator Directory service page at http://localhost:6080/arcgis/admin/services/SampleWorldCities.MapServer. Here, we can see that the edit was applied and the Maximum idle time (in seconds): shows 2400.

So why this is not reflected in the ags_service_obj? This is because this object is a representation of the service properties at the moment when it was initialized. You can use the ags_service_obj.refreshProperties() method that refreshes the object's values by re-querying the service.

Alternatively, in order to get the up-to-date representation of the service properties, you could re-initialize it by creating a new instance of the AGSService class.

ags_service_obj = AGSService(url=admin_service_url,securityHandler=ags_security_handler)
ags_service_obj.maxIdleTime
>>> 2400

You should keep this in mind and "refresh" your service instance object before checking whether any of your properties that have been modified are correct.