SARTORIUS Sim Api 軟體使用者指南

SARTORIUS Sim Api 軟體

規格

• 產品名稱：SimApi 指南
• 發布日期：5 年 2024 月 XNUMX 日
• 目的：向 Umetrics Suite 產品提供數據

產品使用說明

SimApis 簡介

• SimApis 用於檢索 Umetrics Suite 產品中的專案建立和模型建構的資料。

取得 SimApis

• 若要取得 SimApis，請參閱官方文件或聯絡客戶支援尋求協助。

SimApi 功能

• SimApis 為 SIMCA 和 SIMCA-online 中的監控、控制和模型建置提供即時資料。

僅限目前資料使用情況

• 建議僅使用當前數據並避免使用歷史數據以獲得最佳效能。

準備 SimApi 安裝

• 安裝前，請確保您的系統符合使用者指南中指定的最低要求。

安裝 SimApi

• 按照使用手冊中提供的逐步說明在您的系統上安裝 SimApi。

為 SIMCA 設定 SimApi

• 根據提供的指南配置 SIMCA 中的 SimApi 設定。

為 SIMCA-online 設定 SimApi

• 設定 SimApi 以便在 SIMCA-online 中執行即時資料擷取和寫回操作。

測試和故障排除

• 安裝後，進行測試以確保功能正常。如果出現問題，請參閱使用者指南中的故障排除部分。

透過 SIMCA-online 進行測試

• 從 SIMCA-online 測試 SimApi 整合以驗證資料檢索。

使用日誌進行故障排除 Files

• 使用 SimApi 日誌 file 識別並解決任何安裝或操作問題。

服務帳戶配置

• 確保SIMCA-online服務帳戶的正確配置，以實現無縫運作。

技術細節

• 有關 SimApis 的深入技術信息，請參閱用戶指南第 7 部分。

SimApis 簡介

• SimApi 是 Umetrics® Suite 軟體與資料來源之間的軟體介面。 SimApi 的主要目的是向 SIMCA®-online 或 SIMCA® 提供數據。
• Sartorius Stedim Data Analytics AB 為許多不同的資料來源開發了 SimApis，例如流程歷史學家和通用資料庫。
• 本文檔介紹了什麼是 SimApi，以及如何在 Umetrics Suite 產品中使用它。您將學習如何規劃和安裝 SimApi、如何排除故障以及如何測試安裝。最後一章包含針對開發人員的 SimApis 技術細節。

SimApi 目的：向 Umetrics Suite 產品提供數據

• SimApi 的主要目的是從資料來源向 SIMCA-online 或 SIMCA 提供資料。資料來源不是SIMCA-online的一部分，但可以是過程歷史學家或其他保存和管理資料的系統。
• SimApi 公開了節點的層次結構，對應於 file 系統。每個節點可以包含其他節點，或者 tags。一個 tag 對應一個變數。對於這些 tags，即可取得數據。圖片顯示的是 tag，Temp，在節點中選擇
• SIMCA-online 中的資料來源為 BakersYeastControlGood。它還顯示從資料來源取得的最新值。

Umetrics Suite 中的 SimApi 使用

• 桌面軟體 SIMCA 可以使用 SimApi 檢索資料以進行專案建立和模型構建，如下圖所示。
• SIMCA-online使用SimApis即時取得資料進行監控與控制，並將資料寫回資料來源。下圖顯示了 SimApi 在由資料來源、SIMCA-online 伺服器和客戶端組成的系統中的位置。

常用 SimApis

• 最廣泛使用的 SimApis 是：
• PI AF SimApi 用於連接到 Aveva（以前稱為 OSIsoft）PI 系統。
• OPC UA SimApi
• ODBC SimApi – 用於對 SQL Server 或 Oracle 等資料庫的常規訪問
• 所有可用的 SimApis 及其功能均列在第 3 段。

用於模擬資料的DBMaker SimApi

• DBMaker是隨SIMCA-online伺服器安裝提供的應用程式。它透過使用預先載入的資料表來模擬資料來源（例如過程歷史記錄），其中觀察結果透過 DBMaker SimApi 逐一提供給 SIMCA-online。
• DBMaker 僅用於演示目的，不能用於來自資料來源的即時資料的生產。請參閱內建協助以了解有關 DBMaker 的更多資訊。

附加文檔

• 本文檔是一系列相關文件中的一份，每份文件都有不同的重點和目標受眾：

來源	什麼	在哪裡
SIMCA-在線 web 頁	介紹資訊和下載	sartorius.com/umetrics-simca- 在線的

SIMCA-線上閱讀與安裝.pdf	安裝以及如何開始使用 SIMCA-線上演示數據	在安裝 zip 中 file
SIMCA-線上實施指南	概述 SIMCA-online 功能，將其與其他 Umetrics Suite 軟體進行比較，描述成功部署的要求和最佳實踐以及逐步安裝說明。	sartorius.com/umetrics-simca- 在線的
SimApi 指南	準備和執行 SimApi 安裝，包括故障排除。還包含有關開發人員的 SimApis 的技術細節。	sartorius.com/umetrics-simapi
SimApi 使用者指南	每個已發布的 SimApi 的文檔，包括功能、安裝說明和配置細節。	sartorius.com/umetrics-simapi
SIMCA-線上技術指南	SIMCA-online 伺服器安裝規劃、故障排除以及深入了解 SIMCA-online 工作原理的技術參考。	sartorius.com/umetrics-simca-在線的
SIMCA-線上協助	Web-有關如何使用 SIMCA-online 以及 SIMCA-online 如何運作的協助。	在軟體本身中，以及 sartorius.com/umetrics-simca
SIMCA-在線 Web 客戶端安裝指南	描述 SIMCA-online 的安裝 Web 客戶。	sartorius.com/umetrics-simca-在線的
Umetrics 知識庫	可搜尋的資料庫，其中包含有關每個已發佈軟體版本的文章、技術文章以及 Umetrics Suite 產品中的已知問題。	sartorius.com/umetrics-kb
SIMCA 說明/使用者指南	如何使用桌面 SIMCA 建立專案和建模資料。	在 SIMCA 和 sartorius.com/umetrics-simca
支援 web 頁	如何獲得技術支持。	sartorius.com/umetrics-support

