arcgis.gis.server module

A collection of classes for administering an ArcGIS Enterprise server.

Server

class arcgis.gis.server.Server(url, gis=None, **kwargs)

Bases: arcgis.gis.server._common._base.BaseServer

An ArcGIS Enterprise server used for hosting services.

Argument Description
url

Required string. The web address to the ArcGIS Server administration end point.

Example: https://mysite.com/arcgis/admin

The URL should be formatted as follows: <scheme>://<host>:<port (optional)>/<web adapter>/admin
gis Optional string. The GIS object to which this Server is federated with.
Optional Argument Description
baseurl Optional string. The root URL to a site. Example: https://mysite.com/arcgis
tokenurl Optional string. Used when a site is federated or when the token URL differs from the site’s baseurl. If a site is federated, the token URL will return as the Portal token and ArcGIS Server users will not validate correctly.
username Optional string. The login username for BUILT-IN security.
password Optional string. A secret word or phrase that must be used to gain access to the account above.
key_file Optional string. The path to PKI key file.
cert_file Optional string. The path to PKI cert file.
proxy_host

Optional string. The web address to the proxy host.

Example: proxy.mysite.com
proxy_port Optional integer. The port where the proxy resides on, default is 80.
expiration Optional integer. This is the length of time a token is valid for. Example 1440 is one week. The Default is 60.
all_ssl Optional boolean. If True, all calls will be made over HTTPS instead of HTTP. The default is False.
portal_connection Optional string. This is used when a site is federated. It is the ArcGIS Online or Portal GIS object used.
initialize Optional boolean. If True, the object will attempt to reach out to the URL resource and populate at creation time. The default is False.
content

Gets the Services Directory which can help you discover information about services available on a particular server. A service represents a local GIS resource whose functionality has been made available on the server to a wider audience. For example, an ArcGIS Server administrator can publish an ArcMap document (.mxd) as a map service. Developers and clients can display the map service and query its contents.

The Services Directory is available as part of the REST services infrastructure available with ArcGIS Server installations. It enables you to list the services available, including secured services when you provide a proper login. For each service, a set of general properties are displayed. For map services, these properties include the spatial extent, spatial reference (coordinate system) and supported operations. Layers are also listed, with links to details about layers, which includes layer fields and extent. The Services Directory can execute simple queries on layers.

The Services Directory is also useful for finding information about non-map service types. For example, you can use the Services Directory to determine the required address format for a geocode service, or the necessary model inputs for a geoprocessing service.

datastores

Gets the information about the data holdings of the server. Data items are used by ArcGIS for Desktop and other clients to validate data paths referenced by GIS services. You can register new data items with the server by using the Register Data Item operation. Use the Find Data Items operation to search through the hierarchy of data items. A relational data store type represents a database platform that has been registered for use on a portal’s hosting server by the ArcGIS Server administrator. Each relational data store type describes the properties ArcGIS Server requires in order to connect to an instance of a database for a particular platform. At least one registered relational data store type is required before client applications such as Insights for ArcGIS can create Relational Database Connection portal items. The Compute Ref Count operation counts and lists all references to a specific data item. This operation helps you determine if a particular data item can be safely deleted or refreshed.

logs

Gives users access the ArcGIS Server’s logs and lets administrators query and find errors and/or problems related to the server or a service.

Logs are the records written by the various components of ArcGIS Server. You can query the logs and change various log settings. Note ArcGIS Server Only

machines

Gets the list of server machines registered with the site. This resource represents a collection of all the server machines that have been registered with the site. It other words, it represents the total computing power of your site. A site will continue to run as long as there is one server machine online. For a server machine to start hosting GIS services, it must be grouped (or clustered). When you create a new site, a cluster called ‘default’ is created for you. The list of server machines in your site can be dynamic. You can register additional server machines when you need to increase the computing power of your site or unregister them if you no longer need them.

publish_sd(sd_file, folder=None)

Publishes a service definition file to ArcGIS Server.

Argument Description
sd_file Required string. The service definition file to be uploaded and published.
folder Optional string. The folder in which to publish the service definition file to. If this folder is not present, it will be created. The default is None in which case the service definition will be published to the System folder.
Returns:A boolean indicating success (True) or failure (False).
services

Gives the administrator access to the services on ArcGIS Server as a ServerManager Object.

site

Gets the site’s collection of server resources. This collection includes server machines that are installed with ArcGIS Server, including GIS services, data and so on. The site resource also lists the current version of the software. When you install ArcGIS Server on a server machine for the first time, you must create a new site. Subsequently, newer server machines can join your site and increase its computing power. Once a site is no longer required, you can delete the site, which will cause all of the resources to be cleaned up.

system

Provides access to common system configuration settings.

usage

Gets the collection of all the usage reports created within your site. The Create Usage Report operation lets you define a new usage report.

users

Gets operations to work with users.

ServicesDirectory

class arcgis.gis.server.catalog.ServicesDirectory(url, username=None, password=None, key_file=None, cert_file=None, verify_cert=False, **kwargs)

Bases: arcgis.gis.server._common._base.BaseServer

Provides ArcGIS Server Services Directory access.

The Services Directory allows you to browse the contents of an ArcGIS Server and obtain information that can be useful to endusers for developing applications, performing analysis, or cataloging services. The ServicesDirectory is a view of the ArcGIS Server REST API in a python class.

With the Services Directory, you can do the following:
  • Browse the contents of the GIS Server and get service-level metadata
  • Navigate a series of links to view information about the services on your GIS Server.
  • Get information to help you develop applications

When you develop applications with the Python API, you must provide URLs to services and the layers and functionality they expose. The Services Directory provides an interactive way for you to construct those URLs.

The Services Directory works using REST. REST is an architectural style that allows ArcGIS Server to reveal a hierarchy of information about itself through endpoints, or URLs. When you use the Services Directory, you navigate through a series of links to discover information about the server. Each time you click a link, you see a new page that reveals additional information about what’s available on the server. The information that you see on the page is retrieved through REST using the page’s URL.

Arguments Description
url

string required. The web address to the ArcGIS Server administration end point.

