Import Map Server Cache (Server Tools)

Summary

Imports tiles from a folder on disk into a map image layer cache.

The source folder can be a child of a registered server cache directory, a folder into which a cache has been previously exported, or a tile package (.tpk or .tpkx).The target service must have the same tiling scheme and the storage format as the source cache.

Usage

Use this tool to import all or portions of a cache from one folder to another.
The Overwrite Tiles parameter allows the imported tiles to completely overwrite the existing tiles, rather than blending the images. Imported tiles can still be constrained to an area of interest.
This tool recognizes caches that have been created in a ready-to-serve format, meaning the cache content has been generated using the open tile package specification. Caches generated using a schema stored in XML format are also supported.

Label	Explanation	Data type
Input Service	The map image layer with the cache tiles to be imported. 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 provide this parameter value.	Image Service; Map Server
Source Cache Type	Specifies the type of cache that will be imported to a cached map or image service running on the server. Map or image service cache—A map or image service cache that is generated using ArcGIS Server will be imported. It can be used in ArcGIS Desktop and by ArcGIS Server map or image services. 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 imported. It can be used in ArcGIS Pro and with ArcGIS Maps SDKs for Native Apps.	String
Source Cache Dataset (Optional)	The path to the tiles that will be imported. This is represented by a raster dataset icon when you are browsing. You do not need to specify a registered server cache directory; typically, you'll specify a location on disk where tiles have been previously exported. This location should be accessible to the ArcGIS Server account. If the ArcGIS Server account cannot be granted access to this location, check the Upload data to server parameter.	Raster Dataset
Source Tile Package (Optional)	The path to the tile package (`.tpk` or `.tpkx`) that will be imported. This location should be accessible to the ArcGIS Server account. Importing a tile package file to a cached map or image service automatically enables the Upload data to server parameter.	File
Upload data to server (Optional)	Specifies how tiles will be moved to the server cache directory. Check this parameter if the ArcGIS Server account does not have read access to the source cache. The tool will upload the source cache to the ArcGIS Server uploads directory before moving it to the ArcGIS Server cache directory. Checked—Tiles will first be placed in the server uploads directory, then moved to the server cache directory. This is enabled by default when Source Cache Type is Tile package. Unchecked—Tiles will be imported directly into the server cache directory. The ArcGIS Server account must have read access to the source cache.	Boolean
Scales (Optional)	A list of scale levels at which tiles will be imported. By default, the scales listed on the tool dialog box are between the minimum and maximum cached scales for the service. To update the scale range, go to the Service Editor > Caching tab and use the sliders to update the minimum and maximum cached scales.	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 polygon that spatially constrains where tiles will be imported into the cache. This parameter is useful when importing tiles for irregularly shaped areas, as the tool clips the cache dataset, which intersects the polygon at pixel resolution and imports it to the service cache directory. If you do not provide a value for this parameter, the value of the Import Extent parameter will be used. The default is to use the full extent of the map.	Feature Set
Import Extent (Optional)	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 destination 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 imported, 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

Derived output

Label	Explanation	Data type
Output Map Service URL	The output URL.	String

arcpy.server.ImportMapServerCache(input_service, source_cache_type, {source_cache_dataset}, {source_tile_package}, {upload_data_to_server}, {scales}, {num_of_caching_service_instances}, {area_of_interest}, {import_extent}, {overwrite})

Name	Explanation	Data type
input_service	The map image layer with the cache tiles to be imported.	Image Service; Map Server
source_cache_type	Specifies the type of cache that will be imported to a cached map or image service running on the server. `CACHE_DATASET`—A map or image service cache that is generated using ArcGIS Server will be imported. It can be used in ArcGIS Desktop and by ArcGIS Server map or image services. `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 imported. It can be used in ArcGIS Pro and with ArcGIS Maps SDKs for Native Apps.	String
source_cache_dataset (Optional)	The path to the cache folder matching the data frame name. You do not need to specify a registered server cache directory; typically, you'll specify a location on disk where tiles have been previously exported. This location should be accessible to the ArcGIS Server account. If the ArcGIS Server account cannot be granted access to this location, set the `upload_data_to_server` parameter to `UPLOAD_DATA`.	Raster Dataset
source_tile_package (Optional)	The path to the tile package (`.tpk` or `.tpkx`) that will be imported. This location should be accessible to the ArcGIS Server account. When importing a tile package file to a cached map or image service, the `upload_data_to_server` parameter is ignored, as it is automatically set to `UPLOAD_DATA`.	File
upload_data_to_server (Optional)	Specifies how tiles will be moved to the server cache directory. Set this parameter to `UPLOAD_DATA` if the ArcGIS Server account does not have read access to the source cache. The tool will upload the source cache to the ArcGIS Server uploads directory before moving it to the ArcGIS Server cache directory. `UPLOAD_DATA`—Tiles will first be placed in the server uploads directory, then moved to the server cache directory. This is enabled by default when `source_cache_type` is `TILE_PACKAGE`. `DO_NOT_UPLOAD`—Tiles will be imported directly into the server cache directory. The ArcGIS Server account must have read access to the source cache.	Boolean
scales [scales,...] (Optional)	A list of scale levels at which tiles will be imported.	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 polygon that spatially constrains where tiles will be imported into the cache. This parameter is useful when importing tiles for irregularly shaped areas, as the tool clips the cache dataset, which intersects the polygon at pixel resolution and imports it to the service cache directory. If you do not provide a value for this parameter, the value of the `import_extent` parameter will be used. The default is to use the full extent of the map.	Feature Set
import_extent (Optional)	A rectangular extent defining the tiles that will be imported into the cache. 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 spatially constrain the imported tiles using an irregular shape. If values are provided for both parameters, the Area Of Interest parameter value will be used. A rectangular extent defining the tiles that will be imported into the cache. 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 spatially constrain the imported tiles using an irregular shape. If values are provided for both parameters, the `area_of_interest` parameter value will be used. `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 destination 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 imported, 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