技術支援

• Sartorius 線上支援團隊回答有關 SimApis 的技術問題，也可以將有關 SimApis 增強功能的請求轉發給相關人員。了解更多信息 sartorius.com/umetrics-support.

取得 SimApis

• 我們提供可用的 SimApis 文件和安裝程序鏈接，網址為 sartorius.com/umetrics-simapi.
• 每個 SimApi 都記錄在其使用者指南中。
• 您現在正在閱讀的 SimApi 指南在 SimApi 規劃、安裝和故障排除方面對該資訊進行了補充。

SimApi 功能

• 並非所有資料來源都是相同的。 SimApi 不需要實作規格中的所有功能。由於這些原因，不同的 SimApis 提供不同的功能。下表列出了可用的 SimApis 及其功能。
• 下面解釋了這些特點。請注意，該表有單獨的列，分別顯示 SIMCA-online 和 SIMCA 中可用的功能。

特徵	目的	SIMCA-線上使用	SIMCA 使用
當前數據	從資料來源讀取具有最新值的單一觀察值。	即時正常執行	–
史料	使用來自資料來源的歷史資料一次讀取多個觀察值。	追趕和預測過去的數據，使用建立項目 File > 新	資料庫匯入精靈用於匯入流程資料以建立模型。
離散數據	從資料來源讀取實驗室/IPC資料。每批有許多觀察結果。	適用於為離散資料檢索配置了階段或批次條件的批次項目。	–
批次數據	讀取批次條件和最終品質屬性（或	批次條件或局部定心。	資料庫導入精靈讀取批次條件

特徵	目的	SIMCA-線上使用	SIMCA 使用
	其他 MES 類型資料）。每批觀察一次。		批次級模型創建。
批次節點	指定特定批次的開始時間和結束時間（活動批次為空）。 列舉某個時間範圍內存在的所有批次。	執行批次配置時所需。	資料庫匯入精靈選擇要匯入的批次。
寫回 – 連續數據	將連續資料（例如預測）寫回資料來源。	從批次演變層級寫回數據，用於控制顧問或連續配置	–
寫回 – 離散	將離散資料（例如預測）寫回資料來源。	在批次演進層級對離散資料擷取配置的階段進行批次配置的寫回	–
寫回 – 批次數據	將批次級資料（例如預測或最終品質屬性）寫回資料來源。	以批次等級寫回批次配置	–
節點層次	SimApi 支援節點層次結構，類似 file 系統。每個節點可以包含 tags 和其他節點。層次結構使得管理大量節點更加容易，且 tags.	在所有地方都得到支持 tags 被使用。
大批 tag 擴張	一個數組 tag 儲存多個值。 SimApi 擴展了陣列 tag 對許多個人 tags，數組中每個元素一個。	支援範圍 tags 用於連續數據。每個擴展 tag 必須對應到 SIMCA 項目中的變數。
多種資料來源	SimApi 可以連接到多個資料來源，或支援具有單獨設定和日誌的多個實例 file每個實例的 s。	連接到多個相同類型的不同資料來源。	–
連結彈性	如果 SimApi 與資料來源斷開連接，它將嘗試自動重新建立連接。	無需重新啟動 SimApi 即可重新建立與資料來源的連線。	–
內部開發	SimApi 由以下公司開發、提供和支援

不建議只使用當前數據，而不使用歷史數據

• 一些 SimApis，尤其是 OPC DA，僅支援讀取當前數據，而不支援歷史數據。
• 僅支援目前資料的 SimApi 不能用於桌面 SIMCA，因為它無法讀取建構模型的歷史資料。
• 對於 SIMCA-online，我們強烈建議一個資料來源和 SimApi，它不僅提供用於即時執行的當前數據，還提供歷史數據，以便能夠預測和追趕過去的數據。 SIMCA-online 根據需要自動在即時資料和歷史資料之間切換，且無法關閉。
• 僅提供當前資料而不提供歷史資料的資料來源可以用於SIMCA-online中的連續項目，但對於批量項目，則需要歷史資料。

準備安裝 SimApi

• 本節介紹成功安裝 SimApi 的重要資訊。

64 位元或 32 位元 SimApis

• 每個 SimApi 都有 32 位元和 64 位元版本。
• SIMCA-online 和 SIMCA 是 64 位元的，並且需要 64 位元 SimApis 變體。舊版 32 位元 SimApis 仍然適用於舊安裝。

日誌位置 file 和設置

• SimApi 儲存其日誌 file位於隱藏的 Program Data 資料夾1：
  %programdata%\Umetrics\SimApi，其中 %programdata% 對應到您電腦上的實際資料夾。預設為 C:\ProgramData。
• 每個 SimApi 通常都使用自己的日誌 file，類似 SIMCA-online 伺服器日誌 file 將根據日誌等級設定包含更多或更少的資料。這 file 對於故障排除很有用。紀錄 file 被命名為
  .log 其中例如，您正在安裝的 SimApi 是amp樂 PIAFSimApi。另請參閱下一部分以了解 SIMCA-online SimApi 實例名稱。
• 此資料夾還包含 XML 中的 SimApi 設定 file 命名.xml。
• 大多數 SimApis 都有圖形使用者介面，可以更改 xml 中的設置 file，但有些則需要直接在 XML 中輸入更改 file 使用文字編輯器，例如記事本。查看每個 SimApi 的使用者指南。

