Excel 端口 - 知行之桥文档

Excel 端口使用指令碼範本在 Excel 工作表（.xlsx）和 XML 檔案之間轉換資料。

核心功能

在表格（Table）和範本（Template）模式下提供 Excel/XML 的雙向轉換
使用 ArcScript 實現動態資料填充的進階範本系統
支援多個工作表，並可配置行/列範圍

概覽

Excel 端口可以配置為兩種模式：表模式和範本模式。這些模式如下所述。

表模式

Excel 端口的預設模式是 Table。此模式僅支援將檔案從 XLSX 轉換為 XML。若要從 XML 轉換為 XLSX，請使用 Template 模式。在表模式中，端口會像處理 CSV 檔案一樣處理輸入 XLSX 檔案。生成的輸出 XML 檔案具有以下結構，原始檔案中的每一行（記錄）都會成為工作表包裝元素的子元素，而該包裝元素是根元素 Items 的子元素。預設情況下，包裝元素以工作表命名。若要控制包裝元素的名稱，請參閱根元素名稱。

<Items>
 <Sheet1>
  <Record>
   <field_0></field_0>
   <field_1></field_1>
   <field_2></field_2>
  </Record>
 </Sheet1>
</Items>

範本模式

在 Template 模式中，端口使用範本檔案執行轉換。此範本檔案與輸出檔案格式相匹配：

從 XML 轉換為 Excel 時，範本檔案是 Excel 檔案。
從 Excel 轉換為 XML 時，範本檔案是 XML 檔案。

這些範本檔案使用 ArcScript，將輸入檔案中的資料動態填充到輸出檔案中。有關更多資訊，請參閱範本部分。

端口配置

本節包含所有可配置的端口屬性。

設定

配置

與端口核心配置相關的設定。

設定	描述
端口 Id	端口的靜態、唯一識別碼。
端口型別	顯示端口名稱及其用途描述。
端口描述	一個可選欄位，用於提供端口及其在流程中角色的自由格式描述。
Translation Mode	指定使用哪種方法（Table 或 Template）將輸入檔案轉換為輸出格式。有關更多資訊，請參閱概覽。
Column headers	（Table 模式）勾選此項後，轉換會使用 XLSX 檔案第一行中的值作為子元素的元素名稱。如果未勾選，值元素會被賦予 field_0、field_1 等通用名稱。
Template File	（Template 模式）作為輸出範本的檔案。資料會根據範本中的指令碼動態新增到檔案中。有關詳細資訊，請參閱範本部分。

進階設定

前面類別中未包含的設定。

設定	描述
工作表名稱	（Table 模式）要輸出的工作簿工作表名稱清單，以逗號分隔。預設情況下，輸出所有工作表。
Start Row	（Table 模式）工作表中用於輸出表的第一行。
Start Column	（Table 模式）工作表中用於輸出表的第一列。
End Column	（Table 模式）工作表中用於輸出表的最後一列。如果未設定，則將第一行中第一個空單元格前面的列檢測為工作表的結尾。
DateTime Format	（Table 模式）Excel 文件中 DateTime 值使用的格式。
Number Format	（Table 模式）Excel 文件中數字使用的格式。如果希望以相同方式處理文件中的所有數字，請設定此項。
根元素名稱	（Table 模式）在 Table 模式下輸出的每則 XML 訊息中，包裝元素所使用的 XML 元素名稱。支援宏。預設值 `%SheetName%` 以正在處理的工作表為該元素命名。處理多個工作表時，可使用 `%Sequence%` 包含工作表的處理序號。如需詳細資訊，請參閱根元素名稱。
Propagate Merged Cell Values	（Table 模式）在表模式下讀取 Excel 時，勾選此項可將每個合併單元格的值傳播到合併區域中的所有行。此選項可提供更完整的資料，但需要額外讀取 Excel 檔案，這可能會影響大型工作簿的效能。
本地檔案方案	用於為端口輸出的訊息分配檔名的方案。可以在檔名中動態使用宏，以包含識別碼和時間戳等資訊。有關更多資訊，請參閱宏。

進階頁面

訊息

訊息設定確定端口如何搜尋訊息並在處理後管理它們。

注意：以下設定已棄用，預設處於隱藏狀態。只有先前已啟用這些設定或將其配置為非預設值的端口才會顯示它們。若要保留成功處理的檔案副本，請在工作流程中右鍵單擊該端口，選擇顯示成功路徑，然後將成功路徑連線到 File 端口。