Example: https://mysite.com/arcgis

The URL should be formatted as follows: <scheme>://<host>:<port (optional)>/<web adapter>
baseurl optional string, the root URL to a site. Example: https://mysite.com/arcgis
tokenurl optional string. Used when a site if federated or when the token URL differs from the site’s baseurl. If a site is federated, the token URL will return as the Portal token and ArcGIS Server users will not validate correctly.
username optional string, login username for BUILT-IN security
password optional string, a secret word or phrase that must be used to gain access to the account above.
key_file optional string, path to PKI ket file
cert_file optional string, path to PKI cert file
proxy_host

optional string, web address to the proxy host

Example: proxy.mysite.com
proxy_port optional integer, default is 80. The port where the proxy resided on
expiration optional integer. The Default is 60. This is the length of time a token is valid for. Example 1440 is one week.
all_ssl optional boolean. The default is False. If True, all calls will be made over HTTPS instead of HTTP.
portal_connection optional GIS. This is used when a site is federated. It is the ArcGIS Online or Portal GIS object used.
initialize optional boolean. The default is False. If True, the object will attempt to reach out to the URL resource and populate at creation time.
find(service_name, folder=None)

finds a service based on it’s name in a given folder

folders

returns a list of server folders

get(name, folder=None)

returns a single service in a folder

list(folder=None)

returns a list of services at the given folder

report(as_html=True, folder=None)

Generates a table list of Services in the given folder

Service

class arcgis.gis.server.Service(url, gis, initialize=False, **kwargs)

Bases: arcgis.gis.server._common._base.BaseServer

Represents a GIS administrative service

(This should not be created by a user)

delete()

deletes a service from arcgis server

edit(service)

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.

rename(new_name)

Renames this service to the new name

restart()

restarts the current service

start()

starts the specific service

statistics

returns the stats for the service

status

returns the status of the service

stop()

stops the current service

Machine

class arcgis.gis.server.Machine(url, gis, initialize=False)

Bases: arcgis.gis.server._common._base.BaseServer

A server machine represents a machine on which ArcGIS Server software has been installed and licensed. A site is made up one or more of such machines that work together to host GIS services and data and provide administrative capabilities for the site. Each server machine is capable of performing all these tasks and hence a site can be thought of as a distributed peer-to-peer network of such machines. A server machine communicates with its peers over a range of TCP and UDP ports that can be configured using the edit operation. For a server machine to host GIS services, it needs to be added to a cluster. Starting and stopping the server machine enables and disables, respectively, its ability to host GIS services. The administrative capabilities of the server machine are available through the ArcGIS Server Administrator API that can be accessed over HTTP(S). For a server machine to participate in a site, it must be registered with the site. A machine can participate in only one site at a time. To remove a machine permanently from the site, you can use the unregister operation.
Parameters:
url:web address of the machine
gis:GIS or Server object
initialize:default False, if True, the properties are loaded at

creation

export_certificate(certificate)

A certificate represents a key pair that has been digitally signed and acknowledged by a Certifying Authority (CA). It is the most fundamental component in enabling SSL on your server. The Generate Certificate operation creates a new self-signed certificate and adds it to the keystore. In order for browsers and other HTTP client applications to trust the SSL connection on the server, this certificate must be digitally signed by a CA and then imported into the keystore. Even though a self-signed certificate can be used to enable SSL, it is recommended that you use a self-signed certificates only on staging or development servers.

Parameters:
certificate:name of the certificate to grab information for
generate_CSR(certificate)

This operation generates a certificate signing request (CSR) for a self-signed certificate. A CSR is required by a CA to create a digitally signed version of your certificate. Parameters:

certificate:name of the certificate to grab information for
import_CA_signed_certificate(certificate, ca_signed_certificate)
Parameters:
certificate:name of the certificate to grab information for
ca_signed_certificate:
 The multi-part POST parameter containing the signed certificate file.
import_existing_server_certificate(alias, cert_password, cert_file)

This operation imports an existing server certificate, stored in the PKCS #12 format, into the keystore. If the certificate is a CA signed certificate, you must first import the CA Root or Intermediate certificate using the importRootCertificate operation.

Parameters:
alias:A unique name for the certificate that easily identifies it.
cert_password:password to unlock the file containing the certificate
cert_file:multi-part POST parameter containing the certificate file
import_root_certificate(alias, root_CA_certificate)

This operation imports a certificate authority (CA)’s root and intermediate certificates into the keystore. To create a production quality CA-signed certificate, you need to add the CA’s certificates into the keystore that enables the SSL mechanism to trust the CA (and the certificates it has signed). While most of the popular CA’s certificates are already available in the keystore, you can use this operation if you have a custom CA or specific intermediate certificates.

Parameters:
alias:name of teh certificate
:root_CA_certificate:multi-part POST parameter containing the
certificate file.
ssl_certificate(certificate)

A certificate represents a key pair that has been digitally signed and acknowledged by a Certifying Authority (CA). It is the most fundamental component in enabling SSL on your server. The Generate Certificate operation creates a new self-signed certificate and adds it to the keystore. In order for browsers and other HTTP client applications to trust the SSL connection on the server, this certificate must be digitally signed by a CA and then imported into the keystore. Even though a self-signed certificate can be used to enable SSL, it is recommended that you use a self-signed certificates only on staging or development servers.

Parameters:
certificate:name of the certificate to grab information for
ssl_certificates

This resource lists all the certificates (self-signed and CA-signed) created for the server machine. The server securely stores these certificates inside a key store within the configuration store. Before you enable SSL on your server, you need to generate certificates and get them signed by a trusted certificate authority (CA). For your convenience, the server is capable of generating self-signed certificates that can be used during development or staging. However, it is critical that you get CA-signed certificates when standing up a production server. In order to get a certificate signed by a CA, you need to generate a CSR (certificate signing request) and then submit it to your CA. The CA will sign your certificate request which can then be imported into the server by using the import CA signed certificate operation.

start()

Starts the server machine

status

returns the state

stop()

Stops the server machine

unregister()

