ConvertWebMapToMapDocument (arcpy.mapping)

摘要

将要打印或导出的 Web 地图（JSON 格式）转换为地图文档。可在最终打印或导出地图文档之前对其进行进一步修改。

讨论

ArcGIS 支持通过 ArcGIS Web API 打印 Web 地图。ConvertWebMapToMapDocument 函数将您想要打印或导出的 Web 地图转换为地图文档。文档转换后，地图文档中存在 Web 地图的完整状态。例如，服务子图层的属性被传输到文档中地图服务的子图层中。随即可对地图文档进行进一步修改，然后将其最终打印或导出为常用格式（如 PDF）。

ConvertWebMapToMapDocument 函数主要用于需要使用 arcpy.mapping 函数修改 Web 地图的工作流。它用于以不同的分辨率导出 Web 地图，或使用不同的页面大小进行打印，而这些选项在导出 Web 地图地理处理工具中并未提供。可以使用 ConvertWebMapToMapDocument 函数处理的部分工作流示例如下：

如果您已经获取了一个为打印操作而准备地图的 Python 脚本后，可以在地理处理脚本工具中封装该脚本。您随后可将脚本工具作为 ArcGIS Server 地理处理服务发布。每个 ArcGIS Web API 具有一个可用于 Web 应用程序中的打印任务。打印任务具有 URL 属性，该属性指向所创建的地理处理服务的 REST URL。有关使用 ArcGIS Web API 的详细信息，请参阅首选开发人员平台的帮助，地址为 http://resources.arcgis.com/content/web/web-apis。有关地理处理服务的详细信息，请参阅：

什么是地理处理服务？创作和共享地理处理服务快速浏览发布地理处理服务快速浏览地理处理服务的基本词汇
有关在 Web 应用程序中进行打印的详细信息，请参阅：
在 Web 应用程序中打印Web 地图高级打印

使用 ArcGIS Web API 的地理处理服务中的 ConvertWebMapToMapDocument 时，脚本工具的参数名称必须与 Web API 的打印任务参数相匹配：

参数名称

数据类型

说明

Web_Map_as_JSON

字符串

要在地图在 Web 应用程序中显示时导出的地图状态的 JSON 表示。请参阅 ExportWebMap 规范来了解对此文本进行格式化的方式。通过 ArcGIS Web API（针对 JavaScript、Flex、Silverlight 等），开发人员可以从地图中轻松获得此 JSON 字符串。

Output_File

文件

输出文件名。文件扩展名取决于格式参数。

格式

字符串

传送打印用地图影像时所使用的格式。接受以下字符串。

例如：

  • PNG8（参数留空时的默认值）
  • PNG
  • PDF
  • PNG32
  • JPG
  • GIF
  • EPS
  • SVG
  • SVGZ

Layout_Template

字符串

可以是列表中某个模板的名称，也可以是关键字 MAP_ONLY。选择 MAP_ONLY 或传递空字符串时，输出地图不会包含任何页面布局的周围要素（例如切片、图例、比例尺等）。

提示提示:

还可以添加任意数量的附加用户定义参数。将额外的参数传递到自定义打印任务的能力非常有用，它允许您从 Web 应用程序收集任意数量的额外参数，并将其传递到 Python 脚本中。

从 Web 应用程序打印地图时，最常使用的是 ConvertWebMapToMapDocument。当您使用 ArcGIS Web API 的打印任务时，不需要创建 Web 地图 JSON；因为 API 会为您解决这个问题。但是，必须先在本地运行脚本，然后才能将其发布并在 Web API 中进行使用。在本地运行脚本时，可使用任何有效的 Web 地图 JSON 字符串。要成功运行脚本，可能需要与 Web 应用程序将要返回的字符串相类似的 JSON 字符串。请参阅 ExportWebMap 规范来了解对此文本进行格式化的方式。示例字符串如下：