設定	描述
儲存到已傳送資料夾（已棄用）	將端口處理的檔案複製到 Sent 資料夾。預設停用。儲存到 Sent 資料夾中的檔案不受靜態加密保護。
已傳送資料夾方案（已棄用）	按所選時間間隔對 Sent 資料夾中的檔案進行分組。僅在啟用儲存到已傳送資料夾時適用。

日誌

用於管理日誌建立和儲存的設定。

設定	描述
日誌級別	指定要記錄在端口日誌目錄中的資訊型別： None - 不建立任何日誌。 Error - 僅當端口遇到錯誤時才建立日誌。 Warning - 僅當端口發出警告時才建立日誌。 Info - 記錄工作流程的一般資訊，包括任何錯誤和警告（如果適用）。 Debug - 記錄成功和失敗工作流程的詳細偵錯資訊。 Trace - 記錄成功和失敗工作流程的詳細跟蹤資訊。請注意：Debug 和 Trace 級別的日誌可能會記錄敏感資訊，包括訊息內容和 SSL 憑證。儘管連線屬性（例如密碼）被遮蔽了，但在與您的組織外部共享它們之前，請檢視此級別的日誌以避免洩漏敏感資訊。
日誌資料夾結構	指示端口根據選定的時間間隔將日誌資料夾中的檔案分組。例如，Weekly 選項指示端口每週建立一個新的子資料夾，並將該周的所有日誌儲存在該資料夾中。空白設定告訴端口將所有日誌直接儲存在日誌資料夾中。對於處理許多交易的端口，使用子資料夾有助於保持日誌的有序性並提高效能。
保留訊息副本	指示端口在日誌目錄中儲存最新訊息副本的切換。請注意，端口每個子資料夾只保留一個訊息，並且端口在再次執行時會覆蓋以前儲存的訊息。

其他設定

設定	描述
處理延遲	放置在交易索引標籤中的檔案在處理前延遲的時間（以秒為單位）。這是舊版設定。最佳做法是使用 File 端口來管理本地檔案系統，而不是使用此設定。

其他設定

特殊設定適用於特定用例。

設定	描述
其他設定	允許在以分號分隔的清單中配置隱藏的端口設定，例如 `setting1=value1;setting2=value2`。正常的端口用例和功能不需要使用這些設定。

自動化

與端口自動處理檔案相關的設定。

自動化設定

設定	描述
傳送	到達端口的訊息是否自動進行處理。

效能

與端口資源分配相關的設定。

設定	描述
最大工作執行緒數	此端口上處理檔案時從執行緒池中消耗的最大工作執行緒數。如果設定，則會覆蓋進階設定頁面的效能設定部分的預設設定。
最大檔案數	分配給端口的每個執行緒傳送的最大檔案數。如果設定，則會覆蓋進階設定頁面的效能設定部分的預設設定。

警示

SLA

範本

XML 到 Excel

下面的 XML 檔案片段在 /Items/Orders 路徑下包含一組元素。

<Items>
    <Orders>
        <OrderNo>PO0012345</OrderNo>
        <Customer>Teddy</Customer>
        <Date>04/19/2023</Date>
        <SubTotal>23.98</SubTotal>
        <Items>
            <Name>Teddy Bear</Name>
            <Cost>14.99</Cost>
            <Desc>Brown</Desc>
        </Items>
        <Items>
            <Name>Truck</Name>
            <Cost>8.99</Cost>
            <Desc>Red</Desc>
        </Items>
    </Orders>
</Items>

要將此 XML 檔案轉換為 XLSX，必須建立一個 Excel 範本。下圖顯示了一個使用 xmlDOMSearch 和 xpath 迴圈遍歷 XML 檔案元素的 Excel 範本範例：

每個 Excel 範本都必須包含以下元素，如上例所示：

靜態列標題。在上例中為 Order Detail。
Excel 批註中的指令碼。此指令碼應使用 xmlDOMSearch 操作，在指定 XPath 處迴圈遍歷輸入 XML。在上例中，它包含在 arc:call 操作中。
Excel 單元格中的指令碼。此指令碼應使用 xpath 格式化器從給定 xpath 讀取 XML 中的值。此 xpath 相對於 xmlDOMSearch 操作中指定的 xpath。

下面描述此範例中 xmlDOMSearch 操作和 xpath 格式化器的詳細資訊。

xmlDOMSearch

xmlDOMSearch 需要兩個參數：

參數	描述
URI	要解析的 XML 檔案的資源路徑。`[filepath]` 屬性會解析為端口的輸入 XML 檔案，URI 幾乎總是應設定為此值。在上例中，檔案路徑使用 urlencode 格式化器進行 URL 編碼，以確保檔案路徑中的特殊字元不會阻止端口讀取檔案：`[filepath \| urlencode]`
xpath	文件中要迴圈遍歷的 XML 路徑。該操作會針對指定 xpath 的每次出現進行迴圈。例如，使用 xpath `/Items/Orders` 時，根 Items 元素的每個子 Orders 元素都會在生成的 Excel 檔案中產生一組新的輸出。

