编写 Python

Version 25.2.9314


编写 Python


完成 先决条件 后,知行之桥便可以在任何可以编写 ArcScript 的地方读取和执行 Python 代码。这包括 Script 端口、事件XML Map 端口中的代码脚本等等。

要让知行之桥的脚本引擎使用 Python 而不是 ArcScript,必须将 Python 定义为所使用的语言。这可以通过在 arc:script 关键字上设置 language 属性来实现,如下所示:

<arc:script language="python">
# Python 代码在这里
</arc:script>

Python 直接嵌入到知行之桥的脚本引擎中,这使得熟悉 Python 编写的用户能够使用类似的语法与脚本中的消息和上下文进行交互。

还可以在同一个脚本中使用 ArcScript 和 Python。当已经编写了 ArcScript 代码,但需要使用 Python 实现一些额外的逻辑时,这非常有用。您可以使用 Python 直接访问用 ArcScript 编写的项目,如下例所示:

<arc:set attr="CustomerA.OrderID" value="123456" />
<arc:script language="python">
print("The OrderId for CustomerA is", _ctx.CustomerA.OrderID)
</arc:script>

许多 Python 方法和变量专门用于知行之桥中的消息、项目和属性上下文。

内置对象接口

知行之桥的 Python 实现中使用了两个主要接口。它们包含并提供对以下列出的内置变量的访问:

ArcScriptContext

这代表知行之桥中 Python 脚本的主要脚本上下文对象。它提供类似字典的条目访问方式,并包含日志记录功能。此接口提供对 _ctx 变量的访问,您可以使用该变量访问上下文。

可用的方法如下:

ArcScriptItem

这表示知行之桥脚本环境中的单个数据项。它提供类似字典的属性访问方式,并维护值列表。以下变量是自动可用的 ArcScriptItem 实例:

可用的方法有:

从高层次来看,_ctx 提供对脚本上下文的访问,而_inputoutput_message是预先实例化的 ArcScriptItem 对象。使用语法_ctx.itemname可以动态创建或访问自定义项。有关更多信息,请参阅内置变量运算器

内置变量

这些变量用于访问脚本环境中消息上下文的核心。您可以使用它们与脚本引擎中的可用项进行交互。

_ctx

访问脚本环境的主要变量。它提供:

  • 访问脚本中所有可用的项
  • 创建新项、推送项以及记录到应用程序日志的功能

在以下示例中,调用 _ctx 变量的 log 方法,使用 INFO 日志级别将信息记录到应用程序日志

<arc:script language="python">
...
_ctx.log('INFO', 'Successfully analyzed all data!')
...
</arc:script>

_input

脚本引擎的只读输入项。可用属性根据您编写脚本的上下文(例如端口 操作类型)而有所不同。例如,在设置为 转换 操作的 Script 端口中,可以使用以下属性:

  • ConnectorId
  • WorkspaceId
  • MessageId
  • FilePath
  • FileName
  • Attachment#
  • Header:*

但是,如果将 Script 端口设置为触发操作,且未向端口提供任何输入,则只有 ConnectorId 和 WorkspaceId 可用。

以下示例将端口的名称打印到当前消息的日志文件中:

<arc:script language="python">
...
print(_input.ConnectorId)
...
</arc:script>

此示例获取输入文件,对其进行重命名,记录原始名称,然后使用新名称推送相同的文件:

<arc:script language="python">
originalname = _input.Filename
print("The original filename was ", originalname)
output.Filename = "mynewfile.xml"
output.Filepath = _input.Filepath
</arc:script>

此示例检查输入文件的名称,以确定其是否为易腐烂物品列表。然后,它根据文件名设置易腐烂物品的标头和值:

<arc:script language="python">
# 根据文件名检查是否为易腐烂产品列表
is_perishable = "perishables" in _input.FileName.lower()
# 根据文件名设置易腐烂产品标题和值
output['Header:category'] = 'perishable' if is_perishable else 'non-perishable'
</arc:script>

output

内置项目可作为创建和推送自定义项目的替代方案。与需要显式调用 push() 将其作为输出发送的自定义项目不同,output 项目会在脚本完成时自动推送。只需修改其属性,它就会作为输出发送,无需任何额外的 push() 调用。

可以直接在项目上设置属性,也可以使用 dict 定义属性,也可以对自己定义的项目执行相同的操作。以下示例推送了一个包含一些数据的输出文件:

<arc:script language="python">
output = {'data': 'This is a test'}
output.filename = "foo.txt"
</arc:script>

此示例获取输入文件,对其进行重命名,记录原始名称,然后使用新名称推送相同的文件:

<arc:script language="python">
originalname = _input.Filename
print("The original filename was ", originalname)
output.Filename = "mynewfile.xml"
output.Filepath = _input.Filepath
</arc:script>

_message

当上下文中已加载消息时,提供对当前消息的访问。只有在特定场景下(例如,上下文中已加载消息时),端口正在主动处理消息时,此变量才可用。例如,在 操作 设置为 触发 的端口中,_message 变量不可用,因为在端口完成工作之前,消息不会出现。当此变量不可用时,会出现“_message 未定义”异常。

可以使用以下属性:

  • Header:Message-Id
  • Header:FileName
  • Header:*
  • body

下面的示例对消息正文进行一些简单的字符串操作:

<arc:script language="python">
# 本例中的消息正文为纯文本“Example data for 知行之桥.”。
# 执行字符串操作
transformed = _message.body.replace('a', '@').replace('e', '3')
print("Original:", _message.body)
print("Transformed:", transformed)
...
</arc:script>

结果输出被打印到消息日志中:

Original: Example data for 知行之桥.
Transformed: 3x@mpl3 d@t@ for 知行之桥.

此示例显示如何从_message项中读取 CustomerID 头并将其作为当前消息的日志文件中的条目打印。

<arc:script language="python">
...
print("The data is valid for customer", _message["Header:CustomerID"])
...
</arc:script>

result

一个专门用于 XML Map 端口 脚本节点的特殊变量。它被视为整个脚本的结果。此变量的值将用作地图中节点的值。然而,它也可以用作 Script 端口中的调试工具。

此示例用于 XML Map 端口目标节点的脚本中,它从顶部声明的 ArcScript 项中读取源文件的地址/城市 xpath,然后使用 Python 将该值修改为前三个字母,全部大写。新值随后作为 result 的值发送:

<arc:set attr="source.city" value="[xpath(address/city)]" />
<arc:script language="python">
city_value = _ctx.source.get("city")
# 规范化:如果需要,从列表中提取
if isinstance(city_value, list):
    city = city_value[0] if city_value else None
else:
    city = city_value
# 最终逻辑
result = city[:3].upper() if city else ""
</arc:script>

在此示例中,result 变量用于向 Script 端口的日志文件添加条目:

<arc:script language="python">
result = ["Step 1"]
output = {
  "Filename": "test.txt",
  "Data": "foo"
}
result.append("Step 2")
</arc:script>

脚本输出如下所示:

[2025-06-12T17:14:36.878-04:00][Info] Output File: test.txt
[2025-06-12T17:14:36.883-04:00][Info] Receiving done.
[2025-06-12T17:14:36.883-04:00][Info] Script output:
["Step 1","Step 2"]

运算器

log

log(level, message)_ctx 变量的一个可用方法,允许将条目直接写入知行之桥 应用程序日志。可用的日志级别包括 DEBUG、INFO、WARNING 和 ERROR。

<arc:script language="python">
...
_ctx.log('ERROR', f'Data evaluation failed in connector {_input.ConnectorId}!')
...
</arc:script>

前面的示例生成以下日志条目:

push

push(item) 将提供的项推送为脚本的输出。如果未指定输出,则推送 output 项。

在本例中,在 ArcScriptContext 中创建了一个新的项 foo,并为其分配了一些数据和文件名,然后将其推送出去。

<arc:script language="python">
foo = _ctx.foo
foo.Filename = "test2.txt"
foo.Data = "bar"
_ctx.push(foo)
</arc:script>

get

get(attr) 返回 ArcScriptItem 上指定属性的值。此方法提供了一种通过名称访问项目属性的编程方式。其功能相当于直接使用点符号访问属性(例如 _input.myattr)或使用字典式访问(例如 _input.get('myattr'))。

以下示例将 item 对象上 tags 属性的值列表打印到当前脚本的日志文件中。

<arc:script language="python">
item = _ctx.item
item.name = 'Milk'
item.price = '2.99'
item.tags = ['perishable', 'dairy', 'noreturn']
print(item.get('tags'))
</arc:script>

clear

clear() 清除调用该方法的 ArcScriptItem。该项目保持不变,只是为空。

<arc:script language="python">
product = _ctx.product
product.name = 'Milk'
product.price = '2.99'
product.tags = ['perishable', 'dairy', 'noreturn']
print("Before clear:", product)
# Use the clear() method to remove all items
product.clear()
print("After clear:", product)
</arc:script>

前面的示例产生以下输出:

  • Before clear: {"price":"2.99","name":"Milk","tags":["perishable","dairy","noreturn"]}
  • After clear: {}