机器人应用程序中的 Python 和 HCL 脚本编写

机器人应用程序提供了固有的基于云的脚本编写功能，您可以将其用于数据分析，或者自动完成贵组织的 Diligent One 工作流的某些部分。机器人应用程序脚本编写将 Python 及其支持的所有资源库的全部功能与我们的自定义 Python 库 HighBond Command Language (HCL) 相结合，用于进行以域为重点的数据分析并实现 Diligent One 自动化。

机器人应用程序继续支持使用 ACLScript 和从 Analytics 上传的脚本进行数据分析和数据自动化。因此，您可以得益于在 ACL（审计命令语言）中的任何现有投资以及行业标准编程语言 Python 和 HCL 提供的所有可能性。

三个类型的机器人

机器人应用程序包含三个类型的机器人。虽然存在很多类似之处，但不同的机器人类型支持不同的脚本编写方案：

ACL 机器人支持使用您从 Analytics 上传的脚本和已计划的任务进行全面彻底的数据分析。脚本可以在云中运行，也可以在本地运行。
HighBond 机器人支持使用直接在该机器人中创建的 Python/HCL 脚本和已计划的任务进行全面彻底的数据分析。脚本只能在云中运行。
工作流机器人支持轻量数据分析，或使用直接在机器人中创建的 Python/HCL 脚本和计划任务或基于事件的任务，自动完成 Diligent One 工作流的某些部分。脚本只能在云中运行。

说明

要访问工作流机器人，您必须被分配拥有专业版订阅的系统管理员用户类型。

目的是让拥有专业版订阅的系统管理员，能够在工作流机器人中配置由 Diligent One 事件触发的任务。此项功能仍在开发中，尚不可用。

机器人类型比较

下面三种机器人类型用于不同的目的，在功能上相互独立。您不能在单个机器人中混用 ACLScript 和 Python/HCL。

机器人特征	ACL 机器人	HighBond 机器人	工作流机器人
预期用途	数据分析和自动化		Diligent One 平台自动化
支持的语言	ACL脚本	Python Pandas、NumPy、Requests 和其他标准 Python库 HCL 自定义 Python 库 (HighBond Command Language)
脚本创作位置	Analytics	机器人
脚本执行位置	云本地部署	云
用于运行任务的选项	已计划临时运行（手动）		由 Diligent One 事件触发已计划临时运行（手动）
最长任务运行时间	基于云的机器人代理：60 分钟本地部署机器人代理：由客户网络控制	无限制说明计划实施 12 小时限制，但尚未实行。如需停止运行时间过长的任务，可在任务运行选项卡中单击取消任务运行。	15 分钟
同时运行的最大任务数	5	5	50
必需的权限	成为机器人的协作者由协作者的机器人角色（所有者、编辑、审核者）控制的访问级别		具有专业版订阅的系统管理员用户类型

机器人应用程序脚本编辑器

HighBond 机器人和工作流机器人包含一个用于创作 Python/HCL 脚本的集成式脚本编辑器，以交互方式运行（手动）。该脚本编辑器模仿了 Jupyter Notebook 应用程序（一个在数据科学社区中流行的开发环境）。该脚本编辑器使用基于单元格的脚本创作方法。

说明

机器人应用程序脚本编辑器设计用于 Diligent One 中的数据分析和自动化。它并不用作一般的 Python 脚本编辑器或 IDE（集成开发环境）。因此，它不支持诸如 Jupyter 或 PyCharm 之类的 IDE 提供的一系列功能。要了解其中一些限制，请参阅机器人应用程序脚本编辑器中不包括的 Jupyter Notebook 功能。

数目

描述

在脚本编辑器中打开的脚本的版本号以及提交消息

包含该脚本的机器人的名称

单元格控件：

运行该单元格
在上面添加一个新单元格（未显示）
在下面添加一个新单元格（未显示）
运行当前单元格以及上面的所有单元格（未显示）
运行当前单元格以及下面的所有单元格（未显示）
删除该单元格（未显示）

显示运行每个单元格的顺序的顺序指示器

有关详细信息，请参阅基于单元格的脚本创作的主要特点。

用于编写脚本代码的单元

有关详细信息，请参阅基于单元格的脚本创作方法。

单元格的显示输出

