在 Python/HCL 脚本中使用变量

在机器人脚本编辑器中创建 Python/HCL 脚本时，可以创建两种不同类型的变量：

  • Python 变量在脚本主体中定义的常规 Python 变量

  • HCL 变量在变量窗口中定义的 HCL 变量

这两种变量有不同的用途，将在后面的部分中解释。

HCL 还会根据脚本运行所在的 Diligent One 组织以及脚本运行的模式（开发或生产），自动为内置系统变量赋值。有关详细信息，请参阅system_variable[] 方法。

您可以在同一个脚本中同时使用这三种变量。

Python 变量

Python/HCL 脚本中的 Python 变量的工作方式与它们在任何 Python 脚本中的工作方式相同。如果脚本中的值要发生更改，则可以引用脚本逻辑中的变量，而不是文字值。可以在脚本中任何需要的地方创建 Python 变量。

Python 变量示例

以下示例遍历数字列表，并对列表中的每个数字进行平方运算。由于列表中的数字发生变化，脚本逻辑使用变量而不是文字值：

  • list_of_numbers – 分配给数字列表的变量

  • v_number – 分配给列表中单个数字的变量

  • v_squared_number – 分配给 v_number * v_number 结果的变量

每次迭代 for 循环，v_number 和 v_squared_number 变量的值会更新。

list_of_numbers = [1, 2, 3, 4, 5]
for v_number in list_of_numbers:
    v_squared_number = v_number * v_number
    print(v_squared_number)

脚本输出：

1
4
9
16
25

HCL 变量

HCL 变量有两个主要用途：

  • 它们为机器人任务中的任务输入参数提供了依据。

  • 它们提供敏感信息（如密码和验证令牌）的安全存储。

在机器人应用程序中，这些要求都不能通过 Python 变量来实现。必须使用 HCL 变量。

变量窗口

在机器人脚本编辑器中，变量窗口提供了一个用于定义脚本所需的任何 HCL 变量的集中式位置。特别需要指出的是，变量窗口是您定义任何存储由用户在运行或计划机器人任务时提供的输入值的脚本变量的位置。例如：

  • 一个允许用户在运行或计划任务时指定特定部门的 v_department 变量

  • 一个安全地管理访问数据源所需的身份验证凭据（如密码或验证令牌）的变量

您还可以使用变量窗口定义仅在脚本上下文中使用的 HCL 变量 – 例如 v_org_id。但是，在这种情况下，更简单的方法是在脚本主体中创建标准 Python 变量，而不是定义 HCL 变量。

变量定义字段

数目 描述
1

名称包含变量名称，如 v_department
2

类型指定变量类型
3

值在脚本编辑器中以交互方式运行脚本时被分配给该变量的初始值

机器人任务输入字段

数目 描述
4

任务输入指定该变量被在任务设计器中与一个任务输入参数一起使用

  • 需要用户输入运行或计划机器人任务时，用户必须提供输入值

  • 用户输入可选运行或计划机器人任务时，用户可以不提供输入值
5

任务输入标签为该用户在任务设计器中看到的输入参数创建一个标签 – 例如，输入一个部门

任务输入描述（可选）为输入参数创建描述，以添加可能对用户有帮助的其他详细信息

使用变量窗口定义 HCL 变量

在任务设计器中定义一个可与机器人任务输入参数一起使用的 HCL 变量，如 v_department 或 v_password。

说明

HCL 变量主要用于机器人任务输入，如脚本配置选项、密码或令牌。对于不与任务输入一起使用的脚本变量，更简单的方法是在脚本主体中定义标准 Python 变量。

创建基本变量定义

  1. 从机器人脚本编辑器中，单击管理变量 。

  2. 在变量窗口中，单击添加变量。

  3. 指定下列值以创建基本变量定义：

    字段 描述
    名称

    指定变量名称。例如：v_department 或 v_password。

    说明

    存储 Diligent One 令牌的变量必须使用这个确切名称：v_hb_token

    有关获取 Diligent One 令牌的信息，请参阅创建和管理 HighBond 访问令牌。
    类型

    选择变量类型：

    • 对于文本，为字符

    • 密码用于安全地管理密码或令牌

    • 系统用户（随工具包提供）用于在不引用实际用户的情况下，授权执行 Diligent One 平台操作，类似于服务账户

      注意

      请勿编辑系统用户变量，除非您有理由那样做。
    值

    输入一个变量值。密码变量值的长度可达 8 KB。

    您输入的值是在脚本编辑器中以交互方式运行脚本时被分配给该变量的初始值。

    说明

    对于与任务输入相关联的变量，该值仅在脚本编辑器中可用。它不会作为任务设计器中的默认值进行传递。

配置关联的任务输入参数

如果该变量被在任务设计器中与任务输入参数一起使用，您需要指定附加的设置。

  1. 单击切换按钮以启用任务输入。

    启用此设置可在任务设计器中要求用户提供一个值。该变量用于存储在运行或者计划任务时由用户输入的值。

  2. 如果要允许用户跳过提供输入值，请选择用户输入可选。

    某些值可以改变脚本行为，但可能不是该脚本运行所必需的。例如，可选的用户指定开始日期和结束日期可能将分析范围限制到特定范围的数据。

  3. 在任务输入标签中，输入用户将在任务设计器中看到的此参数的标签。

    例如，输入一个部门或者输入您的 Diligent One 令牌。

  4. 可选。在任务输入描述中，添加可帮助用户为该参数提供输入值的其他详细信息。

保存变量定义

  1. 单击保存并关闭以保存该变量定义并退出变量窗口。

  2. 单击保存并提交可保存该脚本并更新变量定义。

    说明

    您需要保存并提交该脚本以永久保存变量定义。

  3. 键入一个提交消息，然后单击提交。

    将出现一条消息，确认提交该脚本是否成功。

重新运行该脚本

保存变量窗口的内容会自动在脚本编辑器中清除会话内存。任何导入的 Python 库、Python 字典、生成的数据帧或存储在内存中的变量值都不再可用。如果您运行一个依赖于以前存储在内存中的某个内容的脚本单元格，则会获得错误或者意外的结果。

要将会话内存恢复至其以前的状态，请重新运行整个脚本，或者重新运行所有必备的单元格。

在脚本中使用 HCL 变量

要在脚本中使用 HCL 变量，需要使用特定 HCL 语法引用该变量。

引用 HCL 字符变量

要引用 HCL 字符变量，请使用以下语法：hcl.variable["变量名称"]

例如：

print(hcl.variable["v_department"])

脚本输出：

运营

有关所需语法的详细信息，请参阅variable[] 方法。

引用 HCL 密码变量

要引用 HCL 密码变量，请使用以下语法：hcl.secret["变量名称"].unmask()

例如：

print(hcl.secret["v_hb_token"].unmask())

脚本输出：

zq025f72938e4s...

有关所需语法的详细信息，请参阅secret[] 方法。

将 HCL 变量分配给 Python 变量

为了方便，您可以将该 HCL 变量值分配给一个常规的 Python 变量，而接下来仅引用该 Python 变量。

例如：

department = hcl.variable["v_department"]
print(department)
token = hcl.secret["v_hb_token"].unmask()
print(token)

脚本输出：

操作
zq025f72938e4s...