編寫 Python

完成必要條件後，便可以在任何可以編寫 ArcScript 的地方讀取和執行 Python 程式碼。這包括 Script 端口、事件、XML Map 端口中的程式碼指令碼等等。要讓的指令碼引擎使用 Python 而不是 ArcScript，必須將 Python 定義為所使用的語言。這可以透過在 arc:script 關鍵字上設定 language 屬性來實現，如下所示：

<arc:script language="python">
# Python code goes here
</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
ArcScriptItem

ArcScriptContext

這表示中 Python 指令碼的主要指令碼上下文物件。它提供類似字典的項存取方式，幷包含日誌記錄功能。此介面提供對 _ctx 變數的存取，您可以使用該變數存取上下文。可用的方法如下：

push
log

ArcScriptItem

這表示指令碼環境中的單個資料項。它提供類似字典的屬性存取方式，並維護值清單。以下變數是自動可用的 ArcScriptItem 例項：

_input
output
_message
result

可用的方法有：

get
clear

從高層次來看，_ctx 提供對指令碼上下文的存取，而 _input、output 和 _message 是預先例項化的 ArcScriptItem 物件。使用語法 _ctx.itemname 可以動態建立或存取自定義項。有關更多資訊，請參閱內建變數和運算器。

內建變數

這些變數用於存取指令碼環境中訊息上下文的核心。您可以使用它們與指令碼引擎中的可用項進行互動。

_ctx

存取指令碼環境的主要變數。它提供：

存取指令碼中所有可用的項
建立新項、推送項以及記錄到應用程式日誌的功能

在以下範例中，呼叫 _ctx 變數的 log 方法，使用 INFO 日誌級別將資訊記錄到應用程式日誌：

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

_input

指令碼引擎的只讀輸入項。可用屬性根據您編寫指令碼的上下文（例如端口的操作型別）而有所不同。例如，在設定為 Transform 操作的 Script 端口中，可以使用以下屬性：

ConnectorId
WorkspaceId
MessageId
FilePath
FileName
Attachment#
Header:*

但是，如果將 Script 端口設定為不向端口提供輸入的 Trigger 操作，則只有 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">
# Check if it's a perishable product list based on the filename
is_perishable = "perishables" in _input.FileName.lower()
# Set a perishable header and value based on the filename
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',
          '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

當上下文中已載入訊息時，提供對當前訊息的存取。只有在特定場景下（例如，上下文中已載入訊息時），端口正在主動處理訊息時，此變數才可用。例如，在操作設定為 Trigger 的端口中，_message 變數不可用，因為在端口完成工作之前，訊息不會出現。當此變數不可用時，會出現 _message is not defined 例外。可以使用以下屬性：

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

下面的範例對訊息正文進行一些簡單的字串操作：

<arc:script language="python">
# The message body in this example is plain text of "Example data for Arc."
# Perform string manipulation
transformed = _message.body.replace('a', '@').replace('e', '3')
print("Original:", _message.body)
print("Transformed:", transformed)
...
</arc:script>

結果輸出被列印到訊息日誌中：

Original: Example data for Arc.
Transformed: 3x@mpl3 d@t@ for Arc.

此範例顯示如何從 _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 項中讀取來源檔案的 address/city xpath，然後使用 Python 將該值修改為前三個字母並全部大寫。新值隨後作為 result 的值傳送：

<arc:set attr="source.city" value="[xpath(address/city)]" />
<arc:script language="python">
city_value = _ctx.source.get("city")
# Normalize: extract from list if needed
if isinstance(city_value, list):
    city = city_value[0] if city_value else None
else:
    city = city_value
# Final logic
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: {}

入門指南

工作流

EDI 交易夥伴管理控制台

端口

對映

系統 API

操作指南

腳本編寫

軟體許可和第三方版權

內建物件介面

ArcScriptContext

ArcScriptItem

內建變數

_ctx

_input

output

_message

result

運算器

log

push

get

clear

​內建物件介面

​ArcScriptContext

​ArcScriptItem

​內建變數

​_ctx

​_input

​output

​_message

​result

​運算器

​log

​push

​get

​clear

內建物件介面

ArcScriptContext

ArcScriptItem

內建變數

_ctx

_input

output

_message

result

運算器

log

push

get

clear