Derived output

Name	Explanation	Data type
out_job_url	The output URL.	String

Code sample

ImportMapServerCache example 1 (stand-alone script)

Import a cache dataset to a cached service for the default number of scales. Tiles in the receiving cache will be overwritten by the tiles being imported.

# Name: ImportMapServerCache.py
# Description: The following stand-alone script demonstrates how to import map
#               server cache from a source directory with CACHE_DATASET and
#               OVERWRITE existing cache on the service for the number
#               of scales specified without Uploading data to server
# Requirements: os, sys, time and traceback modules

# Any line that begins with a pound sign is a comment and will not be run
# 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 sys
import time
import datetime

# 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
sourceCacheType     = "CACHE_DATASET"
sourceCacheDataset  = "C:/data/destination_folder/Layers"
sourceTilePackage   = ""
uploadDataToServer  = "DO_NOT_UPLOAD"
scales              = [500000,250000,125000,64000]
numOfCachingServiceInstances = "2"
areaOfInterest      = ""
importExtents       = ""
overwriteTiles      = "OVERWRITE"

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 "scales[0]","scales[-1]","scales[0:3]"

try:
    starttime = time.clock()
    result = arcpy.server.ImportMapServerCache(inputService, sourceCacheType,
                                               sourceCacheDataset,
                                               sourceTilePackage,
                                               uploadDataToServer, scales,
                                               numOfCachingServiceInstances,
                                               areaOfInterest, importExtents,
                                               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("Imported Map server Cache Tiles successfully for" + serviceName + \
        " from" + sourceCacheDataset + "\n in " + str(elapsedtime)+ "sec 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("Imported Map server Cache Tiles ")

report.close()

ImportMapServerCache example 2 (stand-alone script)

Import cache tiles for an area of interest from a tile package into a cache service.

# Name: ImportMapServerCache.py
# Description: The following stand-alone script demonstrates how to import map
#               server cache from a source directory with Tile Package to an existing service for
#               the default number of scales specified using an AOI by uploading data to remote server
# To Import cache tiles for the scales specified for given feature class

# Requirements: os, sys, time and traceback modules

# Any line that begins with a pound sign is a comment and will not be run
# 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 sys
import time
import datetime

# 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
sourceCacheType = "TILE_PACKAGE"
sourceCacheDataset = ""
sourceTilePackage = "C:\\data\\destination_folder\\TPK\\Rainfall.tpk"
uploadDataToServer = "UPLOAD_DATA"
scales = [500000,250000,125000,64000]
numOfCachingServiceInstances = "2"
cacheDir = "c:\\arcgisserver\\arcgiscache"
areaOfInterest = "C:/data/101/Portland/Portland_Metro.shp"
importExtents = ""
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 "scales[0]","scales[-1]","scales[0:3]"

try:
    starttime = time.clock()
    result = arcpy.server.ImportMapServerCache(inputService, sourceCacheType,
                                               sourceCacheDataset,
                                               sourceTilePackage,
                                               uploadDataToServer, scales,
                                               numOfCachingServiceInstances,
                                               areaOfInterest, importExtents,
                                               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("Imported Map server Cache Tiles successfully for " + serviceName + \
        " from " + sourceTilePackage + " to " + cacheDir + "\n using "+ areaOfInterest + \
        " 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 2 \n" "Line %i" % tb.tb_lineno)
    report.write(str(e))

report.close()

print("Imported Map server Cache Tiles for the given feature class")

Environments

This tool does not use any geoprocessing environments.

Licensing information

Basic: Yes
Standard: Yes
Advanced: Yes

Import Map Server Cache (Server Tools)

Summary

Usage

Parameters

Derived output

Environments

Licensing information

Related topics