This operation causes the server machine to be deleted from the Site. The server machine will no longer participate in the site or run any of the GIS services. All resources that were acquired by the server machine (memory, files, and so forth) will be released. Typically, you should only invoke this operation if the machine is going to be shut down for extended periods of time or if it is being upgraded. Once a machine has been unregistered, you can create a new site or join an existing site.

Report

class arcgis.gis.server.Report(url, gis, initialize=False)

Bases: arcgis.gis.server._common._base.BaseServer

(This class should not be created by a user)

A Single Usage Report returned by ArcGIS Server

A Usage Report is used to obtain ArcGIS Server usage data for specified resources during a given time period. It specifies the parameters for obtaining server usage data, time range (since from and to parameters), aggregation interval, and queries (which specify the metrics to be gathered for a collection of server resources, such as folders and services).

delete()

deletes the current report

edit()

Edits the usage report. To edit a usage report, you need to submit the complete JSON representation of the usage report which includes updates to the usage report properties. The name of the report cannot be changed when editing the usage report.

Values are changed in the class, to edit a property like metrics, pass in a new value. Changed values to not take until the edit() is called.

Inputs:
None
query(query_filter=None)

Retrieves server usage data for the report. This operation aggregates and filters server usage statistics for the entire ArcGIS Server site. The report data is aggregated in a time slice, which is obtained by dividing up the time duration by the default (or specified) aggregationInterval parameter in the report. Each time slice is represented by a timestamp, which represents the ending period of that time slice. In the JSON response, the queried data is returned for each metric- resource URI combination in a query. In the report-data section, the queried data is represented as an array of numerical values. A response of null indicates that data is not available or requests were not logged for that metric in the corresponding time-slice.

Inputs:
query_filter - The report data can be filtered by the machine

where the data is generated. The filter accepts a comma separated list of machine names; * represents all machines.

Examples:
# filters for the specified machines {“machines”: [“WIN-85VQ4T2LR5N”, “WIN-239486728937”]} # no filtering; all machines are accepted {“machines”: “*”}

Datastore

class arcgis.gis.server.Datastore(datastore, path, datadict=None, **kwargs)

Bases: arcgis.gis.server._common._base.BaseServer

Represents a Single Datastore in DataStoreManager

datasets

Returns the datasets in the data store (currently implemented for big data file shares.)

delete()

Unregisters this data item from the data store

hints

This returns the hints resource for a big data file share. Hints are advanced parameters to control the generation of Manifest.

manifest

The manifest resource for bigdata fileshares,

ref_count

The total number of references to this data item that exist on the server. You can use this property to determine if this data item can be safely deleted (or taken down for maintenance).

update(item)

Edits this data item to update its connection information.

Input
item - the dict representation of the updated item
Output:
True if successful
validate()

Validates that this data item’s path (for file shares) or connection string (for databases) is accessible to every server node in the site

Output:
True if successful

User

class arcgis.gis.server.User(usermanager, user_dict)

Bases: dict

Individual User Account

add_role(role_name)

You must use this operation to assign roles to a user account when working with an user and role store that supports reads and writes. By assigning a role to a user, the user account automatically inherits all the permissions that have been assigned to the role.

Parameter:
role:role name to assign to current user
delete()

deletes the current user account

update(password=None, full_name=None, description=None, email=None)

Updates a user account in the user store

Parameters:
username - the name of the user. The name must be unique in
the user store.

password - the password for this user. fullname - an optional full name for the user. description - an optional field to add comments or description

for the user account.

email - an optional email for the user account.

Role

class arcgis.gis.server.Role(rolemanager, roledict)

Bases: dict

represents a single role on server

(This is should not be created by a user)

delete()

deletes the current role

grant(username)

Adds a user to the current role

Parmeters Description
username required string, account name to add to the role
Returns:boolean, True means added, False means could not add to Role
set_privileges(privilage)

Administrative access to ArcGIS Server is modeled as three broad tiers of privileges:

ADMINISTER-A role that possesses this privilege has unrestricted
administrative access to ArcGIS Server.
PUBLISH-A role with PUBLISH privilege can only publish GIS
services to ArcGIS Server.
ACCESS-No administrative access. A role with this privilege can
only be granted permission to access one or more GIS services.

By assigning these privileges to one or more roles in the role store, ArcGIS Server’s security model supports role-based access control to its administrative functionality. These privilege assignments are stored independent of ArcGIS Server’s role store. As a result, you don’t need to update your enterprise identity stores (like Active Directory).

update(description=None)

Updates a role in the role store with new information. This operation is available only when the role store is a read-write store such as the default ArcGIS Server store.

Parameters:
description:An optional field to add comments or a description for the role
Output:
status dictionary

ServerManager

class arcgis.gis.server.ServerManager(gis)

Bases: object

Helper class for managing your ArcGIS Servers. This class is not created by users directly. An instance of this class, called ‘servers’, is available as a property of the gis.admin object. Administrators call methods on this ‘gis.admin.servers’ object to manage and interrogate ArcGIS Servers.

get(role=None, function=None)

Retrieves the ArcGIS Server(s) by role or function. While each argument is optional, at least one argument must be set with an allowed value other than None.

Argument Description
role Optional string. Limits the returned ArcGIS Servers based on the server’s role as either a hosting server for the portal, a federated server, or a server with restricted access to publishing. The allowed values are HOSTING_SERVER, FEDERATED_SERVER, or FEDERATED_SERVER_WITH_RESTRICTED_PUBLISHING, respectively.
function Optional string. Limits the returned ArcGIS Servers based on the server’s function. Provide a comma-separated list of values. The allowed values are GeoAnalytics, RasterAnalytics, and ImageHosting.
Returns:The ArcGIS Server(s) discovered that match the criteria.
list()

Retrieves all servers in a GIS.

Returns:A list of all servers found in the GIS.
update(server, role, function=None)

This operation allows you to set an ArcGIS Server federated with Portal for ArcGIS as the hosting server or to enforce fine-grained access control to a federated server. You can also remove hosting server status from an ArcGIS Server. To set a hosting server, an enterprise geodatabase must be registered as a managed database with the ArcGIS Server.