顶部工具栏：

	在选定单元格的下面添加一个新的单元格
	向上移动选定的单元格
	向下移动选定的单元格
	运行选定的单元格
	按照从上到下的顺序运行所有单元格
	停止脚本执行
	删除选定的单元格
	将该脚本还原至以前提交的版本

变量按钮：打开用于定义 HCL 变量的变量窗口

有关详细信息，请参阅在 Python/HCL 脚本中使用变量。

向 AI 提问按钮：打开向 AI 提问聊天面板，帮助您编写脚本

有关详细信息，请参阅使用机器人中的 AI 脚本助理。

会话文件按钮，显示当前文件计数：打开或关闭会话文件面板

保存并提交按钮：保存该脚本并将其作为新版本提交

基于单元格的脚本创作方法

该脚本编辑器的最显著特征是能够使用多个单元格来包含构成单个脚本的各个代码块。如果您不熟悉 Jupyter Notebook，则基于单元格的脚本创作方法最初可能看起来很复杂。实际上，它易于使用，并且拥有您很快就会赞叹不已的优点。

说明

单元格不会影响脚本的运行方式。无人看管的、计划的脚本执行从上到下逐行进行，而无论单元格是否出现在脚本编辑器中。

基于单元格的脚本创作的主要特点

多个单元格是可选的如果您不愿意，则无须使用多个单元格。您可以使用单个单元格创作并运行整个脚本。
逻辑划分单元格使您可以将脚本划分为您自己选择的逻辑块，按照任何顺序手动逐个运行这些逻辑块，或者将其作为一个完整的序列运行。

例如，一个脚本的基本四单元格布局可能是：
- 第一个单元格导入 Python 库
- 第二个单元格导入数据
- 第三个单元格对数据执行分析
- 第四个单元格输出分析结果
单元格的好处使用单元格进行脚本开发具有下列好处：
- 您可以单独处理单个单元格，测试并改进它们，而暂时忽略其他单元格中包含的脚本逻辑。
- 在您运行初始导入单元格一次之后，您无须在开发和反复测试后续单元格的过程中不断运行它们。
- 您可以使用单元格对脚本施加可视化顺序，使不同逻辑块之间的关系易于您或他人查看和理解。
序列指示器在每个单元格的旁边有一个数值指示器，它显示了在脚本会话期间运行相应单元格的顺序。例如：[7]。

当您运行某个单元格时，该指示器会在考虑您在此期间已经运行的任何其他单元格之后递增。因此，如果您已经在此期间运行了两个其他单元格，或者运行其他某个单元格两次，则指示器会从 [7] 变为 [10]。
会话内存和存储值在脚本编写会话中被保存在内存中的数据帧和变量值被基于您运行单元格的序列进行更新。

通常，您会对单元格进行相应的构建，以使其在计划的无人看管模式脚本执行过程中从上到下按顺序运行。某些数据帧或变量值可能会被基于脚本逻辑逐渐更新。如果您杂乱无章地手动运行单元格，则数据帧或变量值的当前状态可能不是您假定其具有的状态，并且可能出现错误或不准确的结果。要将数据帧或变量值恢复至其预期状态，只需重新运行所有单元格并按照预期顺序引用该数据帧或变量。
单元格输出显示默认情况下，运行单元格后会仅显示该单元格中最后一个表达式的输出。如果您想要查看单元格中多个表达式的输出，您可以将这些表达式放在不同的单元格中。但是，更方便的方法是在脚本编辑器中设置一个配置选项。
- 配置单元格以显示所有表达式的输出：
```
from IPython.core.interactiveshell import InteractiveShell
InteractiveShell.ast_node_interactivity = "all"
```
- 重置单元格以仅显示最后一个表达式的输出：
```
from IPython.core.interactiveshell import InteractiveShell
InteractiveShell.ast_node_interactivity = "last_expr"
```
提示

您可以使用该配置设置根据需要在这两种模式之间来回切换。要了解单元格输出的其他配置选项，请参考 Jupyter 或 IPython 在线文档。

机器人脚本编辑器中的键盘快捷键

脚本编辑器中的键盘快捷键，可为脚本开发提供便利并提高速度。在脚本编辑器中，请使用以下任一方法查看可用的快捷方式列表：

按下 Ctrl+/
单击标题栏中的键盘快捷键图标