File 當命名實例與 SIMCA-online 一起使用時的名稱

• 在SIMCA-online中，每個SimApi實例都有自己的配置 file 並記錄 file 與每個 SimApi 的多個實例一起工作。這些的名字 files 以實例名稱為後綴，如 SIMCA-online 伺服器選項對話方塊中的 SimApi 標籤所示。
• 以下前ample 顯示了這些的命名 files，其中需要用 SimApi 名稱替換。
• 新增實例時給出的設定名稱：OmegaServer
• 配置 file 姓名： Omega伺服器
• 紀錄 file 姓名： Omega伺服器日誌
• 請注意，通用 file .紀錄 file 仍在創建。這個日誌 file 包含由於技術原因無法定向到日誌的條目 file 的實例..
• 預設情況下，此資料夾在 Windows 中是隱藏的。看到它 File 資源管理器你配置它顯示隱藏 file秒。請注意，您可以透過在 File Explorer 的網址列。
• 請注意，SIMCA 不支援 SimApi 的多個實例，因此使用如上所述的沒有實例名稱的名稱。

網路規劃

• 您應該將 SIMCA-online 伺服器放置在靠近網路中資料來源的位置。這確保了SIMCA-online與其資料來源之間的快速連接。
• 網路設備可能會幹擾SIMCA-online與資料來源之間的連線。

使用者帳戶和資料來源權限

• 資料來源通常控制對其資料的存取。這通常透過使用者名稱和密碼來實現，但也可以使用基於 IP 位址或 DNS 的限制（例如ampAveva PI 系統中的 PI Trust)。
• 可以透過不同的方式向資料來源提供使用者名稱和密碼：
• SimApi 以在伺服器電腦上執行桌面 SIMCA 或 SIMCA-online 服務帳戶的使用者的 Windows 使用者身分運作。 SimApi 可以使用該帳戶連接到資料來源。這就是 OPC I 和 PI SimApi 的工作方式，如果您在配置時不提供憑證，則是 ODBC 的工作方式。
• 對於通用 ODBC，您可以使用 Windows 中「開始」功能表上的 ODBC 資料來源管理器應用程式。
• 一些資料庫提供者為其資料庫提供自己的驅動程式和工具。例如 Oracle 資料庫amp例如，使用 Oracle 資料存取元件 (ODAC)。
• 某些 SimApis（例如 PI AF 和 ODBC）具有配置對話框，可將加密憑證儲存在 SimApi XML 配置中 file.
• PI 在 PI 伺服器電腦上的 PI 系統管理工具中也提供了各種安全選項。請參閱 PI AF SimApi 使用者指南，以了解更多資訊。即使您使用舊版 OSIsoft PI SimApi，本指南也很有用。
• OPC DA 和 HDA 使用 DCOM 作為資料來源和 SimApi 之間的傳輸。 DCOM 使用 Windows 中的元件服務工具 (DCOMCNFG.EXE) 進行設定並使用 Windows 驗證。
• 對於較舊的 OSIsoft PI SimApi（而不是較新的 AF SimApi），OSIsoft AboutPI-SDK 應用程式 (PISDKUtility.exe) 用於設定與 PI 伺服器的連線。

驗證資料來源連接
當您想要在電腦上安裝 SimApi 時，使用另一個工具驗證從該電腦到資料來源的連線會很有用：

• Windows 中的 ODBC 資料來源用於設定和測試通用 ODBC。請注意，64 位元 Windows 上有兩個版本：一個用於 32 位元應用程序，一個用於 64 位元。使用 ODBC 設定精靈末端的測試資料來源按鈕來驗證與資料庫的連線。我們建議您將資料來源配置為系統 DSN。
• 來自資料庫提供者的特定於資料庫的連接工具，例如 Oracle 資料存取元件。
• PI System Explorer 可用於測試與 PI AF 伺服器的連線。它是 PI AF 用戶端的一部分，是 PI AF SimApi 的先決條件。
• Unified Automation 的 OPC UA Expert – UaExpert 是 OPC UA 伺服器的跨平台測試用戶端。
• PI-SDK 應用程式 (PISDKUtility.exe) 可用於測試連接性並 view SIMCA-online 嘗試連接到 PI 伺服器時可能記錄的任何錯誤訊息。這僅適用於舊版 OSIsoft SimApi，不適用於 PIAF。
• PI 系統管理工具用於 PI 伺服器電腦上從該側進行故障排除。例如ample，尋找阻止從 SIMCA-online 伺服器存取的安全性問題。觀看此 YouTube 視頻，以了解有關 PI 系統故障排除的更多資訊。
• 安裝合適的插件後，Excel 可用於從 ODBC 連接和大多數其他系統取得資料。
• Matrikon OPC Explorer for Ior HDA（這些是獨立的工具）可用於測試 OPC 連接，而 Matrikon OPC Analyzer 可用於診斷 OPC 連接問題。從以下位置下載這些免費工具 https://www.matrikonopc.com/products/opc-desktop-tools/index.aspx
• OPC 救援（針對 DInd HDA）來自 OPC 訓練學院 web 網站“使用戶能夠輕鬆診斷通信和安全問題，並只需按一下按鈕即可立即修復。無需學習配置 DCOM，即可完成所有這些操作”

安裝 SimApi

以下是在 PC 上安裝 SimApi 的方法：