xpath 格式化器

帶有 xmlDOMSearch 操作的 Excel 批註圍繞一塊單元格，這些單元格透過 xpath 格式化器引用輸入 XML。xpath 格式化器從輸入 XML 中指定的 xpath 讀取值。

此 xpath 相對於作為參數提供給 xmlDOMSearch 操作的路徑。

在上例中，第一個單元格使用 [xpath("OrderNo")] 填充。由於此 xpath 是相對路徑，因此該單元格會填充輸入 XML 中以下路徑的值：/Items/Orders/OrderNo。如果 xmlDOMSearch 操作迴圈多次（即找到該操作 xpath 參數的多個例項），則 Excel 批註之間的單元格塊會重複。新單元格會垂直新增，因此在上例中，第二個 OrderNo 單元格會直接位於第一個 Notes 單元格下方。

Excel 到 XML

要從 XLSX 轉換為 XML 檔案，必須使用 ArcScript 命令建立自定義 XML 範本。由於 XML 不支援與 Excel 檔案相同的指令碼功能，因此從 XLSX 轉換為 XML 的結構和格式與從 XML 轉換為 Excel 不同。

由於潛在的輸入和輸出結構範圍很廣，因此沒有適用於所有轉換需求的通用解決方案。下面顯示的範例範本只是眾多可能方案之一。你需要根據自己的需求建立範本。

此範例範本結合使用標準 XML 語法和 ArcScript，從輸入 Excel 檔案讀取、處理並轉換資料。下面的 arc:set 行指定檔案位置以及用於建立該檔案的 Excel 版本。

<!-- Read Excel -->
<arc:set attr="xml.file" value="[FilePath]" />
<arc:set attr="xml.version" value="2007" />

下面的部分指定轉換參數，並將標題對映為標準 XML 格式。參數 [_value | toalphanum | replace(' ','')] 表示 arc:set 命令應從 Excel 檔案解析標題名稱，將其轉換為字母數字格式，刪除空格，並將其指定為 XML 檔案中的標題。

<!-- Always use first sheet-->
<arc:call op="excelListSheets" in ="xml" out="sheet">
  <arc:set attr="xml.sheet" value="[sheet.sheet]" />
  <arc:break />
</arc:call>

<!-- read the headers into an array-->
<arc:set attr="xml.map:headers" value="A1:*1" />
<arc:call op="excelGet" in="xml" out="header">
  <arc:enum attr="header.headers#">
    <arc:set attr="data.headernames#" value="[_value | toalphanum | replace(' ','')]" />
  </arc:enum>
</arc:call>

<arc:set attr="_log.info" value="[data.headernames#1]" />

<arc:enum range="A..Z">
  <arc:set attr="tmp.cells#" value="[_value]" />
</arc:enum>

下面的部分處理剩餘資料，並根據指定結構構建資料列。

<!-- read the remaining cells -->
<arc:enum attr="data.headernames#">
  <arc:set attr="xml.map:[_value]" value="[tmp.cells#[_index]]2:[tmp.cells#[_index]]*" />
</arc:enum>

<!-- build the columns -->
<arc:call op="excelGet" in="xml" out="cols">
  <arc:map from="cols" to="data" map="*=*" />
</arc:call>