可用的快捷方式如下所述。

键盘快捷键	操作
Ctrl + Shift + Enter	运行选定的单元格
Ctrl + Shift + M	按顺序运行所有单元格
Ctrl + Shift + Y	运行选定的单元格和上面的所有单元格
Ctrl + Shift + U	运行选定的单元格和下面的所有单元格
Ctrl + Shift + I	停止脚本执行
Ctrl + Shift + K Ctrl + Shift + 向上箭头	选择上面的单元格
Ctrl + Shift + J Ctrl + Shift + 向下箭头	选择下面的单元格
Ctrl + Shift + H Ctrl + Shift + Home	选择第一个单元格
Ctrl + Shift + L Ctrl + Shift + End	选择最后一个单元格
Ctrl + Shift + A	在上面添加单元格
Ctrl + Shift + B	在下面添加单元格
Ctrl + Shift + D	删除选定的单元格
Ctrl + Shift + Z	向上移动单元格
Ctrl + Shift + X	向下移动单元格

机器人应用程序脚本编辑器中不包括的 Jupyter Notebook 功能

如前所述，机器人应用程序脚本编辑器模仿了 Jupyter Notebook 应用程序。下列 Jupyter 功能未被包括在该脚本编辑器中，尽管随着时间的推移，当该产品继续演变时，其中一些功能可能被包括进来：

单元格级别的操作：
- 撤消/重做单元格操作
- 复制/粘贴单元格
- 拆分/合并单元格
记下单元格（对于文本内容）

将脚本输出保存到日志文件

使用机器人任务运行 Python/HCL 脚本时，您可以选择将脚本输出保存到每个任务运行附带的日志文件中。日志是一个与任务同名的 JSON 文件 (task_name.json)。

若要启用此选项，请在保存并提交脚本版本时，选择将脚本输出保存到任务运行日志文件。可为每个版本的脚本单独配置此选项，因此，如果要保存脚本输出，请确保选择任务运行使用的特定脚本版本的选项。

脚本输出是指脚本生成的 stdout 流中包含的任意内容。stdout 通常是指以交互方式运行脚本时，脚本打印或显示到屏幕上的任意内容。本质上来说，选择将脚本输出保存到任务运行日志文件选项，即表明您将永久捕获屏幕上显示的所有内容。捕获的此类输出在您开发脚本并对其进行故障排除时非常实用，方便查看。

附加信息：

此选项仅适用于任务即使您在机器人脚本编辑器中选择了将脚本输出保存到任务运行日志文件，此选项也仅适用于由机器人任务运行的脚本。如果您在脚本编辑器中以交互方式运行脚本，此选项无效。
任务运行日志文件中的错误消息无论您如何配置将脚本输出保存到任务运行日志文件选项，任务运行日志文件中始终包含 Python 错误消息（stderr 流）。
访问任务运行日志文件任务运行选项卡中的每个任务运行都有一个任务运行日志文件。选择一个任务运行，任务运行详细信息侧面板的输出部分会显示日志文件。您可以将文件下载到计算机，以供审核。

从 ACLScript 迁移到 Python 和 HCL

Python 是一种通用编程语言，并且要比 ACLScript 复杂得多，后者是一种相对简单的脚本编写语言，最初是为审计分析域而设计的。

我们的意图是随着时间的推移，HCL 将复制 ACLScript 中提供的许多命令和函数。要开始使用 HCL——我们的自定义 Python 库，要求您至少具备基本的 Python 技能。对于那些正在寻求从 ACLScript 迁移至 Python/HCL 的人而言，我们的忠告是参加一门优秀的入门级 Python 课程。

Python 编码规范

您将需要习惯某些在 ACLScript 中没有强制执行但在 Python 和 HCL 中强制执行的编码规范：

是否区分大小写 Python 和 HCL 语法区分大小写，而 ACLScript 语法则不区分。

在 Python 中：
- print("Hello World!") 有效
- PRINT("Hello World!") 产生错误
不可缩写 Python 和 HCL 函数、方法和参数名称必须完全拼写出来。与 ACLScript 不同，缩写不受支持。
缩进有影响 Python 使用缩进实施控制结构，如条件性语句和循环。不正确的缩进会导致错误。ACLScript 忽略缩进。

Python 外部库