Returns:A status message of ‘success’ with the ID of the ArcGIS Server.
validate()

This operation returns information on the status of ArcGIS Servers registered with Portal for ArcGIS.

Returns:True if all servers are functioning as expected, False if there is an issue with 1 or more of the Federated Servers.

ServiceManager

class arcgis.gis.server.ServiceManager(url, gis, initialize=False, sm=None)

Bases: arcgis.gis.server._common._base.BaseServer

Helper class for managing services. This class is not created by users directly. An instance of this class, called ‘services’, is available as a property of the Server object. Users call methods on this ‘services’ object to managing services.

create_folder(folder_name, description='')

Creates a unique folder name on AGS Inputs:

folder_name - name of folder on AGS description - describes the folder
Output:
JSON message as dictionary
create_service(service)

Creates a new GIS service in the folder. A service is created by submitting a JSON representation of the service to this operation.

The JSON representation of a service contains the following four sections:

  • Service Description Properties-Common properties that are shared
by all service types. Typically, they identify a specific service.
  • Service Framework Properties-Properties targeted towards the
framework that hosts the GIS service. They define the life cycle and load balancing of the service.
  • Service Type Properties -Properties targeted towards the core
service type as seen by the server administrator. Since these properties are associated with a server object, they vary across the service types. The Service Types section in the Help describes the supported properties for each service.
  • Extension Properties-Represent the extensions that are enabled
on the service. The Extension Types section in the Help describes the supported out-of-the-box extensions for each service type.
Output:
dictionary status message
delete_folder(folder_name)

deletes a folder on AGS Inputs:

folder_name - name of folder to remove
Output:
boolean
exists(folder_name, name=None, service_type=None)

This operation allows you to check whether a folder or a service exists. To test if a folder exists, supply only a folder_name. To test if a service exists in a root folder, supply both serviceName and service_type with folder_name=None. To test if a service exists in a folder, supply all three parameters.

Inputs:

folder_name - a folder name name - a service name service_type - a service type. Allowed values:

GeometryServer | ImageServer | MapServer | GeocodeServer | GeoDataServer | GPServer | GlobeServer | SearchServer
folders

returns a list of all folders

list(folder=None, refresh=True)

returns a list of services in the specified folder

Parameters: :param folder: name of the folder to list services from :param refresh: Bool, default is False. If True, the list of services will be requested to the server, else the list will be returned from cache.

publish_sd(sd_file, folder=None)

publishes a service definition file to arcgis server

MachineManager

class arcgis.gis.server.MachineManager(url, gis, initialize=False)

Bases: arcgis.gis.server._common._base.BaseServer

This resource represents a collection of all the server machines that have been registered with the site. It other words, it represents the total computing power of your site. A site will continue to run as long as there is one server machine online. For a server machine to start hosting GIS services, it must be grouped (or clustered). When you create a new site, a cluster called ‘default’ is created for you. The list of server machines in your site can be dynamic. You can register additional server machines when you need to increase the computing power of your site or unregister them if you no longer need them.

get(machine_name)

returns a machine object for a given machine Parameters:

param machine_name:
 name of the server

example >>> machines_obj.get(“SERVER.DOMAIN.COM”)

list()

returns the list of machines in the cluster

register(name, admin_url)

For a server machine to participate in a site, it needs to be registered with the site. The server machine must have ArcGIS Server software installed and authorized. Registering machines this way is a “pull” approach to growing the site and is a convenient way when a large number of machines need to be added to a site. In contrast, a server machine can choose to join a site. Inputs:

name - name of the server machine admin_url - URL wher ethe Administrator API is running on the

server machine. Example: http://<machineName>:6080/arcgis/admin
Output:
JSON message as dictionary
rename(name, new_name)

You must use this operation if one of the registered machines has undergone a name change. This operation updates any references to the former machine configuration. By default, when the server is restarted, it is capable of identifying a name change and repairing itself and all its references. This operation is a manual call to handle the machine name change. Input:

name - The former name of the server machine that is
registered with the site.

new_name - The new name of the server machine.

Output:
JSON messages as dictionary

LogManager

class arcgis.gis.server.LogManager(url, gis, initialize=False)

Bases: arcgis.gis.server._common._base.BaseServer

Log Mangement of a server

This resource is accessed through by administrators to check on error messages.

clean()

Deletes all the log files on all server machines in the site.

count_error_reports(machine='*')

This operation counts the number of error reports (crash reports) that have been generated on each machine. Input:

machine - name of the machine in the cluster. * means all
machines. This is default
Output:
dictionary with report count and machine name
edit(level='WARNING', log_dir=None, max_age=90, max_report_count=10)

The log settings are for the entire site. Inputs:

level - Can be one of [OFF, SEVERE, WARNING, INFO, FINE,
VERBOSE, DEBUG].

log_dir - File path to the root of the log directory max_age - number of days that a server should save a log

file.
ax_report_count - maximum number of error report files
per machine
query(start_time=None, end_time=None, since_server_start=False, level='WARNING', services='*', machines='*', server='*', codes=None, process_IDs=None, export=False, export_type='CSV', out_path=None)

The query operation on the logs resource provides a way to aggregate, filter, and page through logs across the entire site. Inputs:

settings

returns the current log settings

ReportManager

class arcgis.gis.server.ReportManager(url, gis, initialize=False)

Bases: arcgis.gis.server._common._base.BaseServer

Manages and modifies the usage reports for ArcGIS Server

create(reportname, queries, metadata=None, since='LAST_DAY', from_value=None, to_value=None, aggregation_interval=None)

Creates a new usage report. A usage report is created by submitting a JSON representation of the usage report to this operation.

Inputs:

reportname - the unique name of the report since - the time duration of the report. The supported values

are: LAST_DAY, LAST_WEEK, LAST_MONTH, LAST_YEAR, CUSTOM LAST_DAY represents a time range spanning the previous 24