{
    "layoutOptions": {
        "titleText": "Simple WebMap JSON example"
    },
    "operationalLayers": [
        {
            "url": "http://maps1.arcgisonline.com/ArcGIS/rest/services/USA_Federal_Lands/MapServer",
            "visibility": true
        }
    ],
    "exportOptions": {
        "outputSize": [
            1500,
            1500
        ]
    },
    "mapOptions": {
        "extent": {
            "xmin": -13077000,
            "ymin": 4031000,
            "xmax": -13023000,
            "ymax": 4053000
        }
    },
    "version": "1.4"
}

运行脚本工具时，可将 JSON 字符串复制并粘贴到 Web_Map_as_JSON 输入参数中。但是必须删除换行符以确保字符串为有效输入。以下是已删除换行符的 JSON 字符串示例：

{"layoutOptions": {"titleText": "Simple WebMap JSON example"},"operationalLayers": [{"url": "http://maps1.arcgisonline.com/ArcGIS/rest/services/USA_Federal_Lands/MapServer","visibility": true}],"exportOptions": {"outputSize": [1500,1500]},"mapOptions": {"extent": {"xmin": -13077000,"ymin": 4031000,"xmax": -13023000,"ymax": 4053000}},"version": "1.4"}

提示提示:

出于发布目的，由于 ArcGIS Web API 将在 Web 应用程序中提供 Web 地图 JSON，您可将 Web_Map_as_JSON 输入参数留空。如果 Python 脚本的写入方式使其在空白输入时仍能正常执行，则可将 Web_Map_as_JSON 输入参数留空。例如，脚本不会按名称查找 Web 地图图层。如果脚本由于脚本错误在服务器上失败，则必须在本地将其修复，然后重新发布到服务器。因此，在发布前最好在本地确认脚本能够执行，这可以通过测试有效的 web 地图 JSON 字符串或使用包含 web 地图 JSON 中的所有要素的调试地图文档来完成。

提示提示:

如前所述，从 ArcGIS Web API 返回的 JSON 字符串包含 Web 地图的完整状态。JSON 字符串中的 layoutOptions 对象保证了进一步讨论，因为它会自动更新可在 template_mxd 中过渡的布局元素。例如，如果 JSON 具有 titleText 设置，且 template_mxd 具有动态文本标题元素，则模板地图文档布局中的标题将使用 titleText 的值进行更新。有关详细信息，请参阅 ExportWebMap 规范的 layoutOptions 部分。

当您在地理处理服务中封装使用 ConvertWebMapToMapDocument 的 Python 脚本时，您需要确保 ArcGIS for Server 可以看到 Web 应用程序中使用的模板地图文档和数据。最佳做法是使用通过 ArcGIS for Server 注册的文件夹。有关注册数据的详细信息，请参阅：

使数据可供 ArcGIS Server 访问关于将数据注册到 ArcGIS Server使用 ArcGIS for Desktop 将数据注册到 ArcGIS Server

在注册的文件夹中创作模板地图文档时，最佳做法是使用相对路径。这样，ArcGIS for Server 就可以在地图文档位置相对的注册文件夹中找到数据。有关详细信息，请参阅引用地图中的数据。

警告警告:

使用 ConvertWebMapToMapDocument 时，图层的相对路径必须指向 template_mxd 的路径所在级别、之下的级别或之上一层的级别。

警告警告:

如果选择不使用注册的文件夹，那么模板地图文档和数据将打包复制到服务器。在打包过程中，数据可能会移动，并且重新指向 ConvertWebMapToMapDocument 无法解析的文件夹结构的相对路径。因此，建议使用注册的文件夹。

默认情况下，Web 应用程序的注释叠加或客户端图像将存储在内存工作空间中。内存工作空间是临时性的，将在关闭应用程序时被删除。要创建包含注释叠加的输出地图文档的永久复本，请指定 notes_gdb；然后使用合并地图或打包地图地理处理工具来创建输出地图文档的复本。仅当您计划创建输出地图文档的永久复本时，才需要指定 notes_gdb。参阅下面的代码示例 3。如果 Web 地图不包含注释叠加，您可以使用 MapDocument 类的 saveACopy 方法来创建输出地图文档的永久复本。

