地理处理服务示例:获取行进方向

需要 Network Analyst 许可。

项目说明

用途

针对给定出行模式生成输入点之间的行进方向。本示例将介绍如何创作、发布和使用可以执行网络分析的地理处理服务。

服务

TravelDirections(地理处理服务)

Web 工具

GetTravelDirections

输入

  • 代表停靠点的两个或多个数字化点(必填)
  • 用于计算方向的出行模式(必填)
  • 表示路径开始时间的日期-时间值(可选)

输出

具有行进方向和路径形状的要素类

Data

ToolData 文件夹中提供的加利福尼亚州圣地亚哥地区的街道网络数据集

最低 ArcGIS 软件要求

  • 具有 Network Analyst 扩展模块的 ArcGIS Pro 3.1 或更高版本
  • 具有 Network Analyst 扩展模块的 ArcGIS Server 10.8.0 或更高版本

注释

演示创作、发布和使用 web 工具以基于出行模式生成行进方向所需的基本步骤。您可以按照类似的步骤为其他类型的交通网络分析创建 Web 工具,例如围绕一组设施点生成行驶时间区域。

示例详细信息

GetTravelDirections 工具

GetTravelDirections 工具的主要用途是基于给定的出行模式生成用户指定点周围的行进方向。该工具可创建输出线要素类,以显示输入点之间的最佳路径以及包含导航路径所需的行进方向的文本。

下表显示了由 GetTravelDirections 工具创建的输出要素类中的某些列。ElapsedTime 列中的值所采用的单位是在用于分析的出行模式中定义的时间阻抗属性的单位(此示例中为分钟),而 DriveDistance 列中的值所采用的单位是在出行模式中定义的距离阻抗属性的单位(此示例中为英里)。

GetTravelDirections 工具输出中的所选列

TextElapsedTimeDriveDistance

从停靠点 A 开始

0

0

向北沿 BRITANNIA BLVD 行驶,前往 OTAY MESA RD

1.04

0.64

右转沿 OTAY MESA RD 前行

1.83

2.44

继续向前沿 CA-905 行驶

0.29

0.39

继续向前沿 OTAY MESA RD 行驶

0.04

0.06

在岔路口靠左侧行驶,进入 OTAY MESA RD

0.16

0.1

左转

0.04

0.02

继续向前沿 CA-125 行驶

7.17

10.41

到达停靠点 B,目的地位于道路右侧

0

0

数据文件夹

本教程的数据可ArcGIS Online 进行下载。将数据提取至 C:\Routing\TravelDirections。该文件夹包含一个名为 TravelDirections.aprxArcGIS Pro 工程。在此工程中,TravelDirections.tbx 工具箱包含一个名为 GetTravelDirections 的工具,可用于生成行进方向。由 GetTravelDirections 工具使用的名为 Streets_ND 的交通网络存储在 ToolData 文件夹中名为 SanDiego.gdb 的文件地理数据库中。网络数据集将作为名为 Street Network 的图层添加到工程中的默认地图。schema.gdb 地理数据库包含 Stops.lyrx 图层文件引用的 Stops 要素类。该图层文件用于定义 GetTravelDirections 工具使用的输入停靠点的方案和符号系统。

创作地理处理工具

GetTravelDirections 地理处理工具是用于提供特定功能(此示例中为生成行进方向)的脚本工具的一个示例。运行该工具会执行您在文件中编写并与脚本工具相关联的 Python 代码。在此示例中,GetTravelDirections 工具的 Python 代码将被写入 get_directions.py 文件中。脚本工具的输入和输出(称为工具参数)将使用 ArcGIS Pro 中的新建脚本对话框进行定义。

定义工具参数

下图显示了为 GetTravelDirections 工具定义的各种参数:

GetTravelDirections 工具参数
将显示 GetTravelDirections 工具参数。

该工具为 stops 参数使用了 Feature Set 数据类型。此举增加了以交互方式指定输入停靠点的功能。要素集的方案和符号系统是根据 ToolData 文件夹中的 Stops.lyrx 文件定义的。这使您不仅可以强制执行仅使用点几何来指定输入停靠点的约束,还可以预定义输入支持的属性字段集。如果您未定义方案,则您服务的用户可以为要素集指定任何几何类型。