hours.
LAST_WEEK represents a time range spanning the previous 7
days.
LAST_MONTH represents a time range spanning the previous 30
days.
LAST_YEAR represents a time range spanning the previous 365
days.
CUSTOM represents a time range that is specified using the
from and to parameters.
from_value - optional value - The timestamp (milliseconds since
UNIX epoch, namely January 1, 1970, 00:00:00 GMT) for the beginning period of the report. Only valid when since is CUSTOM
to_value - optional value - The timestamp (milliseconds since
UNIX epoch, namely January 1, 1970, 00:00:00 GMT) for the ending period of the report.Only valid when since is CUSTOM.
aggregation_interval - Optional. Aggregation interval in minutes.

Server metrics are aggregated and returned for time slices aggregated using the specified aggregation interval. The time range for the report, specified using the since parameter (and from and to when since is CUSTOM) is split into multiple slices, each covering an aggregation interval. Server metrics are then aggregated for each time slice and returned as data points in the report data. When the aggregation_interval is not specified, the following defaults are used:

LAST_DAY: 30 minutes LAST_WEEK: 4 hours LAST_MONTH: 24 hours LAST_YEAR: 1 week CUSTOM: 30 minutes up to 1 day, 4 hours up to 1 week, 1 day up to 30 days, and 1 week for longer periods.

If the interval specified in Usage Reports Settings is more than the aggregationInterval, the interval is used instead.

queries - A list of queries for which to generate the report.

You need to specify the list as an array of JSON objects representing the queries. Each query specifies the list of metrics to be queries for a given set of resourceURIs. The queries parameter has the following sub-parameters:

resourceURIs - Comma separated list of resource URIs for which to report metrics. Specifies services or folders for which to gather metrics.

The resourceURI is formatted as below:

services/ - Entire Site services/Folder/ - Folder within a Site. Reports

metrics aggregated across all services within that Folder and Sub-Folders.
services/Folder/ServiceName.ServiceType - Service in
a specified folder, for example: services/Map_bv_999.MapServer.
services/ServiceName.ServiceType - Service in the
root folder, for example: Map_bv_999.MapServer.
metrics - Comma separated list of metrics to be reported.
Supported metrics are:

RequestCount - the number of requests received RequestsFailed - the number of requests that failed RequestsTimedOut - the number of requests that timed out RequestMaxResponseTime - the maximum response time RequestAvgResponseTime - the average response time ServiceActiveInstances - the maximum number of active

(running) service instances sampled at 1 minute intervals, for a specified service
metadata - Can be any JSON Object. Typically used for storing
presentation tier data for the usage report, such as report title, colors, line-styles, etc. Also used to denote visibility in ArcGIS Server Manager for reports created with the Administrator Directory. To make any report created in the Administrator Directory visible to Manager, include “managerReport”:true in the metadata JSON object. When this value is not set (default), reports are not visible in Manager. This behavior can be extended to any client that wants to interact with the Administrator Directory. Any user-created value will need to be processed by the client.

Example: >>> queryObj = [{

“resourceURIs”: [“services/Map_bv_999.MapServer”], “metrics”: [“RequestCount”]

}] >>> obj.createReport(

reportname=”SampleReport”, queries=queryObj, metadata=”This could be any String or JSON Object.”, since=”LAST_DAY”

)

edit(interval, enabled=True, max_history=0)

The usage reports settings are applied to the entire site. A POST request updates the usage reports settings.

Inputs:
interval - Defines the duration (in minutes) for which
the usage statistics are aggregated or sampled, in-memory, before being written out to the statistics database.
enabled - default True - Can be true or false. When usage
reports are enabled, service usage statistics are collected and persisted to a statistics database. When usage reports are disabled, the statistics are not collected.
max_history - default 0 - Represents the number of days after
which usage statistics are deleted after the statistics database. If the max_history parameter is set to 0, the statistics are persisted forever.
list()

returns a list of reports on the server

quick_report(since='LAST_WEEK', queries='services/', metrics='RequestsFailed')

The operation quick_report generates an on the fly usage report for a service, services, or folder.

Parameters:
since - the time duration of the report. The supported values

are: LAST_DAY, LAST_WEEK, LAST_MONTH, LAST_YEAR, CUSTOM LAST_DAY represents a time range spanning the previous 24

hours.

LAST_WEEK represents a time range spanning the previous 7

days.

LAST_MONTH represents a time range spanning the previous 30

days.

LAST_YEAR represents a time range spanning the previous 365

days.

CUSTOM represents a time range that is specified using the

from and to parameters.

queries - A list of queries for which to generate the report.

You need to specify the list as an array of JSON objects representing the queries. Each query specifies the list of metrics to be queries for a given set of resourceURIs. The queries parameter has the following sub-parameters:

resourceURIs - Comma separated list of resource URIs for which to report metrics. Specifies services or folders for which to gather metrics.

The resourceURI is formatted as below:

services/ - Entire Site services/Folder/ - Folder within a Site. Reports

metrics aggregated across all services within that Folder and Sub-Folders.

services/Folder/ServiceName.ServiceType - Service in

a specified folder, for example: services/Map_bv_999.MapServer.

services/ServiceName.ServiceType - Service in the

root folder, for example: Map_bv_999.MapServer.

metrics - Comma separated list of metrics to be reported.
Supported metrics are:

RequestCount - the number of requests received RequestsFailed - the number of requests that failed RequestsTimedOut - the number of requests that timed out RequestMaxResponseTime - the maximum response time RequestAvgResponseTime - the average response time ServiceActiveInstances - the maximum number of active (running) service instances sampled at 1 minute intervals, for a specified service

Output:Python dictionary of data on a successful query.
settings

The usage reports settings are applied to the entire site. A GET request returns the current usage reports settings. When usage reports are enabled, service usage statistics are collected and persisted to a statistics database. When usage reports are disabled, the statistics are not collected. The interval parameter defines the duration (in minutes) during which the usage statistics are sampled or aggregated (in-memory) before being written out to the statistics database. Database entries are deleted after the interval specified in the max_history parameter ( in days), unless the max_history parameter is 0, for which the statistics are persisted forever.

DataStoreManager

class arcgis.gis.server.DataStoreManager(url, gis=None, **kwargs)

Bases: arcgis.gis.server._common._base.BaseServer