1. 閱讀您正在安裝的 SimApi 的使用者指南。它包含 SimApi 的具體內容，補充您現在正在閱讀的一般說明。
2. 安裝並配置 SimApi 使用者指南中提到的任何先決條件（例如amp資料庫驅動程式或 SDKs)
3. 執行安裝程式來安裝 SimApi。安裝與您將執行的軟體相符的 64 位元 (x64) 或 32 位元 (x86) 版本。
4. 請依照以下章節的說明在 SIMCA-online 或 SIMCA 中設定 SimApi，並參閱 SimApi 的使用者指南以了解可用設定的描述。
5. 啟動SIMCA-online伺服器。請注意，這可能需要一些時間，因為在初始化 SimApi 時，它將列舉所有 tags 在資料來源中。
6. 透過獲取一些數據來測試 SimApi。對於 SIMCA-online，您可以使用 File > 依照 6.1 所述的方式擷取。
7. 如果 SimApi 無法如預期運作，請參閱 SimApi 日誌 files 進行故障排除，以及 SimApi 使用者指南。

設定 SimApi 以在 SIMCA 中使用

以下是如何在 SIMCA 中使用 SimApi：

1.  透過以下方式之一開始資料庫導入：
   • a. 要在 SIMCA 中建立新項目： File > 新的常規項目或新的批量項目。在“主頁”標籤上選擇“從資料庫”。
   • b. 若要匯入 SIMCA 中現有項目中的資料集：從開啟的 SIMCA 項目的資料標籤上的資料集中匯入。
2. 點擊“新增資料來源”
3. 選擇 SimApi 作為連線類型，按一下 … 按鈕並找到.dll，然後按一下開啟。
4. 按一下配置並參考單獨的 SimApi 使用者指南以了解如何進行設定。
5. 按一下測試資料來源連線以驗證您是否可以連線到資料庫。如果有很多 tags 在資料來源中。
6. 按一下“確定”，完成配置。
7. 請參閱 SIMCA 協助以了解如何處理匯入的資料。

設定 SimApi 以在 SIMCA-online 中使用

• 重要提示：要使用 SimApi，需要 SIMCA-online 伺服器許可證。 SIMCA-online 的示範安裝不允許使用 SimApis。
• 若要將 SimApi 新增至系統，請在伺服器 PC 上執行 SIMCA-online 伺服器選項。了解 SICMA 線上幫助主題在伺服器上新增和配置 SimApi 中的詳細步驟。
• 提示：如果您對 SimApi 進行了更改，則可以從伺服器選項單獨重新啟動該 SimApi，而無需重新啟動整個伺服器。
• 若要設定此 SimApi 的多個實例，請重複上述步驟並為每個實例使用唯一的名稱。了解有關不同日誌和配置的更多信息 files 針對 4.2 中的實例。

測試和排除 SimApi 故障

• 本章介紹有關 SimApi 安裝的測試和故障排除。

從 SIMCA-online 測試 SimApi

• 一旦 SIMCA-online 伺服器成功啟動，您就可以在 SIMCA-online 中測試您的 SimApi（如果伺服器未啟動，請參閱 6.2）：
• 在 SIMCA-online 用戶端中登入伺服器，然後導航至 Extract File 選項卡。 Extract 透過取得數據來幫助您測試 SimApi：
• SimApi 的節點（「資料夾」）顯示在左側框中。 Tags 所選節點的顯示在右上角。
• 只需單擊即可快速測試當前數據 view> 上 tags 提供連續的製程資料（見截圖）
• 右鍵點選節點可以尋找特定時間範圍內的批次。該節點必須是了解批次的批次節點。
• 選擇 tags 在“提取”中按“下一步”，完成精靈以使用不同的資料檢索模式獲取資料：當前資料、歷史資料、大量資料和離散資料。
• 使用其工具將提取的資料與您在資料來源中看到的資料進行比較。了解有關在 7.13 中測試和驗證 SimApi 的所有功能的更多資訊。

使用 SimApi 日誌解決 SimApi 問題 file

• 如果伺服器沒有啟動，SimApi 沒有如預期運作或提取失敗，您需要查閱 SimApi 日誌 file 它會告訴你問題是什麼。在 SimApi 日誌中啟用偵錯等級日誌記錄以取得完整詳細資訊。見 4.2。
• 注意：SIMCA-online 伺服器日誌在這裡不太有用。它們將顯示伺服器如何載入和初始化 SimApi，但 SimApi 的具體細節在其日誌中 file.

使用正確的SIMCA線上服務帳戶

• 當您測試對資料來源的存取權時，請記住您是作為伺服器電腦上的特定使用者登入的（通常是 Windows 網域中您自己的使用者帳戶），但 SIMCA-online 伺服器服務帳戶是不同的帳戶，預設為 LocalSystem，與您的使用者帳戶相比具有不同的存取權限。
• 因此，以您的帳戶執行時間測試可以成功，但 SIMCA-online 無法連接到資料來源的情況並不少見。
• 為了解決此問題，必須授予 SIMCA-online 伺服器服務所使用的帳戶存取權限。通常，您將 LocalSystem 變更為特定的網域服務帳戶，並向該帳戶授予權限。請注意，如果 SimApi 使用在 SimApi 配置中設定的憑證，則這不適用，因為這些憑證優先。

SimApis 的技術細節

• 本章介紹了 SimApi 的工作原理的技術細節。它主要針對想要了解 SimApis 以便為資料來源實作 SimApi 的開發人員。
• 開發人員也應該閱讀本文檔的前面部分，以了解 SimApis 的介紹和功能的高級描述。

何時考慮開發 SimApi，何時不考慮開發？

在考慮為資料來源開發 SimApi 之前：

1. 調查是否已經有可以使用的 SimApi。也許您可以在資料來源中啟用某些功能來使用現有的 SimApis 之一，例如 OPC UA。
2. 仔細閱讀本文檔及其參考資料，並調查您的資料來源是否符合要求：例如amp例如，它需要足夠快，不僅提供當前數據，還提供歷史數據。