有关小幅面打印（例如 8.5 x 11）的详细信息，还可参阅打印工具集概述。此工具集包含导出 Web 地图地理处理工具。使用此工具的任务随 ArcGIS for Server 一起安装，并可在启动后使用。导出 Web 地图还支持注释叠加。

请确保阅读下列教程。这些教程演示了使用 ConvertWebMapToMapDocument 工作流进行的完整高质量打印/导出：创作过渡模板地图文档、创作 Python 脚本、创建地理处理服务、创建 Web 应用程序。

语法

ConvertWebMapToMapDocument (webmap_json, {template_mxd}, {notes_gdb}, {extra_conversion_options})
参数说明数据类型
webmap_json

The web map for printing in JavaScript Object Notation (JSON). See the ExportWebMap JSON Specifications for more information.

String
template_mxd

A string representing the path and file name to a map document (.mxd) to use as the template for the page layout. The contents of the web map will be inserted into the data frame that was active at the time the template_mxd was saved. Layers in the template_mxd's active data frame (and all other data frames) will be preserved in the output mapDocument.

(默认值为 None)

String
notes_gdb

A string representing the path to a new or existing file geodatabase or an existing enterprise geodatabase connection where graphic features should be written. This parameter should only be used if graphic features from the web map JSON need to be preserved permanently. In most cases this parameter is not required as a temporary in-memory workspace will be used to store graphic features. This parameter lets you save graphic features to persistent storage, which is essential if you plan to use the map document for operations that require saving or loading from disk (for example, packaging or consolidating). The path must end with a .gdb or .sde extension.

(默认值为 None)

String
extra_conversion_options

A dictionary of credentials for secured services. This parameter is required if the services in the web map JSON require a user name and password to view. Keys accepted in the dictionary are as follows:

  • SERVER_CONNECTION_FILE
  • WMS_CONNECTION_FILE
  • WMTS_CONNECTION_FILE

An example of key value pairs is as follows:

dict = {"SERVER_CONNECTION_FILE":r"Z:\ArcGIS2 on MyServer (user).ags", 
        "WMS_CONNECTION_FILE":r"Z:\USA on MyServer.wms"}
result = arcpy.mapping.ConvertWebMapToMapDocument(json, 
                                                  extra_conversion_options=dict)

(默认值为 None)

Dictionary
返回值
数据类型说明
tuple

返回 Paython 命名的 Web 地图组件和请求的属性的元组：

  • mapDocument —作为函数输出而创建的地图文档对象。
  • DPI —所要求导出的 DPI。
  • outputSizeHeight —输入 Web 地图中指定的图像高度。执行数据视图导出时使用。
  • outputSizeWidth —输入 Web 地图中指定的图像宽度。执行数据视图导出时使用。
警告警告:

ConvertWebMapToMapDocument 将在系统临时文件夹中创建临时地图文档 (.mxd)。在 Windows Vista 和 Windows 7 中，此位置为 C:\Users\<用户名>\AppData\Local\Temp。用户需要负责管理此文件夹中的地图文档。要在脚本中删除这些临时地图文档，请参阅以下代码示例中的 clean up 部分。

代码实例

ConvertWebMapToMapDocument 示例 1

在本示例中，该脚本分别在 Web 地图 JSON、输出格式和模板地图文档中读取。随后将输出地图文档导出为 PDF 或 PNG。

import arcpy
import os
import uuid

# The template location in the registered folder
templatePath = '//MyMachine/Austin/WebMap'

# Input web map json
Web_Map_as_JSON = arcpy.GetParameterAsText(0)

# Format for output
Format = arcpy.GetParameterAsText(1)
if Format == '#' or not Format:
    Format = "PDF" 

# Input Layout template
Layout_Template = arcpy.GetParameterAsText(2)
if Layout_Template == '#' or not Layout_Template:
    Layout_Template = "Landscape11x17" 

# Get the requested map document
templateMxd = os.path.join(templatePath, Layout_Template + '.mxd')

# Convert the web map to a map document
result = arcpy.mapping.ConvertWebMapToMapDocument(Web_Map_as_JSON, templateMxd)
mxd = result.mapDocument