注:

为要素集指定方案不会阻止您服务的用户传递不受支持的字段。在工具的执行过程中,您可以列出提供给服务的所有输入字段,并确定该工具在获取未在方案中定义的字段时的行为方式。在大多数情况下,您可以忽略未在方案中定义的字段。

该工具为 network_dataset 参数使用了 Network Dataset Layer 数据类型。因此,您可以使用地图中的网络数据集图层来指定网络数据集。用于指定网络数据集的其他有效数据类型包括 Network DatasetNetwork Data SourceNetwork Data Source 数据类型允许您指定磁盘上的网络数据集、地图上的网络数据集图层或配置了路径服务的 ArcGIS OnlineArcGIS Enterprise 门户的 URL。在此示例中,您不希望使用门户中的路径服务来运行分析,因此您不应选择 Network Data Source 数据类型。Network Dataset 数据类型允许您仅使用网络数据集的磁盘位置路径来指定网络数据集。尽管 GetTravelDirections 工具可以使用通过路径指定的网络数据集,但不建议这样做;原因是该工具会为每个请求连接到网络数据集,该过程很慢且会增加请求的响应时间。

提示:

使用网络数据集图层可提升整体工具执行时间,原因是网络数据集图层可使网络数据集的连接保持在打开状态。而如果从网络数据集的磁盘位置引用网络数据集,则只会在每次执行工具时建立与网络数据集的连接,这将降低使用该工具创建的地理处理服务的性能。

该工具为 travel_mode 参数使用了 Network Travel Mode 数据类型。network_dataset 参数将被设置为 network_travel_mode 参数的依赖项。这样,该工具即可读取网络数据集上定义的出行模式,并将其名称作为 travel_mode 参数支持的可能值的列表进行填充。

该工具为 start_time 参数使用了 Date 数据类型。此参数为可选参数,且未定义默认值。在该工具的执行过程中,如果为 start_time 参数传递了一个值,则该值将用于结合根据针对该日期-时间值观测到的历史交通模式得出的行进速度来计算行进时间。如果没有为 start_time 参数传递任何值,则该工具将根据固定的行进速度来计算行进时间。

该工具为 output_directions 参数使用了 Feature Class 数据类型。可通过设置该参数的 Direction 属性来将其标记为输出参数。此参数的默认值将指定将输出写入基于内存的工作空间中的要素类。

提示:

与文件地理数据库相比,将输出写入基于内存的工作空间可以提高通过脚本工具创建的地理处理服务的性能。在大多数情况下,应该将执行网络分析的地理处理工具的输出写入基于内存的工作空间。如果您知道您的工具将生成无法存储在运行地理处理服务的服务器计算机内存中的大型输出,则应将该输出写入文件地理数据库。

记录工具

通过记录地理处理工具,您同时也记录了生成的服务及其参数,因为服务发布过程会将这些文本复制到服务的项目描述中。描述或记录服务为必要条件,同时有助于用户了解如何与服务成功进行交互以及如何生成行进方向。已记录此示例中使用的 GetTravelDirections 工具;如需检查,可以右键单击目录窗格中的地理处理工具并选择查看元数据

定义工具执行

将请求发送到地理处理服务后,该服务后台的工具将执行与该工具关联的 Python 脚本文件。您可以在此脚本文件中定义工具的执行。下面的代码片段列出了定义 GetTravelDirections 工具执行的 Python 代码。该脚本将使用 arcpy.nax 模块中的 Route 类来执行点到点路径并生成行进方向。

用于执行 GetTravelDirections 工具的 Python 代码