• 基於這些原因，我們不建議開發連接到低階硬體或儀器的 SimApi。最好將這些儀器連接到過程歷史資料庫（例如 Aveva PI System），讓其從儀器獲取數據並將其歷史記錄化。然後可以使用 PIAF SimApi 將資料從 PI 取得到 Umetrics 產品。

SimApi 開發和 SimApi 規範

• SimApi 規範 SimApi-v2 包含 SimApi DLL 需要實現的 SimApi 中所有 C 函數的文檔以及如何開發 SimApi 的一些指導。
• 在大多數情況下，使用 C 或 C++ 實作 SimApi 處於不必要的低水準。
• 實作 SimApi 的推薦且更簡單的方法是基於 Examp我們提供的leSimApi原始碼。這是前任ample SimApi 實作處理 C 介面並將其轉換為實際實作的 .NET Framework。它還具有用於日誌記錄、設定、配置 GUI 和其他框架程式碼的框架程式碼。
• 為了開發 SimApi，開發團隊需要具備 Windows 開發、.NET Framework、C 或 C++ 的經驗。還需要對 SimApi 應該連接的資料來源有充分的了解，因為 SimApi 的目的是將來自 SIMCA-online 或 SIMCA 的資料請求轉換為資料來源的 API。 SimApi 的實施絕不是一個一次性的項目，但通常需要持續的支援和偶爾的維護。

讀取或寫入數據

• SimApi 的主要任務是從資料來源提供資料。這稱為讀取資料。
• 大多數 SimApi 實作也支援寫入資料。這意味著透過 SimApi 將資料寫回資料來源。寫入資料是 SIMCA-online 中的可選功能。

Tags 和節點

• A tag 是資料來源中列或「變數」的識別碼。一個 tag的名字被用來識別 tag。節點內的名稱必須是唯一的。 SIMCA-online 18 是第一個支援包含子節點的節點的版本，並且 tag 同名。例如ample：節點 Parent 可能有一個名為 Batch 的子節點和一個 tag 稱為批次處理。
• 節點是 tags。一個節點也可以包含其他節點，就像 file 系統資料夾中有資料夾。
• 就像在一個 file 系統、節點和 tag 名稱可以組合成唯一識別一個的完整路徑 tag。這 tag 在 SIMCA-online 或 SIMCA 中選擇時使用路徑 tags 使用。一個 tag 路徑以 SimApi 實例名稱開頭，後面跟著節點結構，以 tag 名稱，每個項目以冒號 (:) 分隔。例如ample“：ODBCSQLServer：節點：感測器Tag1”。

SimApi 枚舉 tags 和啟動時的節點

• SimApi 實作瀏覽伺服器中的節點並 tags 在初始化 SimApi 時在資料來源中追蹤它們，以便用於枚舉的各種 SimApi 函數 tags 並且節點可以實現。
• SimApi 初始化不僅在伺服器啟動時發生，還可以由使用者在 SIMCA-online 使用刷新 SimApi 功能重新觸發。

區分大小寫 tag- 和節點名稱

• Tag 名稱和節點名稱區分大小寫。
• 因此， tag 稱為“tag1” 不同於 “Tag由於“T”的大小寫不同，因此我們將其重新命名為“1”。我們建議不要使用 tags 或僅大小寫不同的節點名稱。

連續製程節點 

• 當節點包含 tags 有了連續的過程數據，就可以稱之為過程節點。以下兩個螢幕截圖顯示了包含資料的流程節點的表格表示，後面是一張顯示選擇時節點外觀的圖片 tags 在 SIMCA-online。

連續製程節點必須獨立於批次、運作或時間

• 為了在 SimApi 中正常運作，節點必須獨立於批次、運行或時間。在 SIMCA-online 中，擁有包含特定批次或時間範圍資料的節點無法正常運作，因為專案配置只能讀取該批次的數據，而不能用於其他批次。
• 相反，在執行測量的過程中，一個節點應該映射到一個或多個實體單元。

批次編號 tag 批次專案執行所需的連續流程節點

• 每一個連續製程必須有一個 tag （變數）保存每個觀察值的批次標識符。 SIMCA 或 SIMCA-online 使用此批次識別碼來了解每個觀察結果屬於哪個批次。
• $BatchID tag 在 7.4.3 的螢幕截圖中就是這樣一個例子amp勒。
  雖然不是必需的，但建議擁有 tag 在顯示流程目前階段或步驟的流程節點中。這 tag 然後可以在 SIMCA-online 或 SIMCA 匯入資料時在階段執行條件中使用。值 tag 例如amp例如「階段 1」、「清潔」、「階段 2」。

批次上下文節點

• 批次節點是追蹤批次的節點；它們的批次標識符、開始時間和結束時間。這是SIMCA-online批量執行專案的要求。一個資料來源可以有多個批次節點，以不同的方式公開批次處理。使用者選擇適用於其應用程式的批次節點。這個前任ample 公開跨越兩個不同單元的批次：
• /Factory1 –Unit1 和 Unit2 的聚合生命週期批次。
• /Factory1/Unit1 – 僅在 Unit1 中生存的批次
• /Factory1/Unit2 – 僅在 Unit2 中生存的批次
• 如果您的資料來源中沒有批次節點，您可以使用 SIMCA-online 中的批次上下文產生器。請參閱內建說明。
• 可選批次數據
• 批次節點也可以包含批次資料；整批僅有一次觀測的數據。注意 tags 具有批次資料的節點不需要位於具有批次節點的全部功能的節點中。 SimApi 支援讀取批次資料就足夠了 tags。在 7.6 中了解有關批量資料的更多資訊。
• 這是一個前任amp批次節點的檔案：
• 注意：以上螢幕截圖取自與 SIMCA-online 捆綁在一起的 DBMaker。要在 DBMaker 中親自查看，請點擊 View 點擊麵包酵母資料庫上的資料按鈕顯示兩個窗口，其中一個是批次節點，另一個是流程資料。

