Portal for ArcGIS | Administrator Guide - Scripting with the ArcGIS REST API

Portal for ArcGIS can be administered purely through requests to the ArcGIS REST API. Even when you use the Portal for ArcGIS website to administer your portal, calls to the API are being made on the back end. To write scripts that administer Portal for ArcGIS, you need to choose a scripting language that allows you to construct URLs, make HTTP requests, and parse HTTP responses. The examples in this help system use Python.

It's important to note that using the API does not require any Esri software on the machine from which you run the script. All you need is an environment where you can make HTTP requests to your portal.

Getting started with portal administration using the ArcGIS REST API

To use the ArcGIS REST API, you create an HTTP request for the operation you want to perform and include the required parameters for that operation. A simple way to familiarize yourself with the administrative operations available and their required parameters is to use the ArcGIS Portal Directory.

Using the Portal Directory

The ArcGIS Portal Directory is available through two web applications and can help you understand how to write administrative scripts for your portal. The Portal Directory is conceptually similar to the ArcGIS Server Administrator Directory and Services Directory. The available tasks vary between the applications, as described in About the ArcGIS Portal Directory. The URLs to the applications are formatted as follows:

https://webadaptor.domain.com/arcgis/portaladmin
https://webadaptor.domain.com/arcgis/sharing/rest

Think of the Portal Directory as a list of Portal for ArcGIS resources exposed through the REST API. You can navigate the links in the Portal Directory to learn which URLs and parameters to use in your administrative web service requests. You can then formulate these requests and send them over HTTP using a scripting language of your choice.

Try using the Portal Directory to perform an administrative task. Note the parameters you are required to enter, and examine the URL in your browser's address bar as you make the request to the server. Web developer tools such as Fiddler or Firebug can be useful to see the full body of the request and response. This information is extremely valuable when you're attempting to construct your own administrative HTTP requests through Python or another scripting language.

Although you can use the Portal Directory interactively to actually perform administrative tasks, it is best used as a learning tool to help you get familiar with the REST API. The intended web application for portal administration is the Portal for ArcGIS website.

Getting and using a token in scripts

Whenever you administer the portal through its website or Portal Directory, you need to provide the user name and password of an account that has the appropriate privileges to the portal. The same concept applies when you write scripts.

However, unlike accessing the portal website or Portal Directory where your browser will transparently handle the authentication process, you must understand how authentication occurs when using scripts to administer your portal.

If your portal is configured to use built-in accounts and token authentication, you'll be able to use your scripts with the same administrative accounts and URLs that you would use from the Portal Directory. If your portal is configured with enterprise logins and web tier authentication, it is recommended that you have your scripts bypass the Web Adaptor and use the initial administrator account created after installing Portal for ArcGIS.

In either case, the portal returns to you a token, which is a special string of characters that communicates to the portal you have been authenticated to perform certain types of actions. You must include this token in any web service requests you make to the portal.

The following Python function requests a token. The portal's URL, user name, and password are provided as arguments.

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 e

The token does not last forever; it is designed to time out so that it cannot be stolen and used indefinitely by a malicious user. Typically, you have to request a new token each time you run your script (but not each time you make a request). In some exceptional cases, tokens can expire before the execution of your script ends. If your request includes an expired token, the response from the server will include an error indicating that your token has expired. If this occurs, refresh your token and continue the execution of your script.

Working with requests and responses

To make a web service request, you need to formulate the URL for the action you want to take, as well as the required parameters for that action. One of the required parameters on a secured portal is a token like the one generated above.

All administrative actions produce a web service response, which you'll typically request in JavaScript Object Notation (JSON) format. Scripting languages such as Python have libraries that can parse, or read, a JSON response. Sometimes you just want to get the HTTP status code to find out if your request succeeded (for example, a code of 200 means OK). Other times, the response may have data, like log messages, that you want to further parse and examine.

See the various code examples in this help book to understand how you might programmatically send a request to Portal for ArcGIS and work with a response.

5/5/2015