Export Map Server Cache (Server)

Summary

Usage

  • Before running this tool, create the folder on disk that will hold the exported tiles.

Parameters

LabelExplanationData Type
Input Service
Image Service; Map Server
Target Cache Path

The folder into which the cache will be exported. This folder does not have to be a registered server cache directory. The ArcGIS Server account must have write access to the target cache folder. If the server account cannot be granted write access to the destination folder but the ArcGIS Desktop or ArcGIS AllSource client has write access to it, choose the Copy data from server parameter.

Folder
Export cache type

Exports a cache as a cache dataset or a tile package. Tile packages are suitable for ArcGIS Runtime and ArcGIS Mobile deployments.

  • Cache datasetA map or image service cache that is generated using ArcGIS Server. It can be used in ArcGIS Desktop and by ArcGIS Server map or image services. This is the default.
  • Tile packageA single compressed file where the cache dataset is added as a layer and consolidated so that it can be shared. In can be used in ArcGIS Desktop, ArcGIS Runtime, and mobile apps.
String
Copy data from server

Check this parameter only if the ArcGIS Server account cannot be granted write access to the target folder and the ArcGIS Desktop or ArcGIS AllSource client has write access to it. The software exports the tiles in the server output directory before moving them to the target folder.

  • Checked—Tiles are placed in the server output directory and are then moved to the target folder. The ArcGIS Desktop client must have write access to the target folder.
  • Unchecked—Tiles are exported directly into the target folder. The ArcGIS Server account must have write access to the target folder.
Boolean
Storage Format Type

The storage format of the exported cache.

  • Compact Tiles are grouped in bundle and bundlex files to save space on disk and allow for faster copying of caches. If the Export cache type parameter is set to Tile package, this is the default.
  • Compact V2 Tiles are grouped in bundle files only. This format provides better performance on network shares and cloudstore directories. If the Export cache type parameter is set to Tile package then the extension of the tile package is (.tpkx),which is supported by newer versions of the ArcGIS Platform such as ArcGIS Online, ArcGIS Enterprise 11.3 and ArcGIS Runtime 100.5.
  • ExplodedEach tile is stored as an individual file (the way caches were stored prior to ArcGIS Server).
String
Scales

A list of scale levels at which tiles will be exported.

Double
Number of caching service instances
(Optional)
Long
Area Of Interest
(Optional)

An area of interest that spatially constrains where tiles are exported from the cache. This parameter is useful if you want to export irregularly shaped areas, as the tool clips the cache dataset at pixel resolution.

If you do not specify an area of interest, the full extent of the map is exported.

Feature Set
Export Extent
(Optional)

A rectangular extent defining the tiles to be exported. By default, the extent is set to the full extent of the map service into which you are importing. Note that the optional parameter on this tool, Area Of Interest, allows you to alternatively import using a polygon. It is recommended that you not provide values for both parameters for a job. If values are provided for both parameters, the Area Of Interest parameter takes precedence over Import Extent.

  • Current Display Extent Map View—The extent will be based on the active map or scene. This option is only available when there is an active map.
  • Draw Extent Draw Extent—The extent will be based on a rectangle drawn on the map or scene. This option will create a feature class in the project geodatabase and add a layer to the map. The feature class will have the same coordinate system as the map.
    Note:

    This option is not available in the Environments dialog box. It is only available from a tool parameter with an extent data type or from the Environments tab on a tool dialog box.

    Note:

    When the Enable and disable editing from the Edit tab editing option is checked, you must enable editing on the Edit ribbon tab to draw the extent.

  • Extent of a Layer Layer—The extent will be based on an active map layer. Use the drop-down list to choose an available layer or use the Extent of data in all layers option to get the combined extent of all active map layers, excluding the basemap. This option is only available when there is an active map with layers.

    Each map layer has the following options:

    • All Features Select All—The extent of all features in the layer.
    • Selected Features Area from Selected Features—The extent of the selected features in the layer.
    • Visible Features Extent Indicator—The extent of the visible features in the layer.
      Note:

      The extents from the Selected Features Area from Selected Features and Visible Features Extent Indicator options are only available for feature layers.

  • Browse Browse—The extent will be based on an existing dataset.
  • Clipboard Paste—The extent can be copied to and pasted from the clipboard.
    • Copy Extent Copy—Copies the extent coordinates and coordinate system to the clipboard.
    • Use Paste Extent Paste—Pastes the extent coordinates and, optionally, the coordinate system from the clipboard. If the clipboard values do not include a coordinate system, the extent will use the map’s coordinate system.
    Note:

    The extent coordinates are copied to and pasted from the clipboard using the same formatting and order as the ArcPy Extent object: x-min, y-min, x-max, y-max, and the spatial reference.

  • Reset Extent Reset—The extent will be reset to the default value.
  • Manually entered coordinates—The coordinates must be numeric values and in the active map's coordinate system.
    Caution:

    The map may use different display units than the entered coordinates. The use of a cardinal direction (N, S, E, W) is not supported. Use a negative value sign for south and west coordinates.