資料類型：數值資料、文字資料和缺失資料

• 對於每個 tag例如，SimApi 可以支援三種類型的資料：numeric、text、t 和 missing：
• 數值資料通常是製程參數的實際值，例如ample 6.5123。 SimApi 只能處理 32 位元單精確度浮點數值。單精準度浮點格式-維基百科。資料來源中的所有其他數字資料類型都應轉換為浮點數。因此，它們可以處理大值和小值，但只有大約 6 或 7 位有效數字。在技​​術指南中了解更多。
• 這可能會導致大整數或較大且有小數的實數的精度損失。有關詳細信息，請參閱技術指南。
• 文字/字串資料用於批次ID、階段執行條件或定性變數。文字的值 tag 資料區分大小寫。這意味著“running”的值與
  「跑步」。 SimApi 不直接支援日期時間變量，但它們可以作為格式為 YY-MM-DD HH:MM 的字串傳回（例如ample “2020-09-07 13:45”).
• 缺失值意味著沒有值可返回，即沒有資料。
• 傳回什麼類型取決於 SimApi 的實作。 SimApi 了解資料來源中的數據，並應傳回最適合的資料類型。

三種資料檢索模式：連續、批次和離散

• SimApi 規格定義了三種資料擷取模式，即。 SimApi 可以透過三種不同的方式提供數據 tags 在資料來源中（或在另一個方向：將資料寫入 tags 在資料來源中）。
• 連續資料檢索－這指的是隨著批次或流程的發展，連續、依序讀取數據，進行每次觀察。依照觀察之間的固定間隔讀取目前時間或特定範圍的資料。例如ample，09:00:00 至 10:00:00 之間的所有數據amp每 60 秒進行一次觀測，包括端點在內共 61 個觀測值。
• 大量資料檢索－指的是對整個批次的資料進行單次觀察（與特定的成熟度或時間點無關）。批次屬性和局部定心資料在SIMCA-online中作為批次資料讀取。批次條件通常也被讀取為批次資料（除非它們被配置為離散資料檢索）。
• 離散資料檢索－離散資料可以由許多到期日的多個觀察結果組成。但與連續資料不同，離散資料不是按順序讀取的，而是一次讀取一批特定階段的所有資料。資料不需要與成熟度變數的規則間隔開。每次請求資料時，都會按照配置的間隔重新讀取所有資料。
• 對於任何給定 tag 可以在三種模式中的任何一種中請求數據，但通常 SimApi 只支援單一 tag。同樣，也可以混合 tags 在一個節點內，但通常是所有 tags 在特定節點內支援相同模式的資料檢索。
• 對於連續數據（但不能用於批量或離散數據2），可以請求當前數據或歷史數據，這是下一節的主題。
• 並非所有 SimApis 都支援所有模式。請參閱上面的功能矩陣和 SimApi web 頁面了解詳細資訊。

透過 SimApi 取得當前和歷史連續數據

• 連續資料是指隨時間變化的過程資料。

當前數據

• 讀取當前資料意味著向資料來源詢問 tags 在詢問的時候。請注意，這裡沒有使用外部資料來源的時間。
• 讀取為目前資料的資料就是 SIMCA-online 將顯示為即時資料的資料。因此，在資料來源中不要出現不必要的延遲非常重要。為了在 SIMCA-online 中正常運行，當前數據應盡可能新。
• 資料來源可能會利用其對資料的了解以及值的有效期，並決定在某個時間點的原始資料太舊時傳回遺失的資料。例如ample：請求的資料是 15:00:00，但資料來源中最新的資料點是 03:00:00。在這種情況下，數據已經 12 小時了，因此 SimApi 可能決定傳回缺失值（無數據）。

史料

• 讀取歷史資料意味著向資料來源詢問一個或多個 tags 在特定的時間範圍內，以特定的觀察間隔進行。注意，這裡使用資料來源的本地時間來尋找資料。因此資料來源和伺服器之間的時間同步性非常重要。
• 歷史資料由資料矩陣組成。由 SimApi 實作從資料來源請求數據，然後amp以指定的間隔進行提取並建立要傳回的資料矩陣：
• 有時資料來源本身有聚合函數來傳回處理後的數據，或者ampling 函數，可用來傳回正確的資料。
• 對於其他資料來源，SimApi 必須請求時間範圍內的所有數據，然後amp使用正確的觀察來建立矩陣。
• 必須傳回某個時間範圍內的數據，即使在該時間範圍內可能沒有原始數據，但只能傳回開始時間之前的數據。例如ample：資料來源中存在時間點 10 和 20 的資料。amp將其設為時間 15 和 17，因為這些是當時最新的數據點。值 tags 在時間 10 時稱為請求範圍的邊界值。有關邊界值的更深入解釋，請參見amp請參閱 UA 第 11 部分：歷史存取的 returnBounds 文件 – 6.4.3 ReadRawModifiedDetails 結構
  （opcfoundation.org）
• 絕不應該使用插值來計算未來時間點的值，因為資料不會與即時讀取的當前資料相符。對於前任amp與上一個項目符號類似：如果使用項目 15 和 17 的值來插入項目 10 和 20 的數據，則它們實際上會使用未來的值，這是不允許的。
• 資料來源可能會利用其對資料的了解以及值的有效期，並決定在某個時間點的原始資料太舊時傳回遺失的資料。例如ample：請求 15:00:00 的數據，但資料來源中最新的資料點是 03:00:00 的。在這種情況下，數據已經 12 小時了，因此 SimApi 可能決定傳回缺失值（無數據）。

筆記： 在正常專案執行期間，SIMCA-online 通常不會在一次呼叫中請求超過一百個觀察結果。在 SIMCA-online 中進行提取時，或執行桌面 SIMCA 時，可以請求更大的資料。這些可能需要很長時間，這是可以預料的。

