Excel 端口 - 知行之桥文档

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

核心功能

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

概覽

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

表模式

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

<Items>
 <Record>
  <field_0></field_0>
  <field_1></field_1>
  <field_2></field_2>
 </Record>
</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 模式）作為輸出範本的檔案。資料會根據範本中的指令碼動態新增到檔案中。有關詳細資訊，請參閱範本部分。

進階設定

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

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

高階頁面

訊息

日誌

其他設定

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

其他設定

自動化

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

自動化設定

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

效能

警示

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>

宏

範例

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

必需參數

可選參數

輸出屬性