<Items>
  <arc:enum attr="data.[data.headernames#1]#"><arc:set attr="tmp.colIndex" value="[_index]" />
    <Record>
      <arc:enum attr="data.headernames#">
        <[_value]>[data.[_value]#[tmp.colIndex] | def]</[_value]>
      </arc:enum>
    </Record>
  </arc:enum>
</Items>

根元素名稱

在表模式中，端口會為處理的每個工作表輸出一則 XML 訊息。預設情況下，每個工作表的資料列會包裝在以該工作表命名的元素中。對於名為 Sheet1 的工作表，輸出如下所示：

<Items>
  <Sheet1>
    <Record>
      <field_0></field_0>
    </Record>
  </Sheet1>
</Items>

如果工作表名稱在不同檔案之間發生變化，包裝元素也會隨之變化。此時，參照該工作表名稱的下游 XML Map 端口將無法比對，除非在對應中使用萬用字元。

使用根元素名稱設定可控制此包裝元素的名稱。該設定預設為 %SheetName%，即如上所示以正在處理的工作表為元素命名。當工作簿包含多個工作表時，端口會為每個工作表輸出一則訊息。使用 %Sequence% 可在元素名稱中包含工作表的處理序號，使每則訊息都有不同的包裝元素。例如，Sheet_%Sequence% 會為處理的第一個工作表產生 Sheet_1，為第二個工作表產生 Sheet_2，依此類推。

元素名稱必須是有效的 XML 名稱。宏求值後，端口會自動將結果中的所有無效字元取代為底線（_），且不會給出提示。例如，Sales Data 會變為 Sales_Data。

使用靜態名稱

輸入固定值，可使每則輸出訊息都使用相同的包裝元素，而不受工作表名稱影響。例如，對於名為 Sheet1 的工作表，並將根元素名稱設定為 Data 時，輸出如下：

<Items>
  <Data>
    <Record>
      <field_0></field_0>
    </Record>
  </Data>
</Items>

當您只處理工作簿的第一個工作表，或者工作表名稱無法預測時，這種方式非常實用。

宏

範例

Excel 運算器

除了知行之橋提供的操作之外，端口還可以提供將功能擴充套件到 ArcScript 的操作。這些端口操作可以像任何其他 ArcScript 操作一樣呼叫，但有兩個細節例外：

它們必須透過 connector.rsc 端點呼叫。
它們必須包含身分驗證權杖。

例如，使用這兩條規則呼叫端口操作可能如下所示：

<arc:set attr="in.myInput" value="myvalue" />
<arc:call op="connector.rsc/opName" authtoken="admin:1j9P8v8b9K0x6g5R5t7k" in="in" out="out">
  <!-- handle output from the op here -->
</arc:call>

下面列出了 Excel 端口功能特定的操作。

excelClose

關閉 Excel 連線。

可選參數

handle：Excel 檔案的控制代碼。

輸出屬性

success：如果連線成功關閉，則為 True。

excelGet

查詢指定的 Excel 工作表。

必需參數

sheet：Excel 工作表的名稱。

可選參數

version：正在使用的 Excel 版本。預設值為 AUTO。僅當使用舊版 Excel 時才需要選擇其他版本。
file：Excel 工作簿的路徑。
handle：Excel 檔案的控制代碼。
map:*：這組輸入包含屬性名稱與要從電子表格中檢索其值的單元格名稱之間的對映。例如，屬性名稱 map:MyValue 的值為 C1 時，會推送一個名為 MyValue 的屬性，其值為工作表中 C1 單元格中的值。可以指定單元格名稱範圍以檢索一系列單元格值。

輸出屬性

*：取決於工作表內容和指定的查詢。如果存在列標題，則會用於命名輸出屬性。

excelListSheets

列出指定 Excel 工作簿中的工作表。

可選參數

version：正在使用的 Excel 版本。預設值為 AUTO。僅當使用舊版 Excel 時才需要選擇其他版本。
file：Excel 工作簿的路徑。
handle：Excel 檔案的控制代碼。

輸出屬性

isHidden：如果工作表在 Excel 中隱藏，則傳回 true。
sheet：Excel 工作表的名稱。 Note that the name ends with $. This is not required when specifying worksheet names to other operations.

excelOpen

開啟現有 Excel 工作簿。

必需參數

file：Excel 工作簿的路徑。

可選參數

version：正在使用的 Excel 版本。預設值為 AUTO。僅當使用舊版 Excel 時才需要選擇其他版本。

輸出屬性

handle：用於執行其他操作的控制代碼。

​核心功能

​概覽

​表模式

​範本模式

​端口配置

​設定

​配置

​進階設定

​進階頁面

​訊息

​日誌

​其他設定

​其他設定

​自動化

​自動化設定

​效能

​警示

​SLA

​範本

​XML 到 Excel

​xmlDOMSearch

​xpath 格式化器

​Excel 到 XML

​根元素名稱

​使用靜態名稱

​宏

​範例

​Excel 運算器

​excelClose

​可選參數

​輸出屬性

​excelGet

​必需參數

​可選參數

​輸出屬性

​excelListSheets

​可選參數

​輸出屬性

​excelOpen

​必需參數

​可選參數

​輸出屬性

核心功能

概覽

表模式

範本模式

端口配置

設定

配置

進階設定

進階頁面

訊息

日誌

其他設定

其他設定

自動化

自動化設定

效能

警示

SLA

範本

XML 到 Excel

xmlDOMSearch

xpath 格式化器

Excel 到 XML

根元素名稱

使用靜態名稱

宏

範例

Excel 運算器

excelClose

可選參數

輸出屬性

excelGet

必需參數

可選參數

輸出屬性

excelListSheets

可選參數

輸出屬性

excelOpen

必需參數

可選參數

輸出屬性