當前數據和歷史數據必須匹配

• 有時，當資料讀取為即時當前資料或歷史資料時可能會存在差異。這會導致 SIMCA-online 出現問題，因為伺服器會根據需要自動在當前資料和歷史資料之間切換。

低延遲數據採集

• 當SIMCA-online即時使用資料來源時，資料來源中的資料是最新的非常重要。資料來源中的資料擷取不應該出現不必要的延遲。每次觀察時，所有變數的連續過程資料必須同時可用。某些變數遲到的資料將不會被 SIMCA-online 取得。

可以隨時讀取數據 

• 當 SIMCA-online 請求一個值時 tag 對於時間 t，它將接收來自時間 t 的資料來源的值，或時間 t 之前資料來源中的最新觀測值，或時間 t 的內插。因此，伺服器每次請求時總是會獲得一個值，即使資料來源中可能不存在該精確時間點的觀察值。
• 時間ampSimApi 中的 s 總是 UTC。 SIMCA-online 用戶端和 SIMCA 將時間顯示為當地時間。

螺紋加工 

• 預設情況下，SimApi 由 SimApi 使用者透過單一執行緒呼叫。這適用於所有 SIMCA 版本和 SIMCA-online 直至版本 17。
• SIMCA-online 18 支援功能標誌，透過 SimApi 開啟多執行緒存取。在幫助主題「並發 SimApi 訪問」中閱讀更多內容。
• 這意味著，如果可能的話，SimApis 應該透過使 SimApi 實現線程安全性來為多線程做好準備，並記錄這一點以及 SimApi 用戶的任何注意事項。

紀錄 file

• SimApi 應該將操作、錯誤訊息和警告記錄到其日誌中 file 以幫助解決問題。使用不同的日誌等級來表示日誌的重要性。
• 建議對尚未在 SimApi 中實現的功能記錄「未實現」。

錯誤處理

• 當 SimApi 無法滿足資料來源的請求時，它可以透過以下兩種方式之一來處理此問題；透過傳回缺失值（無資料）或發出 SimApi 錯誤訊號：
• 向呼叫者傳回缺失值並發出成功訊號允許呼叫者繼續正常進行（但當然沒有任何資料）。對於部分錯誤，例如可以獲得部分數據，但無法獲得全部數據，則建議採用此做法。 tags 在請求中。
• 發出 SimApi 錯誤訊號允許呼叫者（例如amp請造訪 SIMCA 線上伺服器）立即查看此資訊並採取行動。對於完全失敗且根本無法傳回任何資料的請求，建議採用這種做法。
• SIMCA-online 以不同的方式處理缺失值或錯誤代碼，如 SIMCA-online 技術指南中所述。

SimApi 性能要求

• SimApi中的函數用於獲取數據。
• 如果資料存取速度很慢，SimApi 將無法正常運作，這amp如圖所示：如果SIMCA-online每秒請求一次數據，但需要兩秒鐘才能獲取，那麼SIMCA-online伺服器將永遠無法即時跟上，而且會逐漸落後。
• 在小節中我們將展示 SIMCA 和 SIMCA-online 如何使用資料存取 SimApi 函數以及呼叫 SimApi 函數的頻率。這有助於設定 SimApi 實施的效能要求。

SIMCA 對 SimApi 函數的使用

• 當桌面SIMCA或其他離線產品使用SimApi取得資料時，這些請求將針對一定時間範圍內的一組變數的批次和流程資料。
• 由於這些請求是由使用者手動發起的，因此它們不會頻繁發生，也不會對資料來源造成很大的負載。
• 這些 SimApi 函數用於獲取數據：
• simapi2_node取得活動批次
• simapi2_node取得批次時間
• simapi2_connection讀取歷史數據

SIMCA-online 對 SimApi 函數的使用

• SIMCA-online 用於即時監控流程，因此它會定期透過 SimApi 請求資料。可使用的最短執行間隔為 1 秒。一些現實世界中的前任amp執行間隔較小為10秒、1分鐘或10分鐘。
• 一個伺服器可以同時運行多個項目。
• 為了減少通過 SimApi 的 API 呼叫次數，伺服器透過將許多並發的較小請求分組為同時針對所有變數的單一較大請求來優化資料請求（在幫助主題「優化從資料來源讀取以提高效能」中了解更多資訊）。
• 當伺服器使用下面列出的 SimApi 函數請求資料時，其執行演算法的工作方式如下：
• 所有以相同間隔執行的階段都被分組為單一 SimApi 調用，以減少調用次數。伺服器讀取所有共享間隔的模型所使用的所有變數的最新數據，即，此呼叫將產生一個寬數據行，然後由所有項目使用該數據行。
  • simapi2_connection讀取目前數據
• 對於每個批次項目，伺服器還需要知道哪些批次是活動的。每次執行項目時也需要這樣做：
  • simapi2_node取得活動批次
  • simapi2_nodeGetBatchTimes 的呼叫頻率較低。
• 此外，SIMCA-online還需要歷史數據。這些請求僅在需要時發生，例如趕上在 SIMCA-online 啟動之前啟動的一批資料的開始，或當伺服器落後並需要讀取資料區塊時：
  • simapi2_connection讀取歷史數據
• 或者，一些項目配置使用批次資料或離散資料的功能，從而導致 SimApi 呼叫：
  • simapi2_connection讀取批次數據
  • simapi2_connectionReadDiscreteEx
• 可選地，一些專案配置使用寫回將資料推回資料來源：
  • simapi2_connectionWriteHistoricalDataEx（以及批次資料、離散資料的對應函數）
• 重要的是，每次呼叫用於獲取資料的核心函數 readCurrentData、getActiveBatches/getBatchTimes 都要很快，而且考慮到 SIMCA-online 呼叫這些函數的頻率，這對於資料來源本身來說在計算上並不困難。