Extent
Overwrite Tiles
(Optional)

Specifies whether the images in the receiving cache will be merged with the tiles from the originating cache or overwritten by them.

  • Checked—The export replaces all pixels in the area of interest, effectively overwriting tiles in the destination cache with tiles from the originating cache.
  • Unchecked—When the tiles are exported, transparent pixels in the originating cache are ignored by default. This results in a merged or blended image in the destination cache. This is the default.
Boolean

Derived Output

LabelExplanationData Type
Output Cache Path

The folder into which the cache has been exported.

String

arcpy.management.ExportMapServerCache(input_service, target_cache_path, export_cache_type, copy_data_from_server, storage_format_type, scales, {num_of_caching_service_instances}, {area_of_interest}, {export_extent}, {overwrite})
NameExplanationData Type
input_service
Image Service; Map Server
target_cache_path

The folder into which the cache will be exported. This folder does not have to be a registered server cache directory. The ArcGIS Server account must have write access to the target cache folder. If the server account cannot be granted write access to the destination folder but the ArcGIS Desktop or ArcGIS AllSource client has write access to it, choose the Copy data from server parameter.

Folder
export_cache_type

Exports a cache as a cache dataset or a tile package. Tile packages are suitable for ArcGIS Runtime and ArcGIS Mobile deployments.

  • CACHE_DATASETA map or image service cache that is generated using ArcGIS Server. It can be used in ArcGIS Desktop and by ArcGIS Server map or image services. This is the default.
  • TILE_PACKAGEA single compressed file where the cache dataset is added as a layer and consolidated so that it can be shared. In can be used in ArcGIS Desktop, ArcGIS Runtime, and mobile apps.
String
copy_data_from_server

Set this parameter to COPY_DATA if the ArcGIS Server account cannot be granted write access to the target folder and the ArcGIS Desktop or ArcGIS AllSource client has write access to it. The software exports the tiles in the server output directory before moving them to the target folder.

  • COPY_DATATiles are placed in the server output directory and are then moved to the target folder. The ArcGIS Desktop or ArcGIS AllSource client must have write access to the target folder.
  • DO_NOT_COPYTiles are exported directly into the target folder. The ArcGIS Server account must have write access to the target folder. This is the default.
Boolean
storage_format_type

The storage format of the exported cache.

  • COMPACT Tiles are grouped in bundle and bundlex files to save space on disk and allow for faster copying of caches. If the export_cache_type parameter is set to Tile package, this is the default.
  • COMPACT_V2 Tiles are grouped in bundle files only. This format provides better performance on network shares and cloudstore directories. If the export_cache_type parameter is set to Tile package then the extension of the tile package is (.tpkx),which is supported by newer versions of the ArcGIS Platform such as ArcGIS Online, ArcGIS Enterprise 11.3 and ArcGIS Runtime 100.5.
  • EXPLODEDEach tile is stored as an individual file (the way caches were stored prior to ArcGIS Server).
