Export Map Server Cache (Server)

Summary

Exports tiles from a map image layer cache as a cache dataset or tile package to a folder on disk. The tiles can be imported into other caches, or they can be accessed from ArcGIS Desktop or mobile devices as a raster dataset, independent from their parent service.

Usage

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

• The ArcGIS Server account must have write access to the target cache folder. If the ArcGIS Server account cannot be granted write access to the target cache folder, but the ArcGIS Pro client has write access to it, check the Copy data from server parameter.

• The Overwrite Tiles parameter allows the exported tiles to completely overwrite the tiles in the destination cache, rather than blending the images. Exported tiles can still be constrained to an area of interest.

• When the Ready To Serve Format parameter is checked, the cache content is generated using the open tile package specification. The cache format is Compact V2, but the cache schema is stored in JSON instead of XML. This cache content can be packaged to a zip archive as a tile package for publishing and offline workflows. This cache content is ready to serve using the workflows described in the Publish a tile layer from a cache dataset topic. This parameter is available only when the Export cache type parameter value is Cache dataset.

Parameters

Dialog

Label	Explanation	Data Type
Input Service	The map image layer with the cache tiles to be exported. You can choose it by browsing to the service in a portal or you can drag a web tile layer from the Portal tab in the Project pane to supply this parameter value.	Image Service; Map Server
Target Cache Path	The folder into which the cache will be exported. This folder does not need 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 target cache folder but the ArcGIS Desktop or ArcGIS Pro client has write access to it, check the Copy data from server parameter.	Folder
Export cache type	Specifies the type of cache that will be exported. Tile packages are suitable for use with ArcGIS Maps SDKs for Native Apps. Cache dataset—A map or image service cache that is generated using ArcGIS Server will be exported. It can be used in ArcGIS Desktop and by ArcGIS Server map or image services. This option allows you to generate the content in a ready-to-serve format. This is the default. Tile package—A single compressed file in which the cache dataset is added as a layer and consolidated so that it can be shared will be exported. In can be used in ArcGIS Pro and with ArcGIS Maps SDKs for Native Apps.	String
Copy data from server	Specifies how tiles will be moved to the target folder. Check this parameter only if the ArcGIS Server account cannot be granted write access to the target folder and the ArcGIS Desktop or ArcGIS Pro 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 will first be placed in the server output directory, then moved to the target folder. The ArcGIS Desktop client must have write access to the target folder. Unchecked—Tiles will be 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	Specifies the storage format that will be used for the exported cache. Compact— Tiles will be 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 will be grouped in bundle files only. This format provides better performance on network shares and cloud store directories. If the Export cache type parameter is set to Tile package, the extension of the tile package will be .tpkx, which is supported by recent versions of ArcGIS products such as ArcGIS Online, ArcGIS Enterprise 11.5, ArcGIS Maps SDKs for Native Apps 200.0 or later, and ArcGIS Runtime 100.5-100.15. Exploded—Each tile will be stored as an individual file.	String
Scales	A list of scale levels at which tiles will be exported.	Double
Number of caching service instances (Optional)	The number of instances that will be used to update or generate the tiles. The value for this parameter is set to unlimited (-1) and cannot be modified.	Long
Area Of Interest (Optional)	An area of interest that spatially constrains where tiles will be exported from the cache. This parameter is useful when exporting 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 will be exported.	Feature Set
Export Extent (Optional)	A rectangular extent defining the tiles that will be exported. By default, the extent is set to the full extent of the map service into which you are importing. The optional Area Of Interest parameter allows you to alternatively import using a polygon. It is recommended that you not provide values for both parameters. If values are provided for both parameters, the Area Of Interest parameter takes precedence over this one. Current Display Extent —The extent will be based on the active map or scene. Draw Extent —The extent will be based on a rectangle drawn on the map or scene. Extent of a Layer —The extent will be based on an active map layer. Choose an available layer or use the Extent of data in all layers option. Each map layer has the following options: All Features —The extent of all features. Selected Features —The extent of the selected features. Visible Features —The extent of visible features. Browse —The extent will be based on a dataset. Clipboard —The extent can be copied to and from the clipboard. Copy Extent —Copies the extent and coordinate system to the clipboard. Paste Extent —Pastes the extent and coordinate system from the clipboard. If the clipboard does not include a coordinate system, the extent will use the map’s coordinate system. Reset Extent —The extent will be reset to the default value. When coordinates are manually provided, the coordinates must be numeric values and in the active map's coordinate system. The map may use different display units than the provided coordinates. 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—All pixels in the area of interest will be replaced, 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 will be ignored. This results in a merged or blended image in the destination cache. This is the default.	Boolean
Ready To Serve Format (Optional)	Specifies whether the cache content will be generated using the open tile package specification, and specifies the file format of the cache schema. This parameter is available only when the Export cache type parameter value is Cache dataset. Checked—The cache content will be generated using the open tile package specification. A tile package can be packaged to a zip archive as a tile package for offline workflows. The cache format will be Compact V2, and the cache schema will be stored in JSON format. Unchecked—The cache content will be generated using a schema stored in XML format. Use this option to copy the cache to previous versions of ArcGIS Enterprise. This is the default.	Boolean