測試和驗證 SimApi 數據

• 本節是關於測試 SimApi 以驗證從其傳回的資料是否與資料來源本身中的資料相符。在創建或更改 SimApi 實作之後，或當資料來源的 API 發生變化時，執行這樣的測試非常重要。
• 實際上，數據驗證是使用 SIMCA-online 及其提取功能透過 SimApi 從數據來源提取數據，然後與數據來源中的原始數據進行比較。桌上型 SIMCA 不能用於測試 SimApi 的即時面。

準備和要求

• 有些項目是可選的，但如果您的測試範圍包括以下內容，則可以執行：

1. 請依照產品 zip 中的 ReadMe 和 Installation Guide.pdf 中的說明安裝 SIMCA-online。
2. 取得SIMCA-online伺服器的許可證並安裝它。如果沒有許可證，SimApi 將無法運作。 SIMCA-online 的知識庫文章展示如何授權產品。例如amp來自：SIMCA-online 18 (sartorius.com)
3. 安裝並配置您想要測試的 SimApi。請參閱本文檔第 4 至 5 章以及特定 SimApi 的使用者指南。
   • a. 可選：確保使用者指南是最新的且正確的。
4. 確保您有一個可用於比較 SimApi 資料和資料來源的工具。
5. 在SIMCA-online桌面用戶端中，登入您的SIMCA-online伺服器並使用 File > 透過 SimApi Extract 取得數據。
6. 如果您的測試範圍包括它，則可選：完成測試後，卸載 SimApi 並驗證其 files 被刪除。

測試什麼

• 第 3 章中的功能矩陣列出了所有可能的功能，但給定的 SimApi 實作可能僅支援其中的一個子集。您應該測試由給定的 SimApi 實現的所有功能。
• 以下測試對於大多數 SimApi 實作來說是通用的：
• 使用使用者名稱和密碼進行身份驗證
• 測試 SimApi 配置中的各種設置
• 節點層次：節點和 tags SimApi 公開的是正確的。
  • 必須有一個 tag 公開所有可透過 SimApi 取得的「變數」。前任amples：過程測量、計算值、常數。
• 連線彈性：如果資料來源不可用，則會導致日誌中出現警告或錯誤 file但當資料來源可用時會自動重新建立與資料來源的連線。
• 多重實例：可以同時配置和使用兩個實例，並且具有單獨的日誌 files.
• 當前數據：提取當前數據 tags。確保資料是來自資料來源的最後已知值，或因品質不佳或資料太舊而遺失。
  • 每 10 秒（左右）提取一次數據，持續一分鐘。
• 歷史連續數據：提取歷史數據 tags.
  • 使用與您提取目前資料時相符的時間範圍。驗證目前資料是否與歷史資料以及資料來源中的原始資料相符。
  • 嘗試不同的時間範圍和amp間隔，驗證資料是否與資料來源相符。
  • 嘗試每 1 秒提取一次數據，這是最短的可能時間amp嶺間隔。
  • 嘗試各種類型的 tags 在資料來源（過程變數等）中，確保資料匹配。
  • 注意：SIMCA-online 可能會將單一大型歷史資料請求分成幾個較小的區塊。這將在 SimApi 日誌中可見。
• 驗證 SimApi 是否適用於文字資料、數字資料和缺失資料。
• SimApi 日誌 file。驗證日誌是否包含合理的條目。
• 批次節點：右鍵點選節點並執行「尋找批次」。
  • 驗證批次名稱、批次開始時間、結束時間。
  • 嘗試在資料來源中執行的活動批次。它不應該透過 SimApi 有一個結束時間。
• 流程節點批次標識符 tag。如果 SimApi 具有批次節點功能（請參閱上一個項目符號），它還必須具有批次識別符 tag 在符合的流程資料節點中。此數據 tag 應為批次識別碼（批次名稱）。大量項目需要這些資料來辨識某一行資料屬於哪個批次。

根據 SimApi 是否支持，您可能還需要測試：

• 使用大量數據 File > 提取。
• 離散資料使用 File > 提取。注意：要測試離散數據 File > 提取節點，批次節點和離散資料節點必須在同一個SimApi（SIMCA-online執行專案時，可以來自不同的SimApis）。
• 寫回－將資料批次推送到資料來源。為了測試這一點，您必須在 SIMCA-online 中配置專案配置，以將資料向量寫回資料來源。然後在SIMCA-online中執行該專案並檢查在資料來源中寫回的資料。
• 連續資料在專案配置中的 Evolution Write Back 頁面上配置。
• 離散資料配置在同一頁面上，但僅適用於配置離散資料檢索的階段。
• 大量寫回的批次數據

更多資訊

• Sartorius Stedim Data Analytics AB Östra Strandgatan 24 903 33 於默奧 瑞典
• 電話：+ 46 90-18 48 00
• www.sartorius.com
• 這些說明中包含的信息和數字對應於下面指定的版本日期。
• 賽多利斯保留更改設備的技術、功能、規格和設計的權利，恕不另行通知。使用男性或女性形式是為了便於這些說明中的易讀性，並且始終同時表示所有性別。
  版權聲明：
• 這些說明（包括所有元件）均受版權保護。
• 未經我們批准，不得超出版權法的任何使用範圍。
• 這尤其適用於重印、翻譯和編輯，無論使用何種媒體類型。

常問問題

• Q：SimApis 的用途是什麼？
  • 答：SimApis的主要目的是向Umetrics Suite產品提供數據，用於專案建立和模型建構。
• Q：如何解決 SimApi 安裝問題？
  • 答：您可以透過 SIMCA-online 測試、檢查 SimApi 日誌來排除故障 file，並確保服務帳戶配置正確。