Python 支持大量外部库或包，安装这些库或包可以扩展核心 Python 安装和 Python 标准库的功能。Python 外部库是一个相关代码模块的集合，设计用于完成核心 Python 和标准库所不能完成的具体功能。或者，使某些功能的完成能够比在核心 Python 中完成的更快、更容易。

说明

当提到可以安装以扩展 Python 的外部代码包时，术语“库”和“包”通常可以互换使用。Python 库和 Python 包之间存在技术差异，但是您在机器人应用程序中使用 Python 时，不需要担心这些差异。

Diligent One Python 中包含的外部库

默认情况下，Diligent One 中安装的 Python 包含某些外部库，因此无需特别安装它们。除了 Diligent 自己的 HCL Python 库之外，您确实需要导入预安装的库，以便在后续的 Python/HCL 脚本逻辑中使用它们。

在 Diligent One Python 环境中预安装的外部库：

库	描述	Python 导入语句
HCL	HCL 库，或 HighBond Command Language 是 Diligent 用于以域为中心的数据分析和 Diligent One 自动化的自定义 Python 库。	不需要
Pandas	Pandas 库为 Python 中的数据操作和数据分析提供了一套功能强大的工具，包括数据帧（类似电子表格或表格的二维数据数组）。	import pandas 或 import pandas as pd （可选为库名称创建一个简短的别名）
NumPy	NumPy 库在 Python 中提供快速而强大的科学计算，包括基本代数和统计运算、高级数学运算，以及在多维数组上构建和执行计算。	import numpy 或 import numpy as np （可选为库名称创建一个简短的别名）
请求	Requests 库提供了一个轻量级语法，用于在 Python 中发出 HTTP 请求并与基于 web 的 API 交互。	import requests 或 import requests as req （可选为库名称创建一个简短的别名）
Cryptography	Cryptography 库支持在 Python 中集成加密算法。	import cryptography 或 import cryptography as crypt （可选为库名称创建一个简短的别名）

安装其他外部库

除了 Diligent One Python 环境中预安装的外部库，HighBond 机器人还支持安装其他外部库。要安装其他库，请使用 pip，这是一个用于下载和安装 Python 软件包的工具。默认情况下，pip 从 Python 软件的开源存储库 Python 包索引 (PyPI) 下载软件包。您也可以使用 pip 从其他地方安装软件包。

例如，要安装 pyexcel（一个用于处理 Excel 文件和数据的 Python 库），请在机器人应用程序脚本编辑器中使用以下命令：

pip install pyexcel

即使安装了外部库，也不能保证机器人应用程序脚本编辑器支持外部库的所有功能。例如，它可能不支持显示某些外部库中可用的图表和绘图。

说明

目前，工作流机器人不支持安装任何其他外部库。

使用 Python 和 HCL 处理 API

在机器人应用程序中，您可以使用 Python/HCL 脚本处理 API，包括第三方 API 和 Diligent One 自带的 API。

说明

如果您在从机器人应用程序发出的 API 请求中明确地指定主机信息，则必须使用 HTTPS 协议。例如：

https://openexchangerates.org/api
https://apis-us.highbond.com

使用第三方 API

要使用第三方 API，请首先在机器人应用程序脚本编辑器中导入 Python Requests 库：

import requests

您现在可以使用 Python 的请求语法发出 API 请求并接收响应。有关在机器人应用程序中使用 Python 发起第三方 API 请求的简单示例，请参阅机器人应用程序脚本和 Diligent HighBond API 入门指引中的第 3 部分: 扩展您的能力。

详细解释如何将 Python 与第三方 API 结合使用超出了我们文档的范围。但是，有许多在线资源可以提供详细的指导。

使用 HighBond API

HighBond API 是 Diligent One 平台面向开发人员的接口。您可以使用该 API 自动执行 Diligent One 交互和工作流，构建报告，以及将 Diligent One 与组织中的其他系统集成。

HCL 包括使与 HighBond API 的交互变得简单的方法。有关详细信息，请参阅HCL HighBond API 方法。

您还可以将 Python Requests 库与 HighBond API 一起使用。但是，为了方便和简单，我们建议使用 HCL 方法。

有关将 Python 和 HCL 与 HighBond API 结合使用的入门教程，请参阅机器人应用程序脚本和 Diligent HighBond API 入门。