# Use the uuid module to generate a GUID as part of the output name
# This will ensure a unique output name
output = 'WebMap_{}.{}'.format(str(uuid.uuid1()), Format)
Output_File = os.path.join(arcpy.env.scratchFolder, output)

# Export the web map
if Format.lower() == 'pdf':
    arcpy.mapping.ExportToPDF(mxd, Output_File) 
elif Format.lower() == 'png':
    arcpy.mapping.ExportToPNG(mxd, Output_File)

# Set the output parameter to be the output file of the server job
arcpy.SetParameterAsText(3, Output_File)

# Clean up - delete the map document reference
filePath = mxd.filePath
del mxd, result
os.remove(filePath)
ConvertWebMapToMapDocument 示例 2

在本示例中，该脚本分别在 Web 地图 JSON、输出格式和模板地图文档，以及该 Web 地图将附加到的现有 PDF 文档中读取。将 ConvertWebMapToMapDocument 函数中的输出地图文档导出为 PDF，随后使用 PDFDocument 类将其插入到其他 PDF 中。

import arcpy
import os
import uuid

# The template location in the registered folder
templatePath = '//MyMachine/Austin/WebMap'

# Input web map json
Web_Map_as_JSON = arcpy.GetParameterAsText(0)

# Format for output
Format = arcpy.GetParameterAsText(1)
if Format == '#' or not Format:
    Format = "PDF" 

# Input Layout template
Layout_Template = arcpy.GetParameterAsText(2)
if Layout_Template == '#' or not Layout_Template:
    Layout_Template = "Landscape11x17" 
    
PDF_Document = arcpy.GetParameterAsText(3)
if PDF_Document == '#' or not PDF_Document:
    PDF_Document = "EmergencyEvacuationRoute.PDF"

# Get the requested map document
templateMxd = os.path.join(templatePath, Layout_Template + '.mxd')

# Get the requested PDF file 
PDF_File = os.path.join(templatePath, PDF_Document)

# Convert the web map to a map document
result = arcpy.mapping.ConvertWebMapToMapDocument(Web_Map_as_JSON, templateMxd)
mxd = result.mapDocument

# Export the web map to PDF
WebMapPDF = os.path.join(arcpy.env.scratchFolder, 'WebMap.pdf')
arcpy.mapping.ExportToPDF(mxd, WebMapPDF)

# Create a new output PDF Document and append pages
Output_Name = os.path.join(arcpy.env.scratchFolder, 'EvacuationRouteWithWebMap.pdf')
pdfDoc = arcpy.mapping.PDFDocumentCreate(Output_Name)
pdfDoc.appendPages(PDF_File)
pdfDoc.appendPages(WebMapPDF)
pdfDoc.appendPages(os.path.join(templatePath, 'ContactInfo.pdf'))

# Set the output parameter to be the output PDF
arcpy.SetParameterAsText(4, Output_Name)

# Clean up - delete the map document reference
filePath = mxd.filePath
del mxd, result
os.remove(filePath)
ConvertWebMapToMapDocument 示例 3

在本示例中，合并地图地理处理工具用于创建输出地图文档的永久复本，其中包括注释叠加。

import arcpy
import os
import uuid

# The template location in the registered folder
templatePath = '//MyMachine/Austin/WebMap'

# Input web map json
Web_Map_as_JSON = arcpy.GetParameterAsText(0)

# Format for output
Format = arcpy.GetParameterAsText(1)
if Format == '#' or not Format:
    Format = "PDF" 

# Input Layout template
Layout_Template = arcpy.GetParameterAsText(2)
if Layout_Template == '#' or not Layout_Template:
    Layout_Template = "Landscape11x17" 

# Get the requested map document
templateMxd = os.path.join(templatePath, Layout_Template + '.mxd')
    
# Since we are making a permanent copy of the notes overlays, 
# we need to specify a notes geodatabase
notes = os.path.join(arcpy.env.scratchFolder, 'mynotes.gdb')

