cisco.dnac.swim_workflow_manager 模块 – 用于管理 Cisco Catalyst Center 中 SWIM（软件镜像管理）操作的模块
注意
此模块是 cisco.dnac 集合（版本 6.25.0）的一部分。
如果您使用的是 ansible 包，则可能已安装此集合。它不包含在 ansible-core 中。要检查是否已安装，请运行 ansible-galaxy collection list。
要安装它，请使用：ansible-galaxy collection install cisco.dnac。您需要其他要求才能使用此模块，有关详细信息，请参阅 需求。
要在剧本中使用它，请指定：cisco.dnac.swim_workflow_manager。
cisco.dnac 6.6.0 中的新增功能
概要
管理镜像导入、分发、激活以及将镜像标记为黄金镜像的操作。
提供一个 API，用于通过 HTTP/FTP 从远程文件系统获取软件镜像并将其上传到 Catalyst Center。支持的文件扩展名 - bin、img、tar、smu、pie、aes、iso、ova、tar.gz、qcow2。
提供一个 API，用于从本地文件系统获取软件镜像并将其上传到 Catalyst Center。支持的文件扩展名 - bin、img、tar、smu、pie、aes、iso、ova、tar.gz、qcow2。
提供一个 API，用于从 Cisco Connection Online (CCO) 获取软件镜像并将其上传到 Catalyst Center。有关 Cisco Catalyst Center 中建议的镜像，请参阅 https://software.cisco.com/download/home。CCO 功能从 Cisco Catalyst 版本 2.3.7.6 开始可用。
提供一个 API，用于将镜像标记或取消标记为给定设备系列的黄金镜像。
提供一个 API，用于将软件镜像分发到设备。软件镜像必须先导入到 Catalyst Center，然后才能分发。
需求
执行此模块的主机需要以下要求。
dnacentersdk == 2.7.3
python >= 3.9
参数
参数 |
注释 |
|---|---|
正在管理的 SWIM 镜像的详细信息列表 |
|
用于指定 SWIM 镜像激活目标设备的参数。可以使用以下选项之一来标识设备：- device_serial_number - device_ip_address - device_hostname - device_mac_address - site_name（如果指定，则将在站点内的所有设备上激活镜像）必须至少提供其中一个参数。如果提供了 'site_name'，则可以使用其他过滤器，如 'device_role'、'device_family_name' 和 'device_series_name' 来进一步缩小站点内的设备范围。 |
|
ActivateLowerImageVersion 标志。 选项
|
|
指定设备系列名称，例如交换机和集线器等。 |
|
需要激活镜像的设备主机名 |
|
需要激活镜像的设备 IP 地址 |
|
需要激活镜像的设备 MAC 地址 |
|
定义设备角色，允许的值包括 ALL、UNKNOWN、ACCESS、BORDER ROUTER、DISTRIBUTION 和 CORE。 |
|
需要激活镜像的设备序列号 |
|
此参数指定设备系列的名称。它用于在 Cisco Catalyst Center 中标识特定系列的设备，例如 Cisco Catalyst 9300 系列交换机。 |
|
此参数指定应用于设备的升级模式，其值包括“install”、“bundle”和“currentlyExists”。install - 此模式指示 Cisco Catalyst Center 对目标设备执行新镜像的全新安装。选择此模式时，升级过程中设备上的现有镜像将被新镜像完全替换。这确保设备在升级完成后仅运行新镜像版本。bundle - 此模式指示 Cisco Catalyst Center 在启动升级过程之前，将新镜像与设备上的现有镜像捆绑在一起。通过保留设备上的现有镜像，同时将新镜像作为附加捆绑包添加，此模式允许更有效的升级过程。升级后，设备可以运行现有镜像或新的捆绑镜像，具体取决于配置。currentlyExists - 此模式指示 Cisco Catalyst Center 检查目标设备是否已安装所需的镜像版本。如果设备上已存在镜像，则不执行任何操作，并跳过这些设备的升级过程。此模式有助于避免对已安装正确镜像版本的设备进行不必要的升级，从而节省时间。 |
|
激活 SWIM 镜像时启用 distribute_if_needed 选项。 选项
|
|
SWIM 镜像名称 |
|
ScheduleValidate 查询参数。ScheduleValidate 在调度前验证数据（可选）。 选项
|
|
用于获取与此站点关联的设备详细信息。 |
|
指定 SWIM 镜像分发目标设备的参数。可以使用以下选项之一标识设备：- device_serial_number - device_ip_address - device_hostname - device_mac_address - site_name（如果指定，则镜像将分发到站点内的所有设备）。必须至少提供一个这些参数。如果提供“site_name”，则可以使用其他过滤器，例如“device_role”、“device_family_name”和“device_series_name”，以进一步缩小站点内的设备范围。 |
|
指定设备系列名称，例如交换机和集线器等。 |
|
需要分发镜像的设备主机名 |
|
需要分发镜像的设备 IP 地址 |
|
需要分发镜像的设备 MAC 地址 |
|
设备角色及其允许的值包括 ALL、UNKNOWN、ACCESS、BORDER ROUTER、DISTRIBUTION 和 CORE。ALL - 此角色通常表示网络中的所有设备，无论其具体角色或功能如何。UNKNOWN - 此角色分配给尚未识别或分类其角色或功能的设备。如果平台无法根据可用信息确定设备的角色，则可能会发生这种情况。ACCESS - 此角色通常表示用作最终用户设备连接到网络的接入点的交换机或接入点。这些设备通常位于网络边缘，并为最终用户设备提供连接。BORDER ROUTER - 这些设备将不同的网络域或网段连接在一起。它们通常充当不同网络之间的网关，例如将企业网络连接到互联网或连接多个分支机构。DISTRIBUTION - 此角色表示在分层网络设计中充当分发交换机或路由器的功能。它们聚合来自接入交换机的流量，并将其路由到网络核心或其他分发交换机。CORE - 此角色通常表示构成网络主干的高容量交换机或路由器。它们处理大量的流量，并在网络的不同部分之间提供连接，例如连接分发交换机或在不同的网络段之间提供互连。 |
|
需要分发镜像的设备序列号 |
|
此参数指定设备系列的名称。它用于在 Cisco Catalyst Center 中标识特定系列的设备，例如 Cisco Catalyst 9300 系列交换机。 |
|
SWIM 镜像名称 |
|
用于获取与此站点关联的设备详细信息。 |
|
正在导入的镜像的详细信息 |
|
与从 Cisco Connection Online (CCO) 导入软件镜像到 Catalyst Center 相关的参数。 此 API 从 CCO 获取指定的镜像并将其上传到 Catalyst Center。 从 Cisco Catalyst Center 版本 2.3.7.6 开始支持。 有关推荐镜像，请参阅 Cisco 软件下载门户网站 (https://software.cisco.com/download/home)。 |
|
要从 Cisco.com 导入的软件镜像名称。 这是一个必填参数，必须提供才能启动从 CCO 下载。 |
|
要导入的镜像的本地路径的详细信息。 |
|
提供从本地系统导入镜像所需的绝对文件路径（例如，“/path/to/your/file”）。接受的文件格式包括 - .gz、.bin、.img、.tar、.smu、.pie、.aes、.iso、.ova、.tar_gz、.qcow2、.nfvispkg、.zip、.spa、.rpm。 |
|
确定镜像是否来自第三方（可选）的查询参数。 选项
|
|
指定 ThirdPartyApplicationType 查询参数以指示第三方应用程序的类型。允许的值包括 WLC、LINUX、FIREWALL、WINDOWS、LOADBALANCER、THIRDPARTY 等。（可选）WLC（无线局域网控制器） - 它是一种网络设备，可以集中管理和控制多个无线接入点 (AP)。LINUX - 它是一个开源操作系统，提供一整套软件包和实用程序。FIREWALL - 它是一种网络安全设备，根据预定的安全规则监控和控制传入和传出的网络流量。它充当受信任的内部网络和不受信任的外部网络（例如互联网）之间的屏障，防止未经授权的访问。WINDOWS - 它是一个以其图形用户界面 (GUI) 支持、广泛的硬件和软件兼容性以及在各种应用程序中的广泛使用而闻名的操作系统。LOADBALANCER - 它是一种网络设备或软件应用程序，可在多个服务器或资源之间分配传入的网络流量。THIRDPARTY - 它指的是不属于核心系统的第三方镜像或应用程序。NAM（网络访问管理器） - 它是一种网络管理工具或软件应用程序，提供对网络访问策略、用户身份验证和设备合规性的集中控制和监控。WAN 优化 - 它指的是用于提高广域网性能和效率的技术和技术。它包括各种优化技术，例如数据压缩、缓存、协议优化和流量优先级，以减少延迟，提高吞吐量，并改善广域网连接的用户体验。Unknown - 它指的是未指定的或无法识别的应用程序类型。Router - 它是一种网络设备，用于在计算机网络之间转发数据包。它们对于连接多个网络以及在它们之间引导流量至关重要。 |
|
提供 ThirdPartyImageFamily 查询参数以标识第三方镜像的系列。镜像系列名称，例如 PALOALTO、RIVERBED、FORTINET、CHECKPOINT、SILVERPEAK 等。（可选）。 |
|
包含 ThirdPartyVendor 查询参数以指定第三方的供应商。 |
|
指定镜像导入的来源。支持的值包括用于本地文件导入的“local”、用于远程 URL 导入的“remote”或用于从 Cisco Connection Online 导入的“CCO”。 |
|
SWIM 导入的 URL 详细信息 |
|
通过 Url 导入 Swim 的有效负载。 |
|
一个可选参数，用于指定应用程序的类型。允许的值包括 WLC、LINUX、FIREWALL、WINDOWS、LOADBALANCER、THIRDPARTY 等。这仅适用于第三方镜像类型（可选）。WLC（无线局域网控制器） - 它是一种网络设备，可以集中管理和控制多个无线接入点 (AP)。LINUX - 它是一个开源操作系统，提供一整套软件包和实用程序。FIREWALL - 它是一种网络安全设备，根据预定的安全规则监控和控制传入和传出的网络流量。它充当受信任的内部网络和不受信任的外部网络（例如互联网）之间的屏障，防止未经授权的访问。WINDOWS - 它是一个提供各种应用程序的 GUI 支持以及与硬件和软件的广泛兼容性的操作系统。LOADBALANCER - 它是一种网络设备或软件应用程序，可在多个服务器或资源之间分配传入的网络流量。THIRDPARTY - 它指的是不属于核心系统的第三方镜像或应用程序。NAM（网络访问管理器） - 它是一种网络管理工具或软件应用程序，提供对网络访问策略、用户身份验证和设备合规性的集中控制和监控。WAN 优化 - 它指的是用于提高广域网性能和效率的技术和技术。它包括各种优化技术，例如数据压缩、缓存、协议优化和流量优先级，以减少延迟，提高吞吐量，并改善广域网连接的用户体验。Unknown - 它指的是未指定的或无法识别的应用程序类型。Router - 它是一种网络设备，用于在计算机网络之间转发数据包。它们对于连接多个网络以及在它们之间引导流量至关重要。 |
|
表示镜像系列的名称，仅在上传第三方镜像时适用。镜像系列名称，例如 PALOALTO、RIVERBED、FORTINET、CHECKPOINT、SILVERPEAK 等。（可选）。 |
|
标志指示镜像是否从第三方上传（可选）。 选项
|
|
通过远程 URL 导入 SWIM 镜像的必填参数。使用 URL 导入镜像时需要此参数。（例如，http://{host}/swim/cat9k_isoxe.16.12.10s.SPA.bin，ftp://user:password@{host}/swim/cat9k_isoxe.16.12.10s.SPA.iso) |
|
供应商名称，仅适用于通过 URL 导入时的第三方镜像类型（可选）。 |
|
ScheduleAt 查询参数。纪元时间（自 1970 年 1 月 1 日 UTC 以来的毫秒数），应安排分发的时间（可选）。 |
|
ScheduleDesc 查询参数。自定义描述（可选）。 |
|
ScheduleOrigin 查询参数。此调用的发起者（可选）。 |
|
将镜像标记或取消标记为黄金镜像的详细信息 |
|
设备镜像族名称（例如 Cisco Catalyst 9300 交换机） |
|
指定设备角色，用于标记或取消标记镜像为黄金镜像。允许的值：- ‘ALL’：将黄金标记应用于所有设备，无论其角色如何。- ‘UNKNOWN’：标记没有指定分类的设备。- ‘ACCESS’：标记连接最终用户设备的设备（例如，接入交换机）。- ‘BORDER ROUTER’：标记连接不同网络段或域的设备。- ‘DISTRIBUTION’：标记将流量聚合到核心层的设备。- ‘CORE’：标记处理大流量网络流量的主干设备。行为：- 如果“device_role”是单个字符串（例如，“ACCESS”），则仅标记该角色为黄金角色。- 如果“device_role”包含多个角色（例如，“ACCESS,CORE”），则所有指定的角色都将被标记为黄金角色。示例：- device_role：“ACCESS”仅将“ACCESS”角色标记为黄金角色。- device_role：“ACCESS,CORE”将“ACCESS”和“CORE”角色都标记为黄金角色。 |
|
将被标记或取消标记为黄金镜像的 SWIM 镜像名称。 |
|
SWIM 镜像将被标记/取消标记为黄金镜像的站点名称。如果未提供，SWIM 镜像将映射到全局站点。 |
|
布尔值，用于将 SWIM 镜像标记/取消标记为黄金镜像。如果为 True，则将给定镜像标记为黄金镜像。如果为 False，则将给定镜像取消标记为黄金镜像。 选项
|
|
应用 playbook 配置后，设置为 True 以验证 Cisco Catalyst Center 配置。 选项
|
|
定义检索任务详细信息的 API 调用的超时时间（秒）。如果在此期间内未收到任务详细信息，则进程将结束，并记录超时通知。 默认值： |
|
指示 Cisco Catalyst Center SDK 中是否启用了调试。 选项
|
|
Cisco Catalyst Center 的主机名。 |
|
启用/禁用 playbook 执行日志记录的标志。 当为 true 且提供 dnac_log_file_path 时，- 在执行位置创建具有指定名称的日志文件。 当为 true 且未提供 dnac_log_file_path 时，- 在执行位置创建名为“dnac.log”的日志文件。 当为 false 时，- 日志记录被禁用。 如果日志文件不存在，- 基于“dnac_log_append”标志以追加或写入模式创建它。 如果日志文件存在，- 基于“dnac_log_append”标志将其覆盖或追加。 选项
|
|
确定文件的模式。设置为 True 表示“追加”模式。设置为 False 表示“写入”模式。 选项
|
|
控制日志记录。如果 dnac_log 为 True，则记录日志。 如果未指定路径，- 当“dnac_log_append”为 True 时，在当前 Ansible 目录中生成“dnac.log”；日志被追加。- 当“dnac_log_append”为 False 时，生成“dnac.log”；日志被覆盖。 如果指定了路径，- 当“dnac_log_append”为 True 时，文件以追加模式打开。- 当“dnac_log_append”为 False 时，文件以写入 (w) 模式打开。- 在共享文件场景中，如果没有追加模式，则每次模块执行后都会覆盖内容。- 对于共享日志文件，将第一个模块的 append 设置为 False（以覆盖）；对于后续模块，将 append 设置为 True。 默认值： |
|
设置日志级别的阈值。级别等于或高于此级别的消息将被记录。级别按严重性顺序排列 [CRITICAL、ERROR、WARNING、INFO、DEBUG]。 CRITICAL 表示严重的错误导致程序停止。仅显示 CRITICAL 消息。 ERROR 表示阻止函数的问题。显示 ERROR 和 CRITICAL 消息。 WARNING 表示潜在的未来问题。显示 WARNING、ERROR、CRITICAL 消息。 INFO 跟踪正常操作。显示 INFO、WARNING、ERROR、CRITICAL 消息。 DEBUG 提供详细的诊断信息。显示所有日志消息。 默认值： |
|
Cisco Catalyst Center 身份验证的密码。 |
|
指定与 Cisco Catalyst Center 关联的端口号。 默认值： |
|
指定连续调用 API 以检索任务详细信息之间的间隔（秒）。 默认值： |
|
Cisco Catalyst Center 身份验证的用户名。 默认值： |
|
启用或禁用 SSL 证书验证的标志。 选项
|
|
指定 SDK 应使用的 Cisco Catalyst Center 版本。 默认值： |
|
模块完成后的 Catalyst Center 状态。 选项
|
|
Cisco Catalyst Center SDK 的标志，用于启用根据 JSON 模式验证请求正文。 选项
|
注释
注意
使用的 SDK 方法为 software_image_management_swim.SoftwareImageManagementSwim.import_software_image_via_url、software_image_management_swim.SoftwareImageManagementSwim.tag_as_golden_image、software_image_management_swim.SoftwareImageManagementSwim.trigger_software_image_distribution、software_image_management_swim.SoftwareImageManagementSwim.trigger_software_image_activation，
使用的路径为 post /dna/intent/api/v1/image/importation/source/url、post /dna/intent/api/v1/image/importation/golden、post /dna/intent/api/v1/image/distribution、post /dna/intent/api/v1/image/activation/device，
在 v6.13.2 中添加了参数“dnac_api_task_timeout”、“dnac_task_poll_interval”选项。
不支持
check_mode插件在控制节点上运行，不使用任何 Ansible 连接插件，而是使用 Cisco Catalyst Center SDK 中的嵌入式连接管理器。
以 dnac_ 开头的参数由 Cisco Catalyst Center Python SDK 用于建立连接。
示例
- name: Import an image from a URL, tag it as golden and load it on device
cisco.dnac.swim_workflow_manager:
dnac_host: "{{dnac_host}}"
dnac_username: "{{dnac_username}}"
dnac_password: "{{dnac_password}}"
dnac_verify: "{{dnac_verify}}"
dnac_port: "{{dnac_port}}"
dnac_version: "{{dnac_version}}"
dnac_debug: "{{dnac_debug}}"
dnac_log_level: "{{dnac_log_level}}"
dnac_log: True
config:
- import_image_details:
type: remote
url_details:
payload:
- source_url:
- "http://10.10.10.10/stda/cat9k_iosxe.17.12.01.SPA.bin"
is_third_party: False
tagging_details:
image_name: cat9k_iosxe.17.12.01.SPA.bin
device_role: ACCESS
device_image_family_name: Cisco Catalyst 9300 Switch
site_name: Global/USA/San Francisco/BGL_18
tagging: True
image_distribution_details:
image_name: cat9k_iosxe.17.12.01.SPA.bin
device_serial_number: FJC2327U0S2
image_activation_details:
image_name: cat9k_iosxe.17.12.01.SPA.bin
schedule_validate: False
activate_lower_image_version: False
distribute_if_needed: True
device_serial_number: FJC2327U0S2
- name: Import an image from local, tag it as golden.
cisco.dnac.swim_workflow_manager:
dnac_host: "{{dnac_host}}"
dnac_username: "{{dnac_username}}"
dnac_password: "{{dnac_password}}"
dnac_verify: "{{dnac_verify}}"
dnac_port: "{{dnac_port}}"
dnac_version: "{{dnac_version}}"
dnac_debug: "{{dnac_debug}}"
dnac_log_level: "{{dnac_log_level}}"
dnac_log: True
config:
- import_image_details:
type: local
local_image_details:
file_path: /Users/Downloads/cat9k_iosxe.17.12.01.SPA.bin
is_third_party: False
tagging_details:
image_name: cat9k_iosxe.17.12.01.SPA.bin
device_role: ACCESS
device_image_family_name: Cisco Catalyst 9300 Switch
site_name: Global/USA/San Francisco/BGL_18
tagging: True
- name: Import bulk images from URL
cisco.dnac.swim_workflow_manager:
dnac_host: "{{dnac_host}}"
dnac_username: "{{dnac_username}}"
dnac_password: "{{dnac_password}}"
dnac_verify: "{{dnac_verify}}"
dnac_port: "{{dnac_port}}"
dnac_version: "{{dnac_version}}"
dnac_debug: "{{dnac_debug}}"
dnac_log_level: "{{dnac_log_level}}"
dnac_log: True
config:
- import_image_details:
type: remote
url_details:
payload:
- source_url:
- "http://10.10.10.10/stda/cat9k_iosxe.17.12.01.SPA.bin"
- "http://10.10.10.10/stda/cat9k_iosxe.17.12.02.SPA.bin"
third_party: False
- name: Import images from CCO (cisco.com)
cisco.dnac.swim_workflow_manager:
dnac_host: "{{dnac_host}}"
dnac_username: "{{dnac_username}}"
dnac_password: "{{dnac_password}}"
dnac_verify: "{{dnac_verify}}"
dnac_port: "{{dnac_port}}"
dnac_version: "{{dnac_version}}"
dnac_debug: "{{dnac_debug}}"
dnac_log_level: "{{dnac_log_level}}"
dnac_log: True
config:
- import_image_details:
type: CCO
cco_image_details:
image_name: cat9k_iosxe.17.06.06a.SPA.bin
- name: Tag the given image as golden and load it on device
cisco.dnac.swim_workflow_manager:
dnac_host: "{{dnac_host}}"
dnac_username: "{{dnac_username}}"
dnac_password: "{{dnac_password}}"
dnac_verify: "{{dnac_verify}}"
dnac_port: "{{dnac_port}}"
dnac_version: "{{dnac_version}}"
dnac_debug: "{{dnac_debug}}"
dnac_log_level: "{{dnac_log_level}}"
dnac_log: True
config:
- tagging_details:
image_name: cat9k_iosxe.17.12.01.SPA.bin
device_role: ACCESS
device_image_family_name: Cisco Catalyst 9300 Switch
site_name: Global/USA/San Francisco/BGL_18
tagging: True
- name: Tag the specified image as golden for multiple device roles and load it into the device
cisco.dnac.swim_workflow_manager:
dnac_host: "{{dnac_host}}"
dnac_username: "{{dnac_username}}"
dnac_password: "{{dnac_password}}"
dnac_verify: "{{dnac_verify}}"
dnac_port: "{{dnac_port}}"
dnac_version: "{{dnac_version}}"
dnac_debug: "{{dnac_debug}}"
dnac_log_level: "{{dnac_log_level}}"
dnac_log: True
config:
- tagging_details:
image_name: cat9k_iosxe.17.12.01.SPA.bin
device_role: ACCESS,CORE
device_image_family_name: Cisco Catalyst 9300 Switch
site_name: Global/USA/San Francisco/BGL_18
tagging: True
- name: Un-tagged the given image as golden and load it on device
cisco.dnac.swim_workflow_manager:
dnac_host: "{{dnac_host}}"
dnac_username: "{{dnac_username}}"
dnac_password: "{{dnac_password}}"
dnac_verify: "{{dnac_verify}}"
dnac_port: "{{dnac_port}}"
dnac_version: "{{dnac_version}}"
dnac_debug: "{{dnac_debug}}"
dnac_log_level: "{{dnac_log_level}}"
dnac_log: True
config:
- tagging_details:
image_name: cat9k_iosxe.17.12.01.SPA.bin
device_role: ACCESS
device_image_family_name: Cisco Catalyst 9300 Switch
site_name: Global/USA/San Francisco/BGL_18
tagging: False
- name: Distribute the given image on devices associated to that site with specified role.
cisco.dnac.swim_workflow_manager:
dnac_host: "{{dnac_host}}"
dnac_username: "{{dnac_username}}"
dnac_password: "{{dnac_password}}"
dnac_verify: "{{dnac_verify}}"
dnac_port: "{{dnac_port}}"
dnac_version: "{{dnac_version}}"
dnac_debug: "{{dnac_debug}}"
dnac_log_level: "{{dnac_log_level}}"
dnac_log: True
config:
- image_distribution_details:
image_name: cat9k_iosxe.17.12.01.SPA.bin
site_name: Global/USA/San Francisco/BGL_18
device_role: ALL
device_family_name: Switches and Hubs
device_series_name: Cisco Catalyst 9300 Series Switches
- name: Activate the given image on devices associated to that site with specified role.
cisco.dnac.swim_workflow_manager:
dnac_host: "{{dnac_host}}"
dnac_username: "{{dnac_username}}"
dnac_password: "{{dnac_password}}"
dnac_verify: "{{dnac_verify}}"
dnac_port: "{{dnac_port}}"
dnac_version: "{{dnac_version}}"
dnac_debug: "{{dnac_debug}}"
dnac_log_level: "{{dnac_log_level}}"
dnac_log: True
config:
- image_activation_details:
image_name: cat9k_iosxe.17.12.01.SPA.bin
site_name: Global/USA/San Francisco/BGL_18
device_role: ALL
device_family_name: Switches and Hubs
device_series_name: Cisco Catalyst 9300 Series Switches
scehdule_validate: False
activate_lower_image_version: True
distribute_if_needed: True
返回值
常见的返回值已在 此处 记录，以下是此模块特有的字段。
键 |
描述 |
|---|---|
包含 Catalyst Center Python SDK 返回的激活详细信息的字典。 已返回：始终 示例： |