Derived Output

Label	Explanation	Data Type
Output Cache Path	The folder into which the cache has been exported.	String

Python

arcpy.server.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}, {ready_to_serve_format})

Name	Explanation	Data Type
input_service	The map image layer with the cache tiles to be exported.	Image Service; Map Server
target_cache_path	The folder into which the cache will be exported. This folder does not need 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 target cache folder but the ArcGIS Desktop or ArcGIS Pro client has write access to it, check the Copy data from server parameter.	Folder
export_cache_type	Specifies the type of cache that will be exported. Tile packages are suitable for use with ArcGIS Maps SDKs for Native Apps. CACHE_DATASET—A map or image service cache that is generated using ArcGIS Server will be exported. It can be used in ArcGIS Desktop and by ArcGIS Server map or image services. This option allows you to generate the content in a ready-to-serve format. This is the default. TILE_PACKAGE—A single compressed file in which the cache dataset is added as a layer and consolidated so that it can be shared will be exported. In can be used in ArcGIS Pro and with ArcGIS Maps SDKs for Native Apps.	String
copy_data_from_server	Specifies how tiles will be moved to the target folder. 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 Pro client has write access to it. The software exports the tiles in the server output directory before moving them to the target folder. COPY_DATA—Tiles will first be placed in the server output directory, then moved to the target folder. The ArcGIS Desktop or ArcGIS Pro client must have write access to the target folder. DO_NOT_COPY—Tiles will be 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	Specifies the storage format that will be used for the exported cache. COMPACT— Tiles will be 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 will be grouped in bundle files only. This format provides better performance on network shares and cloud store directories. If the export_cache_type parameter is set to TILE_PACKAGE, the extension of the tile package will be .tpkx, which is supported by recent versions of ArcGIS products such as ArcGIS Online, ArcGIS Enterprise 11.5, ArcGIS Maps SDKs for Native Apps 200.0 or later, and ArcGIS Runtime 100.5-100.15. EXPLODED—Each tile will be stored as an individual file.	String
scales [scales,...]	A list of scale levels at which tiles will be exported.	Double
num_of_caching_service_instances (Optional)	The number of instances that will be used to update or generate the tiles. The value for this parameter is set to unlimited (-1) and cannot be modified.	Long
area_of_interest (Optional)	An area of interest that spatially constrains where tiles will be exported from the cache. This parameter is useful when exporting 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 will be exported.	Feature Set
export_extent (Optional)	A rectangular extent defining the tiles that will be exported. By default, the extent is set to the full extent of the map service into which you are importing. The optional Area Of Interest parameter allows you to alternatively import using a polygon. It is recommended that you not provide values for both parameters. If values are provided for both parameters, the Area Of Interest parameter takes precedence over this one. 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. OVERWRITE—All pixels in the area of interest will be replaced, effectively overwriting tiles in the destination cache with tiles from the originating cache. MERGE—When the tiles are exported, transparent pixels in the originating cache will be ignored. This results in a merged or blended image in the destination cache. This is the default.	Boolean
ready_to_serve_format (Optional)	Specifies whether the cache content will be generated using the open tile package specification, and specifies the file format of the cache schema. This parameter can be used only when the export_cache_type parameter value is CACHE_DATASET. READY_TO_SERVE_FORMAT—The cache content will be generated using the open tile package specification (https://github.com/Esri/tile-package-spec). A tile package can be packaged to a zip archive as a tile package for offline workflows. The cache format will be Compact V2, and the cache schema will be stored in JSON format. NON_READY_TO_SERVE_FORMAT—The cache content will be generated using a schema stored in XML format. Use this option to copy the cache to previous versions of ArcGIS Enterprise. This is the default.	Boolean

Derived Output

Name	Explanation	Data 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: ExportMapServerCacheTiles.py
# Description: The following stand-alone script demonstrates how to export
# 		cache from a map layer in ArcGIS Enterprise portal,
# 		as CACHE_DATASET in COMPACT_V2 storage format and MERGE tiles
#               using an AREA_OF_INTEREST to TARGET_CACHE_PATH
#		which is accessible to server instances

# Example: This sample script updates map cache tiles.

import arcpy
from arcpy import env
import os, sys, time, datetime, traceback, string
import traceback, sys

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

# Sign in to ArcGIS Enterprise
myPortal= "https://MyPortal.domain.com/portalwebadaptor"
arcpy.SignInToPortal(myPortal, "siteadminValue", "siteadminPassword")
myServer="https://Myserver.domain.com/serverwebadaptor"
serviceName= "SampleWorldCities"
serviceType= "MapServer"
myPortalServiceURL = (myServer + "/" + "rest/services" +"/" + serviceName + "/"
                      + serviceType)



# Stand alone ArcGIS Server
##target_server_connection = r"C:\share\python3\arcgis on MyServer.ags"
##serviceName= "MyServiceName"
##serviceType= ".MapServer"
##myPortalServiceURL = (target_server_connection +  "\\" + serviceName + serviceType)

print (myPortalServiceURL)

#variables for reporting
currentTime = datetime.datetime.now()
arg1 = currentTime.strftime("%H-%M")
arg2 = currentTime.strftime("%Y-%m-%d %H:%M")
file = r'C:\test\report_%s.txt'% arg1


# List of input variables for map or image service 
targetCachePath 	= "C:/data/temp"
exportCacheType 	= "CACHE_DATASET"
copyDataFromServer 	= "DO_NOT_COPY"
storageFormat 		= "COMPACT_V2"
scales 			= [500000,250000,125000,64000]
numOfCachingServiceInstances = "2"
areaOfInterest 		= "C:/data/101/Portland/Metro.shp"
exportExtents 		= ""
overwriteTiles 		= "MERGE"
ready_to_serve_format   = "NON_READY_TO_SERVE_FORMAT"


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

try:
    result = arcpy.server.ExportMapServerCache(myPortalServiceURL, targetCachePath,
                                               exportCacheType,
                                               copyDataFromServer,
                                               storageFormat, scales,
                                               numOfCachingServiceInstances,
                                               areaOfInterest, exportExtents,
					       overwriteTiles,
                                               ready_to_serve_format)
    while result.status < 4:
        time.sleep(0.2)
    resultValue = result.getMessages()
    report.write ("completed " + str(resultValue))

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

ExportMapServerCache example 2 (stand-alone script)

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

# Name: ExportMapServerCacheTiles2.py
# Description: The following stand-alone script demonstrates how to export cache
#               on a map service on standalone server 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 

# Example: This sample script updates map cache tiles.

import arcpy
from arcpy import env
import os, sys, time, datetime, traceback, string
import traceback, sys

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

# Sign in to ArcGIS Enterprise
##myPortal= "https://MyPortal.domain.com/portalwebadaptor"
##arcpy.SignInToPortal(myPortal, "siteadminValue", "siteadminPassword")
##myServer="https://Myserver.domain.com/serverwebadaptor"
##serviceName= "SampleWorldCities"
##serviceType= "MapServer"
##myPortalServiceURL = (myServer + "/" + "rest/services" +"/" + serviceName + "/"
##                      + serviceType)
##

# Stand alone ArcGIS Server
target_server_connection = r"C:\share\python3\arcgis on MyServer.ags"
serviceName= "MyServiceName"
serviceType= ".MapServer"
myPortalServiceURL = (target_server_connection +  "\\" + serviceName + serviceType)

print (myPortalServiceURL)

#variables for reporting
currentTime = datetime.datetime.now()
arg1 = currentTime.strftime("%H-%M")
arg2 = currentTime.strftime("%Y-%m-%d %H:%M")
file = r'C:\test\report_%s.txt'% arg1


# List of input variables for map or image service 
targetCachePath = "C:/temp/usa"
exportCacheType = "TILE_PACKAGE"
copyDataFromServer = "COPY_DATA"
storageFormat = "COMPACT_V2"
scaleValues = [500000,250000,125000,64000]
numOfCachingServiceInstances = "2"
exportExtents = ""
areaOfInterest = ""
overwriteTiles = "MERGE"
ready_to_serve_format = "NON_READY_TO_SERVE_FORMAT"

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

try:
    result = arcpy.server.ExportMapServerCache(inputService, targetCachePath,
                                               exportCacheType,
                                               copyDataFromServer,
                                               storageFormat, scales,
                                               numOfCachingServiceInstances,
                                               areaOfInterest,
                                               exportExtents, overwriteTiles,
                                               ready_to_serve_format)
    while result.status < 4:
        time.sleep(0.2)
    resultValue = result.getMessages()
    report.write ("completed " + str(resultValue))

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

Environments

This tool does not use any geoprocessing environments.

Licensing information

• Basic: Yes
• Standard: Yes
• Advanced: Yes