# Convert the web map to a map document
result = arcpy.mapping.ConvertWebMapToMapDocument(Web_Map_as_JSON, templateMxd, notes)
mxd = result.mapDocument

# Save the web map and notes overlays to a new map document using ConsolidateMap 
arcpy.ConsolidateMap_management(mxd.filePath, 
                                os.path.join(arcpy.env.scratchFolder, 'ConsolidateWebMap'))

# Clean up - delete the map document reference
filePath = mxd.filePath
del mxd, result
os.remove(filePath)
ConvertWebMapToMapDocument 示例 4

在本示例中，使用了一个过渡模板地图文档，其中包含所有可能的服务图层的矢量等效表示。执行 ConvertWebMapToMapDocument 函数后，该脚本对输出地图文档中的所有图层进行循环，从而移除所有图层（与 Web 地图 JSON 中的服务图层相对应的矢量图层除外）。随后将输出地图文档导出为 PDF 或 PNG。

import arcpy
import os
import uuid

# The template location in the registered folder (as UNC path)
templatePath = '//MyComputerName/MyDataStore/USA'

# Input web map json
Web_Map_as_JSON = arcpy.GetParameterAsText(0)

# Format for output
Format = arcpy.GetParameterAsText(1)
if Format == '#' or not Format:
    Format = "PDF" 

# Input Layout template
Layout_Template = arcpy.GetParameterAsText(2)
if Layout_Template == '#' or not Layout_Template:
    Layout_Template = "NorthwesternUSA" 
    
# Get the requested map document
templateMxd = os.path.join(templatePath, Layout_Template + '.mxd')

# Convert the web map to a map document
result = arcpy.mapping.ConvertWebMapToMapDocument(Web_Map_as_JSON, templateMxd)
mxd = result.mapDocument

# Reference the data frame that contains the web map
# Note: ConvertWebMapToMapDocument renames the active dataframe in the template_mxd to "Webmap"
df = arcpy.mapping.ListDataFrames(mxd, 'Webmap')[0]

# Get a list of all service layer names in the map
serviceLayersNames = [slyr.name for slyr in arcpy.mapping.ListLayers(mxd, data_frame=df) 
                      if slyr.isServiceLayer and slyr.visible and not slyr.isGroupLayer]

# Create a list of all possible vector layer names in the map that could have a 
# corresponding service layer
vectorLayersNames = [vlyr.name for vlyr in arcpy.mapping.ListLayers(mxd, data_frame=df) 
                     if not vlyr.isServiceLayer and not vlyr.isGroupLayer]

# Get a list of all vector layers that don't have a corresponding service layer
removeLayerNameList = [vlyrName for vlyrName in vectorLayersNames 
                       if vlyrName not in serviceLayersNames]

# Remove all vector layers that don't have a corresponding service layer
for lyr in arcpy.mapping.ListLayers(mxd, data_frame=df):
    if not lyr.isGroupLayer \
    and not lyr.isServiceLayer \
    and lyr.name in removeLayerNameList \
    and lyr.name in vectorLayersNames:
        arcpy.mapping.RemoveLayer(df, lyr)
                
# Remove all service layers
# This will leave only vector layers that had corresponding service layers
for slyr in arcpy.mapping.ListLayers(mxd, data_frame=df):
    if slyr.isServiceLayer:
        arcpy.mapping.RemoveLayer(df, slyr)
        
# Use the uuid module to generate a GUID as part of the output name
# This will ensure a unique output name
output = 'WebMap_{}.{}'.format(str(uuid.uuid1()), Format)
Output_File = os.path.join(arcpy.env.scratchFolder, output)

# Export the web map
if Format.lower() == 'pdf':
    arcpy.mapping.ExportToPDF(mxd, Output_File) 
elif Format.lower() == 'png':
    arcpy.mapping.ExportToPNG(mxd, Output_File)

# Set the output parameter to be the output file of the server job
arcpy.SetParameterAsText(3, Output_File)

# Clean up - delete the map document reference
filePath = mxd.filePath
del mxd, result
os.remove(filePath)
Copyright © 1995-2013 Esri. All rights reserved.
9/15/2013