ArcScript 簡介

ArcScript 是中內建的一種基於 XML 的語言，可用於編寫自定義處理邏輯。ArcScript 可以輕鬆轉換檔案或訊息，並與其它業務流程整合。包含完整的範例指令碼，用於傳送電子郵件、執行批次處理檔案、處理檔案等。您可以從管理控制檯將這些範例插入到指令碼和事件中。不過，ArcScript 也是一種高階程式語言，能夠控制資料存取和處理的幾乎每一個方面。您可以使用關鍵字、屬性、物件、運算器和物件集來編寫指令碼，並在所有端口的事件、專用 Script 和 REST 端口，以及 XML Map 端口的自定義指令碼選項中使用這些指令碼。

屬性：名稱-值對中的名稱部分，例如 attribute=“address”、value=“123 Pleasant Lane”。
- 使用 # 字元表示屬性是陣列。這表示陣列可以包含多個值，每個值都可以使用從 1 開始的索引來引用。
- 例如，[myitem.myattribute#2] 指向 myattribute 屬性的第二個值。

物件：描述輸入或輸出的一組相關屬性-值對。例如：

Attribute="name" value="Bob"
Attribute="address" value="123 Pleasant Lane"
Attribute="phone" value="123-4567"

物件集：物件的清單，例如包含客戶地址和電話號碼的客戶清單。
運算器：接受物件作為輸入並生成物件集作為輸出的方法的通用名稱。
關鍵字：ArcScript 語句，例如 arc:set。

ArcScript 中的陣列限制為 32768 個成員。

ArcScript 包含許多關鍵字，可用於執行以下操作：

描述指令碼輸入和輸出
使用 if/else 語句和 case 語句等高階程式設計結構控制執行流程
呼叫運算器並定義自己的運算器
建立和修改用作運算器輸入的物件，以及物件集（運算器的輸出）
透過迭代物件集中的物件來處理運算器呼叫產生的物件集

範例指令碼

包含用於自動化常見操作（如傳送電子郵件）的完整程式碼片段。在 Script 端口的設定索引標籤或任意端口的事件索引標籤上，單擊插入片段，然後選擇要執行的操作。必要的程式碼會插入到游標處。以下部分介紹如何使用和擴充套件這些程式碼片段來編寫自定義處理邏輯。

使用事件輸入

每個事件都提供相關輸入，可將其用作運算器的輸入參數。輸入參數由 info 部分中的 input 屬性定義。使用事件的預定義輸入可以處理已傳送或已接收的檔案，或傳送包含任何錯誤訊息的電子郵件。還可以使用其它輸入。例如，After Receive 事件的可用輸入如下：

<arc:info title="After Receive" desc="This event is fired after receiving a file.">
  <input name="WorkspaceId"      desc="The id of the workspace that is receiving file." />
  <input name="ConnectorId"      desc="The id of the connector that is receiving file." />
  <input name="Direction"        desc="The direction of transaction." />
  <input name="Filename"         desc="The name of the file that was received." />
  <input name="FilePath"         desc="The path of the file that was received." />
  <input name="Attachment#"      desc="The path of the attachment was received." />
  <input name="MessageId"        desc="The Id of the transaction." />
  <input name="ErrorMessage"     desc="If an error occurred, this will contain the error message." />
</arc:info>

使用運算器

使用內含的程式碼範例可以呼叫一些內建運算器。下面的範例使用 appSendEmail 運算器在收到檔案後傳送電子郵件。要使用它，只需替換佔位符值：

<!-- Send Email -->
<arc:set attr="email.To"         value="Recipient(s)"/>
<arc:set attr="email.Subject"    value="Before Send"/>
<arc:set attr="email.Message"    value="File [Filename] was processed."/>
<arc:call op="appSendEmail"/>

僅當您此前已在設定（單擊齒輪圖示存取）中配置了郵件伺服器時，上面顯示的指令碼才有效。導航到提醒索引標籤的電子郵件設定部分。appSendEmail 運算器使用同一郵件伺服器。

擴充套件範例指令碼

使用內含的程式碼範例可以將預定義輸入傳遞給運算器。您還可以傳入特定於運算器的輸入。例如，appSendEmail 運算器接受正文文字和附件等多個附加輸入。使用 arc:set 關鍵字提供這些值。使用 arc:call 關鍵字可以呼叫事件中的任何內建運算器，或呼叫 API。使用其它關鍵字可以控制執行流程等。ArcScript 在計算上是完備的，幷包含多種增強功能，旨在讓處理和自動化更簡單。有關 ArcScript 語法及其功能的更多資訊，請參閱指令碼。

ArcScript 中的物件

物件集由物件組成，但在 ArcScript 中，物件本身的用途遠不止作為物件集中的單個部分。它們還用於表示運算器的輸入。

宣告物件

為了提高可讀性並便於日後修改指令碼，知行軟體建議在 ArcScript 中建立顯式輸入物件，並在單獨的行中將其傳遞給運算器。物件透過 arc:set 關鍵字建立、命名並賦予屬性值：

<arc:set item="input" attr="mask" value="*.txt" />

上面的程式碼片段將名為 input 的物件上的 mask 屬性設定為值 *.txt。在這種情況下，輸入物件就像 ArcScript 中的變數。不過，名為 input 的物件從未顯式宣告。相反，當您第一次嘗試為其設定屬性時，該物件就會被建立。在此範例中，如果輸入物件不存在，則會建立該物件並設定 mask 屬性。

您也可以使用“簡寫”方法宣告物件和屬性。例如：

<arc:set attr="colors.myfavorite" value="green" />

此程式碼片段建立一個 colors 物件，其 myfavorite 屬性的值為 green。

透過查詢字串參數傳遞物件

作為建立顯式輸入物件的替代方法，您可以透過 arc:call 查詢字串參數的形式將輸入參數傳遞給運算器。為了說明顯式宣告物件與將物件作為參數傳遞之間的區別，請參考以下幾行：它們宣告一個名為 file 的物件，並將該物件傳遞給運算器以讀取一行內容：

<arc:set attr="file.file" value="[filepath]" />

<arc:call op="fileReadLine" in="file">

要使用查詢字串參數完成同樣的操作，可以改用以下語法：

<arc:call op="fileReadLine?file=[filePath | urlencode]">

使用此格式要求透過 urlencode 參數對參數進行 URL 編碼。這可確保應用程式正確解析檔名中的特殊字元或保留字元，而不會出錯。

選擇屬性值

要引用屬性，請使用 item.attribute 語法（例如 input.mask）。要查詢屬性值，請將屬性名放在方括號（[ ]）中。這會告訴直譯器您要計算該字串，而不是將其解釋為字串文字。例如，請參考以下程式碼片段：

<arc:set item="item1" attr="attr1" value="value1"/>
<arc:set item="item1" attr="attr2" value="item1.attr1"/>
<arc:set item="item1" attr="attr3" value="[item1.attr1]"/>

結果如下：

item1.attr1 被賦予文字字串值 value1。
item1.attr2 被賦予文字字串值 item1.attr1。
item1.attr3 被賦予值 value1，因為字串 [item1.attr1] 會在執行時被計算為 item1 的 attr1 屬性。

可以使用反斜槓逸出字元串文字中的方括號。

預設物件

在 ArcScript 的內部物件堆疊中，始終存在一個隱式、未命名的物件，即預設物件。雖然可以使用此物件編寫完整指令碼，但最佳實踐是根據需要定義自己的顯式輸入和輸出物件。這會讓指令碼更易讀，並降低覆蓋現有屬性的風險。對於簡單的指令碼場景，可以在以下兩種情況下使用預設物件，使指令碼稍短且更易編寫：

呼叫運算器：如果未指定其它物件，預設物件就是傳遞給指令碼所呼叫運算器的物件。這意味著您可以使用 arc:set 將屬性寫入預設的未命名物件，這些屬性會作為輸入傳遞給指令碼中呼叫的下一個運算器。這是提供運算器必需參數的一種方式。
處理運算器或指令碼輸出中的當前物件：如果沒有為運算器結果指定變數名，則在呼叫該運算器的 arc:call 塊中，預設物件會引用該運算器生成的當前物件。

透過省略 ArcScript 關鍵字的 item 屬性即可操作預設物件，如以下程式碼片段所示：

<arc:set attr="path" value="." />

內建物件

除了指令碼中宣告的物件外，指令碼範圍內還提供多個內建物件。內建物件為存取 HTTP 請求、回應等組成部分提供介面。這些物件有助於將 HTTP 請求中的輸入對映到運算器輸入。以下各節介紹這些內建物件。

指令碼輸入（_input）

指令碼輸入可以從 _input 物件讀取。_input 物件包含指令碼執行時 URL 查詢字串中的變數和 POST 資料。如果 POST 資料中存在同名變數，則會覆蓋查詢字串中的值。當您從指令碼中的預設物件讀取值時，實際上讀取的是 _input 中的值；同樣，寫入預設物件的屬性會與指令碼輸入一起作為參數傳遞給運算器。只有 info 塊或指令碼中定義的變數才可在 _input 物件中使用。

_input 在 arc:call 塊內不是預設物件。如果需要存取它，必須按名稱引用。

指令碼輸出（_out[n]）

您可以透過預設物件或內建 _outn 物件存取 arc:call 關鍵字生成的物件集中的當前物件，其中 n 是 arc:call 關鍵字的巢狀級別。例如，如果位於單個 arc:call 關鍵字內部，該物件名為 _out1。如果位於三層巢狀的 arc:call 關鍵字內部，則物件名為 _out3。

HTTP 請求（_request）

您可以存取透過 URL 查詢字串傳入的變數、POST 到指令碼的變數，以及 _request 物件中作為屬性集合的其它變數。要存取特定的屬性集合，請使用集合名稱作為要讀取屬性的字首。例如，[_request.qstring:name] 讀取查詢字串中變數 “name” 的值，而 [_request.form:name] 讀取表單資料中變數 “name” 的值。

屬性	描述
`q[uery]string:*`	存取查詢字串參數的值。
`form:*`	存取表單資料中的變數值。
`server:*`	存取伺服器變數的值。
`body`	存取請求的原始內容（主體）。
`bodybase64`	存取請求的 base64 編碼內容（主體）。
`auth:*`	存取使用者的身分驗證資訊。使用 `[_request.auth:isauthenticated]` 判斷使用者是否已透過身分驗證。
`other:*`	存取請求的其它資訊。使用 `[_request.other:applicationpath]` 檢索應用程式路徑。

HTTP 回應（_response）

_response 物件允許指令碼作者直接寫入 HTTP 回應。您可以設定以下屬性：

屬性	描述
`cookie:*`	在回應中設定 cookie。屬性名是帶有 `cookie:` 字首的 cookie 名稱，屬性值是 cookie 值。
`writefile`	將指定路徑的內容寫入回應。
`redirect`	將重新導向頭傳送到用戶端瀏覽器。這可用於將瀏覽器重新導向到另一個 URL。
`statuscode`	設定回應的 HTTP 狀態碼。
`statusdescription`	設定回應的 HTTP 狀態描述。

HTTP 頭（_httpheaders）

_httpheaders 物件可在指令碼和範本中輕鬆存取 HTTP 頭。您可以讀取此物件來讀取 HTTP 請求頭；也可以寫入此物件來寫入傳出回應頭。例如，可以使用如下行設定內容類型：

<arc:set item="_httpheaders" attr="content-type" value="application/xml"/>

使用 _cookies 物件可以檢索請求中的 cookie，並在回應中設定 cookie。包含多個 key/value 對的 cookie 會表示為與 cookie 的 key/value 對相對應的屬性集合。cookie 名稱會作為集合中每個屬性的字首。

ASP.NET 會話（_session）

ASP.NET 會話變數可透過 ArcScript 中的 _session 物件使用。儲存在會話中的任何物件都可以作為此物件的屬性存取。屬性名錶示用於在會話中儲存該物件的鍵。

訊息（_message）

當檔案透過流程時，應用程式會向檔案新增中繼資料。由原始檔案和應用程式中繼資料組成的結果稱為訊息。 _message 物件在指令碼上下文中提供對訊息正文和中繼資料的存取（也可在能夠解釋指令碼的端口欄位中使用，例如 Email Send 端口中的主題欄位）。

ArcScript 中的陣列限制為 32768 個成員。如果訊息包含重複超過 32768 次的頭，則最舊的頭會從訊息中移除。

中繼資料

訊息中繼資料包括：

一個唯一 ID（稱為 MessageId），無論檔名如何更改，它都可以識別檔案
處理過程中失敗和成功的資訊
在流程中以程式設計方式提升的任何自定義中繼資料

要存取訊息中繼資料，請使用 _message 物件的 header:* 屬性。例如，當在中處理檔案時發生錯誤，會向代表該檔案的訊息新增 x-trapped-errordescription 頭。此頭儲存有關所發生錯誤的資訊，包括髮生錯誤的 ConnectorId 以及錯誤的偵錯資訊。以下語法在指令碼上下文中引用此頭： [_message.header:x-trapped-errordescription]

正文

要存取訊息正文，請使用 _message 物件的 body 屬性，如下所示： [_message.body] 這會以字串形式傳回訊息正文。

新增跟蹤頭

要向訊息新增跟蹤頭，請使用 _message 物件的 trackedheader 屬性，如下所示：

<arc:set attr="output.filepath" value="[filepath]" />
<arc:set attr="_message.trackedheader:myHeaderName" value="Myvalue" />
<arc:push item="output" />

新增自定義頭

要向檔案新增自定義頭，請設定端口推出的檔案物件的 Header:header_name 屬性。為清楚起見，先從一個指令碼開始，該指令碼將輸入檔案的未修改版本作為輸出推出：

<arc:set attr="outfile.FilePath" value="[FilePath]" />
<arc:push item="outfile" />

[FilePath] 變數會解析為輸入檔案的完整路徑（和檔名），因此該指令碼會使輸出檔案與輸入檔案相同。此指令碼中的以下新增內容會在推出檔案之前向檔案新增自定義頭：

<arc:set attr="outfile.FilePath" value="[FilePath]" />
<arc:set attr="outfile.Header:myHeaderName" value="myValue" />
<arc:push item="outfile" />

要讓自定義頭可在日誌中搜尋，請導航到設定 > 高階頁面的進階設定部分中的跟蹤頭欄位，並新增頭名稱。

記錄端口事件

要在 ArcScript 中向 _message 正文新增端口定義事件的日誌記錄，請向訊息新增 log 屬性字首、有效的日誌級別項目以及 value。以下範例向日志檔案新增一個 Info 行，其中包含屬性 value 部分的文字：

<arc:set attr="_message.log:info" value="This is an info level log entry" />

有效的日誌級別項目如下：

Error
Warning
Info
Debug
Trace

對映上下文（_map）

_map 物件可在 XML Map 端口中使用。在 _map 物件中設定的屬性始終可供後續對映使用（換言之，這些屬性不會被清除，且 _map 物件永遠不會超出範圍）。 _map 物件適合儲存在對映中某一點計算出來並在稍後引用的資訊。例如，涉及 EDI 文件的對映可能需要計算文件中行專案的數量，然後在文件末尾的 CTT 段中包含此計數值。可以將行專案計數計算並儲存為 _map 物件的屬性，隨後在 CTT 段對映中引用該屬性。

應用程式日誌（_log）

_log 物件是進入應用程式日誌的掛鉤。將此物件的 info 屬性設定為字串，會使該字串顯示在應用程式日誌中。例如：

<arc:set attr="_log.info" value="this string appears in the Application Log when the script executes" />

您可以在同一指令碼中多次設定此屬性，以將多條訊息記錄到應用程式日誌。無需清除或追加屬性值；按上例設定屬性值即可記錄指定值。

端口（_connector）

_connector 物件提供對當前端口欄位和屬性的存取。可用屬性與端口資料夾中 port.cfg 檔案裡儲存的值相同，應使用以下語法存取： [_connector.propertyName]

使用此物件需要端口中的指令碼上下文。端口的事件索引標籤始終提供此上下文，部分端口還可以在特殊的可配置欄位中計算 ArcScript。

連接器狀態（_state）

_state 物件提供限定到當前連接器例項的持久鍵值儲存。寫入 _state 的值會跨指令碼執行保留，適合重複檢測、查詢表、計數器以及其他需要記住先前值的場景。所有 ArcScript 指令碼上下文均可使用 _state，包括：

beforeSend、afterSend 和 afterReceive 等連接器事件
Script 和 Python 連接器
XML Map 連接器

範例

寫入值：

<arc:set attr="_state.mykey" value="some value" />

讀取值（不存在的鍵傳回空值）：

[_state.mykey]

刪除一個鍵：

<arc:unset attr="_state.mykey" />

刪除指令碼管理的全部鍵：

<arc:unset attr="_state.*" />

該操作不會影響連接器自身的內部狀態項目。

重複檔案檢測範例

<arc:call op="messageRead" out="message">
  <arc:set attr="file.sha1hash" value="[message.data | sha1hash(true)]" />
</arc:call>
<!-- 文件名中的句点不能用于键名，因此先替换为下划线 -->
<arc:set attr="custom.key" value="[_input.filename | replace('.', '_')]" />
<arc:set attr="storedHash" value="[_state.[custom.key]]" />
<arc:if exp="![storedHash | def | equals([file.sha1hash])]">
  <arc:set attr="output.filepath" value="[_input.filepath]" />
  <arc:push item="output" />
  <arc:set attr="_state.[custom.key]" value="[file.sha1hash]" />
  <arc:else>
    <arc:throw code="match" desc="A file with name [_input.filename] and hash [file.sha1hash] was already processed." />
  </arc:else>
</arc:if>

範圍

狀態限定到單個連接器例項，因此使用相同指令碼的兩個連接器不會共享狀態。指令碼寫入的鍵也會自動與連接器自身的內部狀態項目隔離。

鍵名

鍵名遵循標準 ArcScript 屬性名規則：

字元	行為
`@`	作為命名空間字首，前面必須有名稱，例如 `test@`。
`#`	作為陣列字尾，前面必須有名稱；之後的文字必須是非零整數。
`:`	作為字首與名稱分隔符號；不允許第二個 `:`。
`*`	作為萬用字元；可出現多次，但不能位於 `#` 之後。
`.`	不允許，會產生 “Invalid attribute name” 錯誤。

值沒有字元限制。過長的鍵在儲存時會被自動截斷。檔名通常包含句點，因此將其用作鍵之前必須清理，並在讀寫時始終使用清理後的鍵：

<arc:set attr="custom.key" value="[_input.filename | replace('.', '_')]" />
<arc:set attr="_state.[custom.key]" value="[file.sha1hash]" />
[_state.[custom.key]]

入門指南

工作流

EDI 交易夥伴管理控制台

端口

對映

系統 API

操作指南

腳本編寫

軟體許可和第三方版權

範例指令碼

使用事件輸入

使用運算器

擴充套件範例指令碼

ArcScript 中的物件

宣告物件

透過查詢字串參數傳遞物件

選擇屬性值

預設物件

內建物件

指令碼輸入（_input）

指令碼輸出（_out[n]）

HTTP 請求（_request）

HTTP 回應（_response）

HTTP 頭（_httpheaders）

ASP.NET 會話（_session）

訊息（_message）

中繼資料

正文

新增跟蹤頭

新增自定義頭

記錄端口事件

對映上下文（_map）

應用程式日誌（_log）

端口（_connector）

連接器狀態（_state）

範例

重複檔案檢測範例

範圍

鍵名

​範例指令碼

​使用事件輸入

​使用運算器

​擴充套件範例指令碼

​ArcScript 中的物件

​宣告物件

​透過查詢字串參數傳遞物件

​選擇屬性值

​預設物件

​內建物件

​指令碼輸入（_input）

​指令碼輸出（_out[n]）

​HTTP 請求（_request）

​HTTP 回應（_response）

​HTTP 頭（_httpheaders）

​HTTP Cookie（_cookies）

​ASP.NET 會話（_session）

​ 訊息（_message）

​中繼資料

​正文

​新增跟蹤頭

​新增自定義頭

​記錄端口事件

​對映上下文（_map）

​應用程式日誌（_log）

​ 端口（_connector）

​連接器狀態（_state）

​範例

重複檔案檢測範例

​範圍

​鍵名

範例指令碼

使用事件輸入

使用運算器

擴充套件範例指令碼

ArcScript 中的物件

宣告物件

透過查詢字串參數傳遞物件

選擇屬性值

預設物件

內建物件

指令碼輸入（_input）

指令碼輸出（_out[n]）

HTTP 請求（_request）

HTTP 回應（_response）

HTTP 頭（_httpheaders）

HTTP Cookie（_cookies）

ASP.NET 會話（_session）

訊息（_message）

中繼資料

正文

新增跟蹤頭

新增自定義頭

記錄端口事件

對映上下文（_map）

應用程式日誌（_log）

端口（_connector）

連接器狀態（_state）

範例

範圍

鍵名