Summary
The ImageSharingDraft class allows you to create a service definition draft file (.sddraft) for a web imagery layer or image service.
Discussion
To create an ImageSharingDraft object, use the CreateSharingDraft function.
- To share a web imagery layer, set the server_type parameter to FEDERATED_SERVER and the service_type parameter to WEB_IMAGERY_LAYER.
- To share an image service, set the server_type parameter to STANDALONE_SERVER and the service_type parameter to IMAGE_SERVICE.
The ImageSharingDraft object can then be configured by setting service- or layer-level properties. Use the targetServer property to specify the server where the image service and web imagery layer will be published.
You can also set image service and web layer properties by modifying the .sddraft file. If no value is specified for a property, the default will be used. You must set the property values even if you are overwriting an image service or web imagery layer that has existing configured properties.
Note:
If metadata properties (credits, description, summary, tags, and useLimitations) are not set or consist of empty strings, the web layer item will source metadata from the data, depending on what is shared.
After the ImageSharingDraft object is configured, it can be saved to a service definition draft file (.sddraft) using the exportToSDDraft method. It can then be staged and shared to either ArcGIS Enterprise or ArcGIS Server using the Stage Service and Upload Service Definition tools.
Code samples are available below for the following:
Properties
| Property | Explanation | Data Type |
| allowAnalysis (Read and Write) | Specifies whether geoprocessing service tools from the Raster Analysis toolbox can access the web imagery layer or image service. | Boolean |
| allowCopy (Read and Write) | Specifies whether the Download Raster geoprocessing service tool can access the web imagery layer or image service. | Boolean |
| allowCompressions (Read and Write) | Specifies the allowable compression methods for the web imagery layer or image service.
| String |
| allowedFields (Read and Write) | The fields that will be transmitted to the client. Provide the fields as a comma-delimited string or a list of strings. | String |
| allowedItemMetadata (Read and Write) | Specifies which metadata items will be transmitted to the client.:
| String |
| allowedMensurationCapabilities (Read and Write) | Specifies the methods that will be derived from the source's mensuration capabilities and listed as part of the dataset's properties. The methods determine the mensuration tools that can be used with the web imagery layer or image service.
| String |
| allowedMosaicMethods (Read and Write) | Specifies the allowable mosaic methods for the web imagery layer or image service.
This property is only applicable to mosaic datasets. | String |
| allowedTemplates (Read and Write) | The server-side raster function names. Provide the fields as a comma-delimited string or a list of strings. | String |
| allowFunction (Read and Write) | Specifies whether clients can access and control the server-side rendering and processing. | Boolean |
| cache.cacheOnDemand (Read and Write) | Specifies whether tiles that are not cached will be created on demand when a client application requests them. The default value is False. | Boolean |
| cache.configuration (Read and Write) | The path and file name of a predefined tiling scheme .xml file generated by the Generate Map Server Cache Tiling Scheme tool. | String |
| cache.exportTiles (Read and Write) | Specifies whether clients will be allowed to download tiles for offline use. The default value is False. | Boolean |
| cache.exportTilesCount (Read and Write) | The maximum number of tiles that can be downloaded in a single request. This property is only honored when the cache.exportTiles property is set to True. The default value is 100000. | Integer |
| cache.useExistingCache (Read and Write) | Specifies whether the data will be drawn from an existing cache. This property is only honored when the enableCache property is set to True. The default value is False. | Boolean |
| cacheControlMaxAge (Read and Write) | The amount of time a browser will be allowed to use a cached response. | Integer |
| colormapToRGB (Read and Write) | Specifies whether a color map in a raster dataset will be published as an RGB image by applying the color map to the image. This impacts the pixel values since the values will be changed from a single value and associated color map to a three-band pixel value. To retain the color map and query the pixel based on its color map, specify False. This property only applies to raster datasets with a color map, or when using a raster dataset layer or mosaic dataset with the Colormap function. | Boolean |
| copyDataToServer (Read and Write) | Specifies whether the data will be copied to the server. A value of True will copy all the data, including data that is registered with your server. A value of False will only copy data that is not registered with your server. Data registered with your server will be referenced by the service. The default value is False. | Boolean |
| credits (Read and Write) | The credits of the web imagery layer or image service. | String |
| defaultCompressionQuality (Read and Write) | The default compression quality. Provide a value from 0 to 100. A value of 80 tends to retain image quality while providing approximately eight times compression. | Integer |
| defaultCompressionTolerance (Read and Write) | The maximum error value that is applicable per pixel, not an average for the image. This value is specified in the units of the mosaic dataset. For example, if the error is 10 centimeters and the mosaic dataset is in meters, use a value of 0.1. | Double |
| defaultResamplingMethod (Read and Write) | Specifies the resampling method that will be used in the request.
| String |
| defaultTemplate (Read and Write) | The default server-side raster function template (RFT) name. | String |
| DEM (Read and Write) | The elevation source that will be used when mensurating. This allows you to make measurements in 3D. | String |
| description (Read and Write) | The description of the web imagery layer or image service. The default value is None. | String |
| downloadDirectory (Read and Write) | The download directory. This property allows you to map the physical directories where the images are located to a virtual directory where the image URLs will be mapped. When allowing download, the service must use a directory that points to the source rasters of the mosaic dataset. This prevents a performance bottleneck that would otherwise occur, as the service copies files from the mosaic dataset source directory to the server output directory. Use this property with the virtualDownloadDirectory property. | String |
| enableCache (Read and Write) | Specifies whether the layer will draw dynamically or from a cache. The default value is False. | Boolean |
| hasLiveData (Read and Write) | Specifies whether the service will reflect data changes. When new rasters are added to the mosaic dataset of a web imagery layer or an image service, the information—such as source resolution, spatial extent, multidimensional information, and time extent—may become outdated. You can restart the service to reflect data changes. If you cannot incur any disruption of the service, set this parameter to True to reflect data changes without restarting the service. Alternatively, run theRefresh Servicecommand to refresh an image service to reflect back-end data changes. | Boolean |
| maxDownloadImageCount (Read and Write) | The maximum number of rasters that a user can download at a time. This property is only applicable to mosaic datasets. | Integer |
| maxDownloadSizeLimit (Read and Write) | The total number of megabytes (MB) that can be downloaded at a time. This property is only applicable to mosaic datasets. | Integer |
| maxImageHeight (Read and Write) | The maximum number of rows that can be used in a client request. | Integer |
| maxImageWidth (Read and Write) | The maximum number of columns that can be used in a client request. | Integer |
| maxMosaicImageCount (Read and Write) | The maximum number of rasters that can be mosaicked per request. This prevents the server from needing to open and perform processing on large numbers of rasters for a single request. | Integer |
| maxRecordCount (Read and Write) | The maximum number of records that will be returned by during querying. The default value is 2000. | Integer |
| maxSampleCount (Read and Write) | The maximum sample count. This generates sample point locations, pixel values, and corresponding spatial resolutions of the source data for a given geometry. By default, the maximum number of sample locations is 1,000. | Integer |
| maxScale (Read and Write) | The denominator of the maximum scale at which caching will be available. Use a value of 0 for a service that is not cached. | Double |
| minScale (Read and Write) | The denominator of the minimum scale at which caching will be available. Use a value of 0 for a service that is not cached. | Double |
| offline (Read and Write) | Specifies whether an offline service definition will be saved.
| Boolean |
| overwriteExistingService (Read and Write) | Specifies whether an existing service with the same name will be overwritten. | Boolean |
| pooling.maxInstances (Read and Write) | The maximum number of instances per machine. This property is only honored when the pooling.type property is set to DEDICATED. | Integer |
| pooling.minInstances (Read and Write) | The minimum number of instances per machine. This property is only honored when the pooling.type property is set to DEDICATED. | Integer |
| pooling.type (Read and Write) | Specifies the type of pooling instance that will be used.
| String |
| portalFolder (Read and Write) | The name of the folder in the portal that will be published. The default folder is the root folder in My Content. This property is only supported when the serverType property is set to FEDERATED_SERVER. | String |
| referenceImage (Read and Write) | The reference raster dataset, mosaic dataset, or raster layer that will be used to georeference the source raster dataset. | String |
| returnJPGPNGAsJPG (Read and Write) | Specifies whether a JPG image will be returned. When you request the image using the JPGPNG format, if there is transparency, a PNG image is returned; otherwise, a JPG image is returned. The PNG image is often much larger than the JPG image and can take longer to transmit. If transparency is not necessary, and you want to ensure that the web imagery layer or image service is always transmitted using a smaller image size, specify True. | Boolean |
| serverFolder (Read and Write) | The name of the server folder where the service will be published. The default folder is the root folder of the server. The folder will be created if it does not exist. | String |
| serverType (Read and Write) | Specifies the server type that was used when the sharing draft was created and is supported for sharing.
| String |
| serviceName (Read Only) | The name of the image service or web imagery layer. This is the name you will see and use to identify the service. The name can only contain alphanumeric characters and underscores. For a web imagery layer, spaces are allowed. For an image service, no spaces or special characters are allowed. The name cannot be more than 120 characters. | String |
| sharing.groups (Read and Write) | The group names, separated by commas. This property is only available when the serverType property is set to FEDERATED_SERVER. | String |
| sharing.sharingLevel (Read and Write) | Specifies the sharing level of the web layer. This property is only available when the serverType property is set to FEDERATED_SERVER.
| String |
| sortField (Read and Write) | The sort field of the default mosaic rule when the allowedMosaicMethods property is set to ByAttribute.. | String |
| sortValue (Read and Write) | The sort base value of the default mosaic rule when the allowedMosaicMethod property is set to ByAttribute. The type depends on the attribute type. | String |
| summary (Read and Write) | The service summary. When a value is provided, this property will override the summary of the dataset or provide a summary when one does not already exist. The summary provided will not be applied to the original dataset. The default value is None. | String |
| tags (Read and Write) | The service tags. When a value is provided, this property will override the tags on the dataset or provide tags when they do not already exist. The tags provided will not be applied to the original dataset. The default value is None. | String |
| targetServer (Read and Write) | The server where the service will be published. This property must be set when the offline property is set to False, which is the default. When the serverType property is set to FEDERATED_SERVER, provide the server URL to the ArcGIS Enterprise portal federated server. When the serverType property is set to STANDALONE_SERVER, the following are supported:
| String |
| useLimitations (Read and Write) | The use limitations of the web layer. | String |
| virtualDownloadDirectory (Read and Write) | The virtual download directory. This property allows you to map the physical directories where the images are located to a virtual directory where the image URLs will be mapped. When allowing download, the service must use a directory that points to the source rasters of the mosaic dataset. This prevents a performance bottleneck that would otherwise occur, as the service copies files from the mosaic dataset source directory to the server output directory. Use this property with the downloadDirectory property. | String |
Method Overview
| Method | Explanation |
| exportToSDDraft (out_sddraft) | Converts an ImageSharingDraft to a service definition draft file (.sddraft). |
Methods
exportToSDDraft (out_sddraft)
| Parameter | Explanation | Data Type |
out_sddraft | The path and file name for the output service definition draft file (.sddraft). | String |
Code sample
The following script creates a web image layer service definition draft file (.sddraft) and sets metadata properties. It is recommended that you register the data location before publishing. If the data location is not registered, the data will be copied to ArcGIS Server. Then the web imagery layer is published to a folder in ArcGIS Enterprise and shared with everyone (public). Portal information is obtained using the SignInToPortal function.
import arcpy
import os
# Sign in to portal
arcpy.SignInToPortal(portal_url="https://organization.example.com/webadaptorname", username="MyUserName", password="MyPassword")
# Set output file names
outdir = r"C:\Project\Output"
service_name = "ImageSharingDraftExample"
sddraft_filename = service_name + ".sddraft"
sddraft_output_filename = os.path.join(outdir, sddraft_filename)
sd_filename = service_name + ".sd"
sd_output_filename = os.path.join(outdir, sd_filename)
datapath = r"C:\Project\data\Raster1.tif"
# Create ImageSharingDraft and set metadata, portal folder, and server folder properties
federated_server_url = "https://gisserver.example.com/webadaptor"
sddraft = arcpy.sharing.CreateSharingDraft(server_type="FEDERATED_SERVER", service_type="WEB_IMAGERY_LAYER",
service_name=service_name, draft_value=datapath)
sddraft.targetServer = federated_server_url
sddraft.credits = "These are credits"
sddraft.description = "This is description"
sddraft.summary = "This is summary"
sddraft.tags = "tag1, tag2"
sddraft.useLimitations = "These are use limitations"
sddraft.portalFolder = "my folder name"
sddraft.serverFolder = "MyServerFolder"
sddraft.sharing.sharingLevel = "EVERYONE"
sddraft.sharing.groups = "" # Group names = "group1,group2"
# Create Service Definition Draft file
sddraft.exportToSDDraft(sddraft_output_filename)
# Stage Service
print("Start Staging")
arcpy.server.StageService(sddraft_output_filename, sd_output_filename)
# Share to portal
print("Start Uploading")
arcpy.server.UploadServiceDefinition(sd_output_filename, federated_server_url)
print("Finish Publishing")The following script creates a service definition draft file (.sddraft) for an image service and sets metadata properties. The image service is published to a folder in a stand-alone ArcGIS Server site.
import arcpy
import os
# Set output file names
outdir = r"C:\Project\Output"
service_name = "ImageSharingDraftExample"
sddraft_filename = service_name + ".sddraft"
sddraft_output_filename = os.path.join(outdir, sddraft_filename)
sd_filename = service_name + ".sd"
sd_output_filename = os.path.join(outdir, sd_filename)
datapath = r"C:\Project\data\Raster2.crf"
# Create ImageSharingDraft and set metadata and server folder properties
target_server_connection = r"C:\Project\gisserver.ags.esri.com (publisher).ags"
sddraft = arcpy.sharing.CreateSharingDraft(server_type="STANDALONE_SERVER", service_type="IMAGE_SERVICE",
service_name=service_name, draft_value=datapath)
sddraft.targetServer = target_server_connection
sddraft.credits = "These are credits"
sddraft.description = "This is description"
sddraft.summary = "This is summary"
sddraft.tags = "tag1, tag2"
sddraft.useLimitations = "These are use limitations"
sddraft.serverFolder = "MyServerFolder"
# Create Service Definition Draft file
sddraft.exportToSDDraft(sddraft_output_filename)
# Stage Service
print("Start Staging")
arcpy.server.StageService(sddraft_output_filename, sd_output_filename)
# Publish to server
print("Start Uploading")
arcpy.server.UploadServiceDefinition(sd_output_filename, target_server_connection)
print("Finish Publishing")The following script overwrites a web imagery layer. If the web imagery layer name already exists, the layer will be overwritten; otherwise, a new layer will be created. If you want the web layer to have specific properties, you must set property values even if the web layer being overwritten already has properties configured. Otherwise, the existing properties will be overwritten with default settings.
import arcpy
import os
# Sign in to portal
arcpy.SignInToPortal(portal_url="https://organization.example.com/webadaptorname", username="MyUserName", password="MyPassword")
# Set output file names
outdir = r"C:\Project\Output"
service_name = "ImageSharingDraftExample"
sddraft_filename = service_name + ".sddraft"
sddraft_output_filename = os.path.join(outdir, sddraft_filename)
sd_filename = service_name + ".sd"
sd_output_filename = os.path.join(outdir, sd_filename)
datapath = r"C:\Project\data\Sample.gdb\Mosaic1"
# Create ImageSharingDraft and set overwrite property
federated_server_url = "https://gisserver.example.com/webadaptor"
sddraft = arcpy.sharing.CreateSharingDraft(server_type="FEDERATED_SERVER", service_type="WEB_IMAGERY_LAYER",
service_name=service_name, draft_value=datapath)
sddraft.targetServer = federated_server_url
sddraft.overwriteExistingService = True
# Create Service Definition Draft file
sddraft.exportToSDDraft(sddraft_output_filename)
# Stage Service
print("Start Staging")
arcpy.server.StageService(sddraft_output_filename, sd_output_filename)
# Share to portal
print("Start Uploading")
arcpy.server.UploadServiceDefinition(sd_output_filename, federated_server_url)
print("Finish Publishing")The following script overwrites an image service. If the service name already exists, the service will be overwritten; otherwise, a new service will be created. If you want the image service to have specific properties, you must set property values even if the image service being overwritten already has properties configured. Otherwise, the existing properties will be overwritten with default settings.
import arcpy
import os
# Set output file names
outdir = r"C:\Project\Output"
service_name = "ImageSharingDraftExample"
sddraft_filename = service_name + ".sddraft"
sddraft_output_filename = os.path.join(outdir, sddraft_filename)
sd_filename = service_name + ".sd"
sd_output_filename = os.path.join(outdir, sd_filename)
datapath = r"C:\Project\data\Sample.gdb\Mosaic2"
# Create ImageSharingDraft and set metadata, and server folder properties
target_server_connection = r"C:\Project\gisserver.ags.esri.com (publisher).ags"
sddraft = arcpy.sharing.CreateSharingDraft(server_type="STANDALONE_SERVER", service_type="IMAGE_SERVICE",
service_name=service_name, draft_value=datapath)
sddraft.targetServer = target_server_connection
sddraft.overwriteExistingService = True
# Create Service Definition Draft file
sddraft.exportToSDDraft(sddraft_output_filename)
# Stage Service
print("Start Staging")
arcpy.server.StageService(sddraft_output_filename, sd_output_filename)
# Share to portal
print("Start Uploading")
arcpy.server.UploadServiceDefinition(sd_output_filename, target_server_connection)
print("Finish Publishing")