下面的代码片段中包含工具文件夹中包含的 get_directions.py 文件的内容。其中显示如何执行点到点路径以及如何将行进方向导出到要素类。执行任何类型网络分析(包括此处演示的点到点路径)的常规模式都是初始化分析指定的求解程序类、设置分析设置、加载输入、求解分析并导出结果。源代码中的注释(以 # 开头的行)可提供有关实施细节的详细信息,包括一些用于优化工具性能的提示。

"""Generate travel directions based on a travel mode."""
import arcpy
def get_directions():
    """Generate travel directions based on a travel mode."""
    # Read inputs
    stops = arcpy.GetParameter(0)
    # Performance tip: The network data source should be read using the arcpy.GetParameterAsText()
    # method instead of the arcpy.GetParameter() method since GetParameterAsText provides
    # access to the network data source much faster
    network_data_source = arcpy.GetParameterAsText(1)
    travel_mode = arcpy.GetParameter(2)
    start_time = arcpy.GetParameter(3)
    output_directions = arcpy.GetParameterAsText(4)
    # Initialize Route solver and set analysis settings
    route_solver = arcpy.nax.Route(network_data_source)
    route_solver.travelMode = travel_mode
    route_solver.timeOfDay = start_time
    route_solver.returnDirections = True
    # Load inputs
    route_solver.load(arcpy.nax.RouteInputDataType.Stops, stops)
    # Solve. A network analyst license is required when solving
    arcpy.CheckOutExtension("network")
    result = route_solver.solve()
    # Print all the warning and error messages in case the solve is not successful
    if not result.solveSucceeded:
        arcpy.AddMessage("Solve failed")
        warning_msgs = result.solverMessages(arcpy.nax.MessageSeverity.Warning)
        error_msgs = result.solverMessages(arcpy.nax.MessageSeverity.Error)
        for msg in warning_msgs:
            arcpy.AddWarning(msg[-1])
        for msg in error_msgs:
            arcpy.AddError(msg[-1])
        raise SystemExit(1)
    # Export the directions
    result.export(arcpy.nax.RouteOutputDataType.Directions, output_directions)
if __name__ == "__main__":
    get_directions()
注:

上面的代码片段显示了如何使用 arcpy.nax 模块来实施点到点路径。但是,上面代码片段中显示的模式可以应用于 使用 arcpy.nax 模块进行的任何其他分析

将工具发布为 Web 工具

要通过 GetTravelDirections 工具创建服务,您必须将该工具发布为 Web 工具。为此,您必须先成功运行该工具,然后使用 ArcGIS Pro 中的共享为 Web 工具窗格将该工具结果作为 Web 工具进行共享。

运行工具

要运行 GetTravelDirections 工具,请完成以下步骤:

  1. ArcGIS Pro 中打开 TravelDirections 工程。
  2. 在 TravelDirections 工具箱中,打开 GetTravelDirections 地理处理工具。
  3. 运行 GetTravelDirections 工具。
    1. 对于停靠点参数,请在地图的圣地亚哥市区域内至少创建两个停靠点。
    2. 对于网络数据集参数,请选择已添加到地图的街道网络图层。

      指定该街道网络图层而非通过磁盘位置指定网络数据集有助于为使用该工具创建的地理处理服务提供最佳性能。

    3. 对于出行模式参数,请从选择列表中选择一种出行模式,例如行驶时间

      出行模式参数的选择列表列出了网络数据集中的出行模式名称,原因是定义出行模式参数时已将网络数据集参数设置为依赖项。

    4. 不要指定开始时间参数的值。

      指定开始时间参数的值会导致通过该工具创建的服务在生成行进方向时将此日期-时间值用作默认开始时间,而这可能不是那些希望传递日期-时间的服务用户所希望看到的。

    5. 保留输出方向参数的默认值。

      输出方向参数的默认值是将工具的输出写入基于内存的工作空间,从而提高通过该工具创建的服务的性能。

    6. 单击运行按钮以运行该工具。

将包含网络数据集的文件夹注册为数据存储

GetTravelDirections 工具所使用的网络数据集必须可供参与 ArcGIS Server 站点的所有计算机访问。可通过以下任一方法来完成此操作:

  • 允许发布过程将网络数据集复制到 ArcGIS Server 站点中可供所有参与站点的计算机访问的位置。
  • 将网络数据集复制到预定义位置的所有参与计算机上,并允许服务从该位置引用数据。

推荐的选项是在预定义位置(例如 D:\RoutingData)的所有参与计算机上手动复制网络数据集。尽管这似乎是两个可用选项中比较费力的一个,但它的效果更好,且可以为服务提供更好的性能。

请选择一个位置来存储每个参与计算机的本地数据,而非将数据存储在所有计算机通用的文件共享。将网络数据集存储在本地文件夹而非文件共享中可以提高路径服务的性能。如需更新网络数据集(例如,如果您收到了较新版本的数据),可以停止路径服务,替换所有参与计算机上包含网络数据集的文件地理数据库,然后重新启动该服务。

当您选择复制数据的选项时,发布过程会将数据复制到所有计算机通用的共享位置(前提是您的 ArcGIS Server 站点中有多台计算机)。路径服务将从共享位置读取网络数据集,而这会降低服务性能。ArcGIS Server 用于存储此数据的位置将被视为 ArcGIS Server 站点的内部位置,并由 ArcGIS Server 托管。要执行数据更新,必须删除并重新创建路径服务,这可能会导致错误,原因是您必须使用先前使用过的相同设置来重新发布路径服务。但是,如果路径服务引用了数据,请停止并启动路径服务而非重新创建服务。

要将包含网络数据集的文件夹注册为与门户联合的服务器中的数据存储,请完成以下步骤:

  1. 单击功能区上的共享选项卡。在管理组中,单击数据存储 数据存储

    将显示管理注册数据存储窗格。

  2. 在窗格顶部,确认下拉列表设置为门户项目。单击添加按钮 将数据存储项目添加到门户,然后单击文件夹 文件夹
  3. 添加数据存储对话框中,提供标题(例如 RoutingData)和标签。

    这是数据存储门户项目的必需元数据。

  4. (可选)指定一个文件夹以包含门户中的数据存储项目。

    默认情况下,项目在内容的根级别下存储。可使用下拉菜单选择现有文件夹或创建文件夹。也可以浏览到文件夹。

  5. 要指定发布者文件夹,请单击浏览按钮 浏览,浏览到包含网络数据集 C:\Routing\TravelDirections\ToolData 的文件夹,然后单击确定

    发布者文件夹是包含要向服务器注册的数据的文件夹。

  6. 如果发布者和服务器的数据位于不同的文件夹中,请取消选中与发布者文件夹路径相同复选框,然后输入路径或浏览到服务器可以访问的文件夹。
  7. 单击要向其添加数据存储的服务器的复选框。可选择多个服务器。
  8. (可选)单击验证 验证 确认服务器是否可以访问该服务器文件夹。

    如果可以访问该文件夹,则确认有效将在服务器名称旁边的状态列中显示。如果不可以,将显示错误无法访问数据项目。创建数据存储时,系统将自动验证连接。

  9. 共享给下,指定如何共享数据存储。
    • 所有人 - 此选项将您的数据存储设置为“公共”。任何人均可访问并进行查看。
    • 我的组织 - 此选项用于将数据存储与您组织中所有经过身份验证的用户共享。
    • 群组 - 您可以通过此选项将您的数据存储与您所在的群组及其成员共享。
  10. 单击创建

    数据存储将创建并在管理注册数据存储窗格中显示。

将工具共享为 web 工具

要通过 GetTravelDirections 工具创建地理处理服务,请完成以下步骤:

  1. 以具有 Web 工具发布权限的用户身份登录到 ArcGIS Enterprise 门户。

    共享 web 工具需要管理权限或者 web 工具发布者权限。

  2. 单击分析功能区选项卡上地理处理组中的历史记录按钮,以打开历史记录窗格。
  3. 右键单击 GetTravelDirections 然后选择共享为 > web 工具
  4. 共享为 Web 工具窗格中配置服务设置,例如服务名称和执行模式。
    1. 项目详细信息下,为名称输入 TravelDirections
    2. 数据下,选择引用注册数据
    3. 位置下,可以选择指定或创建一个门户文件夹,以将 Web 工具项目存储在 ArcGIS Enterprise 门户中。

      如果未指定门户文件夹值,则 web 工具项目将存储在内容的根级别下。

    4. 位置下,选择要向其发布 Web 工具的联合服务器以及联合服务器上将包含路径服务的文件夹。

      如果您使用的是 ArcGIS Enterprise 的基础部署,则服务器和文件夹列表中只有一个服务器(托管服务器)。如果未在服务器和文件夹下指定文件夹名称,则路径服务将在联合服务器的根文件夹中创建。

    5. 共享给下,指定 Web 工具的共享方式。

      默认情况下,Web 工具仅可供发布该工具的用户访问。Web 工具支持公开共享,以便任何人都可以与组织中所有经过身份验证的用户或您所属的特定群组及其成员一起执行该 Web 工具。

    6. 单击共享为 Web 工具窗格中的配置选项卡。
    7. 功能下,取消选中上传复选框。

      上传功能可控制客户端是否可以将文件上传到服务器,以便 web 工具用作输入。此示例中的路径服务不需要支持文件上传。

    8. 执行模式下,选择同步

      TravelDirections 路径服务执行速度较快(通常不到一秒钟)。选择同步执行模式以获得最佳性能。但是,如果您的路径服务需要很长的执行时间(例如,计算多个长距离两点路径),则请将执行模式设置为异步,因为异步执行模式更适合长时间运行的请求。不建议将异步执行模式用于执行速度较快的服务,因为这会在每次执行服务时增加固定的开销。对于长时间运行的请求,所产生的固定开销对服务总执行时间的影响不大。

    9. 属性下,为消息级别选择警告

      将服务的消息级别设置为警告可确保将服务生成的所有错误和警告消息返回至客户端。这对于客户端诊断服务问题(例如服务为何无法生成行进方向)很有帮助。

    10. 属性下,为服务器返回的最大记录数使用默认值。

      在大多数情况下,此示例中的服务所生成的输出方向要素不应超过 1,000 个。如果服务生成的要素超过 1,000 个,则服务器仅会将前 1,000 个要素返回至客户端,而要素的子集可能对客户端无用。为避免出现这种情况,请为服务器返回的最大记录数选项设置一个较高的值。对于其他路径服务,可以将此选项设置为更大的数字。例如,如果您有一项服务需要经常计算 500 个起点和 500 个目的地之间的起点-目的地成本矩阵,则您的服务可以生成 250,000 个要素。在这种情况下,请将此选项值设置为 250,000 或更大的数字。

    11. 单击共享为 Web 工具窗格中的内容选项卡。
    12. 单击我的内容 > TravelDirectionsGetTravelDirections 工具右侧的配置工具属性按钮,以配置 GetTravelDirections Web 工具的属性。
    13. 展开网络数据集参数类别,然后为输入模式选项选择常量值

      使用 TravelDirections 服务的客户端无需指定用于生成行进方向的网络数据集,因为该服务始终使用相同的网络数据集。将参数的输入模式设置为常量可确保该参数在该工具创建的所生成服务上不可用。

    14. 单击 GetTravelDirections 页面左上角的返回按钮,以返回到共享为 Web 工具窗格。
  5. 单击共享为 Web 工具窗格中的分析按钮,并确保没有报告任何错误或警告。

    分析器将检查是否存在阻止工具作为服务成功执行的问题。如果报告了错误,则必须在发布工具之前将其更正。如果仅报告警告,则如果您的情况需要警告,则可以继续发布。例如,如果您要复制数据而非引用注册数据,则会出现一条警告消息,提示该数据将被复制到服务器。这是此情况下预期的警告,可以忽略此消息。您可以右键单击错误或警告消息,以访问介绍如何解决问题的帮助主题。

  6. 单击共享为 Web 工具窗格中的发布按钮,以将该工具发布为服务。

使用 web 工具

您可以在 ArcGIS Pro目录窗格的门户部分中打开 Web 工具。除了在 ArcGIS Pro 中运行工具之外,还可以在 Python 脚本Web 应用程序中使用地理处理服务。

以下步骤描述了如何将 ArcGIS Pro 用作客户端应用程序来运行 GetTravelDirections 工具:

  1. 目录窗格中,单击门户 > 所有门户
  2. 搜索栏中输入 TravelDirections
  3. 双击 TravelDirections 工具箱,然后打开 GetTravelDirections 工具。
  4. 运行 GetTravelDirections web 工具。

    由于 GetTravelDirections 工具会输出要素类,地理处理框架会自动在 Web 工具上添加输出要素类名称参数。此参数允许您将结果写入为存储在企业门户中的要素服务。但是,使用此参数存在一定的限制

    警告:

    如果指定输出要素服务名称值,则 GetTravelDirections Web 工具将返回错误,原因是使用同步执行模式发布的服务(例如本示例中的 TravelDirections 服务)不支持将结果创建为要素服务。