This resource provides information about the data holdings of the server. Data items are used by ArcGIS for Desktop and other clients to validate data paths referenced by GIS services.

You can register new data items with the server by using the Register Data Item operation. Use the Find Data Items operation to search through the hierarchy of data items.

A relational data store type represents a database platform that has been registered for use on a portal’s hosting server by the ArcGIS Server administrator. Each relational data store type describes the properties ArcGIS Server requires in order to connect to an instance of a database for a particular platform. At least one registered relational data store type is required before client applications such as Insights for ArcGIS can create Relational Database Connection portal items.

The Compute Ref Count operation counts and lists all references to a specific data item. This operation helps you determine if a particular data item can be safely deleted or refreshed.

Parameters:
param url:URL to the Data Store URL
param gis:GIS, Server, or ServicesDirectory object
add(name, item)

Registers a new data item with the data store. Input

Output:
True if the data item is registered successfully, False otherwise
add_bigdata(name, server_path=None)

Registers a bigdata fileshare with the data store. Input

name - unique bigdata fileshare name on the server server_path - the path to the folder from the server
Output:
the data item if registered successfully, None otherwise
add_database(name, conn_str, client_conn_str=None, conn_type='shared')

Registers a database with the data store. Input

name - unique database name on the server conn_str - the path to the folder from the server (and client, if shared or serverOnly database) client_conn_str: connection string for client to connect to replicated enterprise database> conn_type - “<shared|replicated|serverOnly>”
Output:
the data item is registered successfully, None otherwise
add_folder(name, server_path, client_path=None)

Registers a folder with the data store. Input

name - unique fileshare name on the server server_path - the path to the folder from the server (and client, if shared path) client_path - if folder is replicated, the path to the folder from the client if folder is shared, don’t set this parameter
Output:
the data item is registered successfully, None otherwise
config

The data store configuration properties affect the behavior of the data holdings of the server. The properties include: blockDataCopy - When this property is false, or not set at all, copying data to the site when publishing services from a client application is allowed. This is the default behavior. When this property is true, the client application is not allowed to copy data to the site when publishing. Rather, the publisher is required to register data items through which the service being published can reference data. Values: true | false

data_items

This resource lists data items that are the root of all other data items in the data store.

get(path)

Returns the data item object at the given path

Arguments
path:required string, the data item path
Returns:None if the data item is not found at that path and the data item object if its found
get_relational_datastore_type(type_id)

This resource lists the properties of a registered relational data store type. The properties returned are those that client applications must provide when creating a Relational Database Connection portal item.

Parameters:
type_id:datastore type id
get_total_refcount(path)

Computes the total number of references to a given data item that exist on the server. You can use this operation to determine if a data resource can be safely deleted (or taken down for maintenance). Input:

path - The complete hierarchical path to the item
Output:
JSON message as dictionary
list()

returns a list of datastore objects

make_datastore_machine_primary(item_name, machine_name)

Promotes a standby machine to the primary Data Store machine. The existing primary machine is downgraded to a standby machine.

Parameters:
item_name:name of the data store item
machine_name:name of the machine to promote to primary
make_primary(datastore_name, machine_name)

Promotes a standby machine to the primary Data Store machine. The existing primary machine is downgraded to a standby machine.

relational_datastore_types

This resource lists the relational data store types that have been registered with the server. Each registered relational data store type has both an id and a name property, as well as an array of userDefinedProperties, which indicates the properties client applications must provide when creating a Relational Database Connection portal item. Only administrators can register and unregister a relational data store type. The following database platforms are supported: SAP HANA, Microsoft SQL Server and Teradata.

remove_datastore_machine(item_name, machine_name)

Removes a standby machine from the Data Store. This operation is not supported on the primary Data Store machine.

Inputs:
item_name - name of the data store item machine_name - name of the machine to remove
search(parent_path=None, ancestor_path=None, types=None, id=None)

You can use this operation to search through the various data items registered in the server’s data store. Inputs:

parent_path - The path of the parent under which to find items ancestor_path - The path of the ancestor under which to find

items.

types - A filter for the type of the items id - A filter to search by the ID of the item

Output:
dictionary
start(item_name, machine_name)

Starts the database instance running on the Data Store machine.

Inputs:
item_name - name of the item to start machine_name - name of the machine to start on
stop(item_name, machine_name)

Stop the database instance running on the Data Store machine.

Inputs:
item_name - name of the item to stop machine_name - name of the machine to stop on
validate()

validates all the items in the datastore

validate_egdb(data_store_name, name)

Checks the status of ArcGIS Data Store and provides a health check response.

Inputs:
data_store_namee - name of the datastore name - name of the machine

UserManager

class arcgis.gis.server.UserManager(url, gis, initialize=False)

Bases: arcgis.gis.server._common._base.BaseServer

This resource represents all users available in the user store that can administer ArcGIS Server and access the GIS services hosted on the server. In short, it represents the complete user space. As the user space could be potentially large, there isn’t any listing of users, but you can use Get Users or Search operations to access their account information. ArcGIS Server is capable of connecting to your enterprise identity stores such as Active Directory or other directory services exposed through the LDAP protocol. Such identity stores are treated as read only, and ArcGIS Server does not attempt to update them. As a result, operations that need to update the identity store (such as adding users, removing users, updating users, assigning roles and removing assigned roles) are not supported when identity stores are read only. On the other hand, you could configure your ArcGIS Server to use the default identity store (shipped with the server) which is treated as a read-write store. The total numbers of users are returned in the response.

Note:
Typically, this resource must be accessed over an HTTPS connection.
create(username, password, fullname=None, description=None, email=None)

Add a user account to the user store Parameters:

username - The name of the user. The name must be unique in
the user store.

password - The password for this user fullname - an optional full name for the user description - an option field to add comments or description

for the user account

email - an optional email for the user account

get(username)
finds a users
Parameters:
username:name of the user to find
Ouput:
User object
me

Gets the user object as the current logged in user. If the username cannot be found, for example, the site administrator account, then just the username is returned.

roles

Helper object to manage custom roles for users

search(username, max_results=25)

You can use this operation to search a specific user or a group of users from the user store. The size of the search result can be controlled with the max_results parameter.