String
scales
[scales,...]

A list of scale levels at which tiles will be exported.

Double
num_of_caching_service_instances
(Optional)
Long
area_of_interest
(Optional)

An area of interest that spatially constrains where tiles are exported from the cache. This parameter is useful if you want to export irregularly shaped areas, as the tool clips the cache dataset at pixel resolution.

If you do not specify an area of interest, the full extent of the map is exported.

Feature Set
export_extent
(Optional)

A rectangular extent defining the tiles to be exported. By default, the extent is set to the full extent of the map service into which you are importing. Note that the optional parameter on this tool, Area Of Interest, allows you to alternatively import using a polygon. It is recommended that you not provide values for both parameters for a job. If values are provided for both parameters, the Area Of Interest parameter takes precedence over Import Extent.

  • MAXOF—The maximum extent of all inputs will be used.
  • MINOF—The minimum area common to all inputs will be used.
  • DISPLAY—The extent is equal to the visible display.
  • Layer name—The extent of the specified layer will be used.
  • Extent object—The extent of the specified object will be used.
  • Space delimited string of coordinates—The extent of the specified string will be used. Coordinates are expressed in the order of x-min, y-min, x-max, y-max.
Extent
overwrite
(Optional)

Specifies whether the images in the receiving cache will be merged with the tiles from the originating cache or overwritten by them.

  • OVERWRITEThe export replaces all pixels in the area of interest, effectively overwriting tiles in the destination cache with tiles from the originating cache.
  • MERGEWhen the tiles are imported, transparent pixels in the originating cache are ignored by default. This results in a merged or blended image in the destination cache. This is the default.
Boolean

Derived Output

NameExplanationData Type
output_cache_path

The folder into which the cache has been exported.

String

Code sample

ExportMapServerCache example 1 (stand-alone script)

Export cache tiles for a feature class while changing the storage format from EXPLODED to COMPACT.

# Name: ExportMapServerCache.py for ArcGIS Server
# Description: The following stand-alone script demonstrates how to export
# 		cache as CACHE_DATASET in COMPACT storage format and MERGE tiles
#               using an AREA_OF_INTEREST to TARGET_CACHE_PATH
#		which is accessible to server instances
# Requirements: os, sys, time and traceback modules

# Any line that begins with a pound sign is a comment and will not be executed
# Empty quotes take the default value.
# To accept arguments from the command line replace values of variables to
#                                                           "sys.argv[]"

# Import system modules
import arcpy
from arcpy import env
import os, sys, time, datetime, traceback, string

# Set environment settings
env.workspace = "C:/data"

# List of input variables for map service properties
connectionFile = r"C:\Users\<username>\AppData\Roaming\ESRI\Desktop10.1\ArcCatalog"
server 			= "arcgis on MyServer_6080 (publisher)"
serviceName 		= "Rainfall.MapServer"
inputService 		= connectionFile + "\\" + server + "\\" + serviceName
targetCachePath 	= "C:/data/temp"
exportCacheType 	= "CACHE_DATASET"
copyDataFromServer 	= "DO_NOT_COPY"
storageFormat 		= "COMPACT"
scales 			= [500000,250000,125000,64000]
numOfCachingServiceInstances = "2"
areaOfInterest 		= "C:/data/101/Portland/Metro.shp"
exportExtents 		= ""
overwriteTiles 		= "MERGE"

currentTime = datetime.datetime.now()
arg1 	= currentTime.strftime("%H-%M")
arg2 	= currentTime.strftime("%Y-%m-%d %H:%M")
file 	= 'C:/data/report_%s.txt' % arg1

# print results of the script to a report
report = open(file,'w')

# use "scaleValues[0]","scaleValues[-1]","scaleValues[0:3]"

# Enter rectangular custom extent values for the "exportExtents" variable to
# constrain the exporting cache along the rectangular extents