Parameters:
username:user or users to find
max_results:integer value of the maximum number of users to

return

Output:
list of User objects

RoleManager

class arcgis.gis.server.RoleManager(url, gis, initialize=False)

Bases: arcgis.gis.server._common._base.BaseServer

This resource represents all roles available in the role store. The ArcGIS Server security model supports a role-based access control in which each role can be assigned certain permissions (privileges) to access one or more resources. Users are assigned to these roles. The server then authorizes each requesting user based on all the roles assigned to the user. As the role space could be potentially large, you can use the paged Get Roles operation to iterate through the list of roles, or you can use the Search Roles operation to search for a specific role. ArcGIS Server is capable of connecting to your enterprise identity stores such as Active Directory or other directory services exposed via the LDAP protocol. Such identity stores are treated as read-only stores and ArcGIS Server does not attempt to update them. As a result, operations that need to update the role store (such as adding roles, removing roles, updating roles) are not supported when the role store is read-only. On the other hand, you can configure your ArcGIS Server to use the default role store shipped with the server, which is treated as a read-write store.

all(start_index=0, page_size=10)

This operation gives you a pageable view of roles in the role store. It is intended for iterating through all available role accounts. To search for specific role accounts instead, use the Search Roles operation. Parameters:

start_index - The starting index (zero-based) from the roles
list that must be returned in the result page. The default is 0.
page_size - The maximum number of roles to return in the
result page. The default size is 10.
Output:
returns JSON messages as dictionary
count

returns the number of roles for AGS

create(name, description='')

Adds a role to the role store. This operation is available only when the role store is a read-write store such as the default ArcGIS Server store. If the name of the role exists in the role store, an error will be returned. Parameters:

rolename - The name of the role. The name must be unique in the
role store.
description - An optional field to add comments or a
description for the role.
Output:
JSON message as dictionary
get_role(role_id=None, max_count=10)

You can use this operation to search a specific role or a group of roles from the role store. The size of the search results can be controlled with the max_count parameter. Parameters:

role_filter - a filter string to search for the roles max_count - maximum size of the result
Ouput:
JSON message as dictionary

SystemManager

class arcgis.gis.server.SystemManager(url, gis, initialize=False)

Bases: arcgis.gis.server._common._base.BaseServer

The System resource is a collection of miscellaneous server-wide resources such as server properties, server directories, the configuration store, Web Adaptors, and licenses.

clear_cache()

This operation clears the cache on all REST handlers in the system. While the server typically manages the REST cache for you, use this operation to get explicit control over the cache.

configuration_store

returns the ConfigurationStore object for this site

deployment

ArcGIS Server has a deployment configuration resource that can control the load balancing functionality between GIS server machines:

singleClusterMode-At 10.4, in large sites with a single cluster, the site is configured to prevent load balancing between GIS server machines. This reduces network traffic between machines in the site and helps reduce load on your network. The default is true for new installations of ArcGIS Server, meaning that load balancing is disabled. Upgrades from earlier versions will set this property to true if the site uses a single cluster. Sites with multiple clusters cannot use singleClusterMode. To prevent load balancing, the following criteria must be met:

  • All machines in the site must participate in a single cluster. Multiple clusters cannot exist.
  • An external load balancer or ArcGIS Web Adaptor must be
configured to forward requests to the site. If no external gateway exists, requests will only be handled by the machine designated in the request.

To enable load balancing, set this property to false. Updating this property will restart all machines in the site.

directories()

returns the server directory object in a list

handlers

A handler exposes the GIS capabilities of ArcGIS Server through a specific interface/API. There are two types of handlers currently available in the server:

Rest-Exposes the REST-ful API Soap-Exposes the SOAP API

The Rest Handler resource exposes some of the administrative operations on the REST handler such as clearing the cache.

jobs

get the Jobs object

licenses

The licenses resource lists the current license level of ArcGIS for Server and all authorized extensions. Contact Esri Customer Service if you have questions about license levels or expiration properties.

rest_handler

Provides a list of resources accessible throught the REST API

server_properties

gets the server properties for the site as an object

unregister_webadaptor(wa_id)

Unregistering a Web Adaptor removes the Web Adaptor from the server’s trusted list. The Web Adaptor can no longer submit requests to the server.

update_web_adaptor(wa_id, description, http_port, https_port)

This operation allows you to update the description, HTTP port, and HTTPS port of a Web Adaptor that is registered with the server.

Note This operation is only meant to change the descriptive properties of the Web Adaptor and does not affect the configuration of the web server that deploys your Web Adaptor.

Parameters:
wa_id:web adaptor id
description:descriptive text
http_port:The HTTP port of the web server
https_port:the HTTPS (SSL) port of the web server
update_web_adaptors_configuration(config)

You can use this operation to change the configuration parameters and shared key.

Inputs:
config - the sharedkey attribute must always be
present in this JSON
web_adaptors

This property lists all the Web Adaptors that have been registered with the site. The server will trust all these Web Adaptors and will authorize calls from these servers. To configure a new Web Adaptor with the server, you’ll need to use the configuration web page or the command line utility. For full instructions, see Configuring the Web Adaptor after installation.

web_adaptors_configuration

The Web Adaptors configuration is a resource for all the configuration parameters shared across all the Web Adaptors in the site. Most importantly, this resource lists the shared key that is used by all the Web Adaptors to encrypt key data bits in the incoming requests to the server.

SiteManager

class arcgis.gis.server.SiteManager(server, initialize=False)

Bases: object

A site is a collection of server resources. This collection includes server machines that are installed with ArcGIS Server, including GIS services, data and so on. The site resource also lists the current version of the software. When you install ArcGIS Server on a server machine for the first time, you must create a new site. Subsequently, newer server machines can join your site and increase its computing power. Once a site is no longer required, you can delete the site, which will cause all of the resources to be cleaned up.

Parameters:
server:arcgis.gis.server object
create(username, password, config_store_connection, directories, cluster=None, logs_settings=None, run_async=False)

This is the first operation that you must invoke when you install ArcGIS Server for the first time. Creating a new site involves:

-Allocating a store to save the site configuration -Configuring the server machine and registering it with the site -Creating a new cluster configuration that includes the server

machine

-Configuring server directories -Deploying the services that are marked to auto-deploy

Because of the sheer number of tasks, it usually takes a little while for this operation to complete. Once a site has been created, you can publish GIS services and deploy them to your server machines.

Parameters:
username - The name of the administrative account to be used by
the site. This can be changed at a later stage.

password - The credentials of the administrative account. configStoreConnection - A JSON object representing the

connection to the configuration store. By default, the configuration store will be maintained in the ArcGIS Server installation directory.
directories - A JSON object representing a collection of server
directories to create. By default, the server directories will be created locally.
cluster - An optional cluster configuration. By default, the
site will create a cluster called ‘default’ with the first available port numbers starting from 4004.

logsSettings - Optional log settings. runAsync - A flag to indicate if the operation needs to be run

asynchronously. Values: true | false
delete()

Deletes the site configuration and releases all server resources. This is an unrecoverable operation. This operation is well suited for development or test servers that need to be cleaned up regularly. It can also be performed prior to uninstall. Use caution with this option because it deletes all services, settings, and other configurations. This operation performs the following tasks:

  • Stops all server machines participating in the site. This in turn stops all GIS services hosted on the server machines.
  • All services and cluster configurations are deleted.
  • All server machines are unregistered from the site.
  • All server machines are unregistered from the site.
  • The configuration store is deleted.
export(location=None)

Exports the site configuration to a location you specify as input to this operation.

Parameters:
location - A path to a folder accessible to the server where the
exported site configuration will be written. If a location is not specified, the server writes the exported site configuration file to directory owned by the server and returns a virtual path (an HTTP URL) to that location from where it can be downloaded.
import_site(location)

This operation imports a site configuration into the currently running site. Importing a site means replacing all site configurations (including GIS services, security configurations, and so on) of the currently running site with those contained in the site configuration file you supply as input. The input site configuration file can be obtained through the exportSite operation. This operation will restore all information included in the backup, as noted in exportSite. When it is complete, this operation returns a report as the response. You should review this report and fix any problems it lists to ensure your site is fully functioning again. The importSite operation lets you restore your site from a backup that you created using the exportSite operation.

Parameters:
location - A file path to an exported configuration or an ID
referencing the stored configuration on the server.
join(admin_url, username, password)

The Join Site operation is used to connect a server machine to an existing site. This is considered a ‘push’ mechanism, in which a server machine pushes its configuration to the site. For the operation to be successful, you need to provide an account with administrative privileges to the site. When an attempt is made to join a site, the site validates the administrative credentials, then returns connection information about its configuration store back to the server machine. The server machine then uses the connection information to work with the configuration store. If this is the first server machine in your site, use the Create Site operation instead.

Parameters:
admin_url - The site URL of the currently live site. This is
typically the Administrator Directory URL of one of the server machines of a site.

username - The name of an administrative account for the site. password - The password of the administrative account.

properties

returns the site

public_key

gets the public key

upgrade(run_async=False)

This is the first operation that must be invoked during an ArcGIS Server upgrade. Once the new software version has been installed and the setup has completed, this operation will be available. A successful run of this operation will complete the upgrade of ArcGIS Server.

caution If errors are returned with the upgrade operation, you must address the errors before you may continue. For example, if you encounter an error about an invalid license, you will need to re-authorize the software using a valid license and you may then retry this operation.

note This operation is available only when a server machine is currently being upgraded. It will not be available after a successful upgrade of a server machine.

Paramters:
run_async:A flag to indicate if the operation needs to be run asynchronously. The default value is false.

DirectoryManager

class arcgis.gis.server.DirectoryManager(system)

Bases: object

A collection of all the server directories is listed under this resource. You can add a new directory using the Register Directory operation. You can then configure GIS services to use one or more of these directories. If you no longer need the server directory, you must remove the directory by using the Unregister Directory operation.

add(name, physicalPath, directoryType, maxFileAge, cleanupMode='NONE', description=None)

Registers a new server directory. While registering the server directory, you can also specify the directory’s cleanup parameters

Parameters:
name:The name of the server directory.
physicalPath:The absolute physical path of the server directory.
directoryType:The type of server directory.
cleanupMode:Defines if files in the server directory needs to be cleaned up.
maxFileAge:Defines how long a file in the directory needs to be kept before it is deleted.
description:An optional description for the server directory.
all()

Server directories are used by GIS services as a location to output items such as map images, tile caches, and geoprocessing results. In addition, some directories contain configurations that power the GIS services.

edit_services_directory(allowedOrigins, arcgis_com_map, arcgis_com_map_text, jsapi_arcgis, jsapi_arcgis_css, jsapi_arcgis_css2, jsapi_arcgis_sdk, serviceDirEnabled)

With this operation you can enable or disable the HTML view of ArcGIS REST API (also known as the Services Directory). You can also adjust the JavaScript and map viewer previews of services in the Services Directory so that they work with your own locally hosted JavaScript API and map viewer.

Parameters:
allowedOrigins:Comma-separated list of URLs of domains allowed to make requests. * can be used to denote all domains.
arcgis_com_map:URL of the map viewer application used for service previews. Defaults to the ArcGIS.com map viewer but could be used to point at your own Portal for ArcGIS map viewer.
arcgis_com_map_text:
 
jsapi_arcgis:The URL of the JavaScript API to use for service previews. Defaults to the online ArcGIS API for JavaScript, but could be pointed at your own locally-installed instance of the JavaScript API.
jsapi_arcgis_css:
 CSS file associated with the ArcGIS API for JavaScript. Defaults to the online Dojo tundra.css.
:jsapi_arcgis_css2:Additional CSS file associated with the ArcGIS
API for JavaScript. Defaults to the online esri.css.
jsapi_arcgis_sdk:
 URL of the ArcGIS API for JavaScript help.
serviceDirEnabled:
 Flag to enable/disable the HTML view of the services directory.
get(name)

Gets a single directory registered with ArcGIS Server

Parameters:
name:name of the registered directory