try:
    starttime = time.clock()
    result = arcpy.server.ExportMapServerCache(inputService, targetCachePath,
                                               exportCacheType,
                                               copyDataFromServer,
                                               storageFormat, scales,
                                               numOfCachingServiceInstances,
                                               areaOfInterest, exportExtents,
					       overwriteTiles)
    finishtime = time.clock()
    elapsedtime = finishtime - starttime

    #print messages to a file
    while result.status < 4:
        time.sleep(0.2)
    resultValue = result.getMessages()
    report.write ("completed " + str(resultValue))

    print("Exported cache successfully for mapservice " + serviceName + \
        " to " + targetCachePath + "\n using " + areaOfInterest + "\n in " + \
        str(elapsedtime) + " sec \n on " + arg2)

except Exception as e:
    # If an error occurred, print line number and error message
    tb = sys.exc_info()[2]
    report.write("Failed at \n" "Line %i" % tb.tb_lineno)
    report.write(str(e))

print("Exported Map server Cache  using area of Interest")

report.close()
ExportMapServerCache example 2 (stand-alone script)

Export cache as a TILE_PACKAGE when the destination folder is inaccessible to ArcGIS Server instances.

# Name: ExportMapServerCache.py
# Description: The following stand-alone script demonstrates how to export cache
#               as TILE_PACKAGE for default number of scales of a service, to a
#               TARGET_CACHE_PATH which is inaccessible to server instances using
#               COPY_DATA_FROM_SERVER
# Requirements: os, sys, time and traceback modules

# Any line that begins with a pound sign is a comment and will not be executed
# Empty quotes take the default value.
# To accept arguments from the command line replace values of variables to
#                                                           "sys.argv[]"

# Import system modules
import arcpy
from arcpy import env
import os, sys, time, datetime, traceback, string

# Set environment settings
env.workspace = "C:/data"

# List of input variables for map service properties
connectionFile = r"C:\Users\<username>\AppData\Roaming\ESRI\Desktop10.1\ArcCatalog"
server = "arcgis on MyServer_6080 (publisher)"
serviceName = "Rainfall.MapServer"
inputService = connectionFile + "\\" + server + "\\" + serviceName
targetCachePath = "C:/temp/usa"
exportCacheType = "TILE_PACKAGE"
copyDataFromServer = "COPY_DATA"
storageFormat = "COMPACT"
scaleValues = [500000,250000,125000,64000]
numOfCachingServiceInstances = "2"
exportExtents = ""
areaOfInterest = ""
overwriteTiles = "MERGE"

currentTime = datetime.datetime.now()
arg1 = currentTime.strftime("%H-%M")
arg2 = currentTime.strftime("%Y-%m-%d %H:%M")
file = 'C:/data/report_%s.txt' % arg1

# print results of the script to a report
report = open(file,'w')

# use "scaleValues[0]","scaleValues[-1]","scaleValues[0:3]"

try:
    starttime = time.clock()
    result = arcpy.server.ExportMapServerCache(inputService, targetCachePath,
                                               exportCacheType,
                                               copyDataFromServer,
                                               storageFormat, scales,
                                               numOfCachingServiceInstances,
                                               areaOfInterest,
                                               exportExtents, overwriteTiles)
    finishtime = time.clock()
    elapsedtime = finishtime - starttime

    #print messages to a file
    while result.status < 4:
        time.sleep(0.2)
    resultValue = result.getMessages()
    report.write ("completed " + str(resultValue))

    print("Exported cache successfully for mapservice " + serviceName + " to " + \
        targetCachePath + " in " + str(elapsedtime) + " sec \n on" + arg2)

except Exception as e:
    # If an error occurred, print line number and error message
    tb = sys.exc_info()[2]
    report.write("Failed at step 1 \n" "Line %i" % tb.tb_lineno)
    report.write(str(e))

print("Exported Map server Cache ")

report.close()

Environments

This tool does not use any geoprocessing environments.