G Oracle Analytics Desktop SDK 參考資料

本主題描述可供用於開發視覺化 Plug-in 並將其部署至您安裝之 Oracle Analytics Desktop 的軟體開發套件 (SDK)。

主題：

Oracle Analytics Desktop SDK

SDK 提供一個開發環境，供您建立及開發自訂視覺化 Plug-in，然後將它們部署至您安裝的 Oracle Analytics Desktop。

主題：

命令檔

您的安裝包括命令檔，供您用來建立開發環境及建立架構視覺化 Plug-in。

命令檔在以下目錄中：<your_installation_directory>\Oracle Analytics Desktop\tools\bin。

例如，C:\Program Files\Oracle Analytics Desktop\tools\bin

請注意以下的命令檔名稱與描述：

  • bicreateenv - 執行此命令檔即可建立供開發 Plug-in 的開發環境。

  • bicreateplugin - 執行此命令檔即可建立架構視覺化，以快速開始進行自訂 Plug-in 的開發。

  • bideleteplugin - 執行此命令檔即可刪除開發環境中的 Plug-in。

  • bivalidate - 使用 gradlew validate 命令呼叫並執行 bivalidate 命令檔。bivalidate 命令檔會驗證 JSON 組態檔的格式是否正確，以及當中是否包含適當的視覺化組態。

其他資源

您可以使用命令檔以外的資源開發自訂的視覺化 Plug-in。

請記下以下的可用資源：

  • circlePack 範例 - 您的開發環境中包含了一個 circlePack 範例。您可以立即部署並使用此範例。不過，本範例僅供搭配提供的教學課程使用，目的為讓您瞭解如何開發視覺化 Plug-in。您也可以複製此範例，作為建立視覺化 Plug-in 的樣板。

    circlePack 範例位於 <your_development_directory>\src\sampleviz\sample-circlepack

    例如，C:\OracleDVDev\src\sampleviz\sample-circlepack

  • 其他視覺化 Plug-in 範例 - 您可以從 Oracle Analytics Library 下載 Plug-in 範例。

  • JS API 文件 - 本文件包含開發視覺化 Plug-in 所需的 JavaScript 參考資訊。請參閱Oracle Analytics Desktop SDK JavaScript 參照。

建立視覺化 Plug-in 開發環境

您必須先設定 PATH 環境變數並建立開發環境之後，才能夠建立視覺化 Plug-in。

  1. 使用命令提示建立一個空白的開發目錄。例如，C:\OracleAnalyticsDev。
  2. 設定 PATH 環境變數。例如： 
    set ANALYTICSDESKTOP_SDK_HOME="C:\Program Files\Oracle Analytics Desktop"
set PLUGIN_DEV_DIR=C:\OracleAnalyticsDev
REM add tools\bin to path: 
set PATH=%ANALYTICSDESKTOP_SDK_HOME%\tools\bin;%PATH%
  3. 執行安裝中所含的 bicreateenv 命令檔，在這個空白的目錄中建立開發環境。例如： 
    cd C:\OracleAnalyticsDev
bicreateenv
    如需有關執行此命令檔時可用之選項的相關資訊，請參閱命令檔的命令行說明。例如：
    C:\OracleAnalyticsDev>bicreateenv -help
    系統就會在您指定的目錄中建立完整的開發環境，包括 build.gradle 和 gradlew。
  4. 選擇性的： 若您是透過 Web 代理主機作業，則需要將 gradle.properties 設為指向您的代理主機。gradle.properties 位於您的開發環境中，例如 C:\OracleAnalyticsDev\gradle.properties。
    請依據下列範例設定您的 gradle.properties：
    systemProp.https.proxyHost=www-proxy.somecompany.com
systemProp.https.proxyPort=80
systemProp.https.nonProxyHosts=*.somecompany.com|*.companyaltname.com

建立架構視覺化 Plug-in

在開發環境中建立架構視覺化 Plug-in 之後，要接著繼續進行開發使其成為健全的視覺化 Plug-in，然後將它部署到您的 Oracle Analytics Desktop 環境中。

  1. 執行安裝中所含的 bicreateplugin 命令檔來建立架構視覺化。請使用下列語法：
    bicreateplugin viz -<subType> -<id> -<name>
    • <subType> 指的是您要建立的視覺化類型。您可以選擇：

      • basic - 此選項可建立未使用 Oracle Analytics Desktop 的資料或任何資料模型對應的視覺化項目。這就像是隨附 Oracle Analytics Desktop 提供的「圖像」和「文字」視覺化類型。例如，您可以使用此視覺化類型來顯示以程式編寫至 Plug-in 內或組態中的圖像或文字。您可以使用此類型的視覺化來改善格式。

      • dataviz - 此類型會將在 Oracle Analytics Desktop 註冊之資料來源的資料，在畫面上以圖表、表格或其他表示方式呈現。它同時負責標示相同工作區上其他視覺化的事件，以及發布影響相同工作區上其他視覺化的互動事件。

      • embeddableDataviz - 此類型會將在 Oracle Analytics Desktop 註冊之資料來源的資料以格子圖視覺化的儲存格方式呈現。它同時負責標示相同工作區上其他視覺化的事件，以及發布影響相同工作區上其他視覺化的互動事件。

    • <id> 指的是您的網域和要在開發環境中為視覺化目錄和元件設定的名稱。例如 com-company.basicviz。
    • <name> 指的是您在工作簿中測試、部署及使用的視覺化 Plug-in 名稱。
    例如，若要建立基本視覺化、將開發目錄命名為 com-company-basicviz，以及將視覺化 Plug-in 命名為 helloViz，請輸入並執行下列命令：

    C:\OracleDevDir>bicreateplugin viz –subType basic –id com.company.basicviz —name helloViz

  2. 選擇性的： 開啟命令檔的命令行說明，以瞭解執行此命令檔時可用選項的相關資訊。例如： C:\OracleDVDev> bicreateplugin -help
第一次執行 bicreateplugin -viz 命令時，系統會在以下位置建立 customviz 目錄：<your_development_environment>\src\customviz

您建立的所有自訂視覺化開發目錄都會加到此目錄中。

例如，C:\OracleDVDev\src\customviz\com-company-basicviz

建立架構外觀或未分類的 Plug-in

bicreateplugin -unclassified 命令會以 plugin.xml、區域化組合建立一個空白的 Plug-in。bicreateplugin -skin 命令則會建立架構外觀 Plug-in。

  1. 執行安裝中所含的 createplugin 命令檔來建立架構 Plug-in。使用下列其中一種語法：
    bicreateplugin -skin -<id>
    bicreateplugin -unclassified -<id>
    • <id> 指的是您的網域和要指定的視覺化名稱。例如，com-company.newskin
    例如，若要建立外觀 Plug-in，請輸入並執行下列命令：

    C:\OracleDevDir>bicreateplugin skin –id com.company.newskin

開發視覺化 Plug-in

建立架構視覺化 Plug-in 之後，您可以使用 Oracle 提供的資源協助您開發 Plug-in。

dataviz 和 embeddableDataviz 類型的目錄包含 datamodelhandler.js 檔案，其中包含實體與邏輯的資料對應格式。此檔案同時會決定 Oracle Analytics Desktop 如何呈現並將使用者互動傳送至伺服器。

參考 .JS API 文件瞭解如何新增相依性。請參閱 Oracle Analytics Desktop SDK JavaScript 參照。

以 SDK 模式執行並測試 Plug-in

您在開發視覺化 Plug-in 或想要測試視覺化 Plug-in 時，可以在瀏覽器中以 SDK 模式執行 Oracle Analytics Desktop。

  1. 執行 gradlew run 命令。例如，C:\OracleDevDir>gradlew run

    執行此命令之後，請注意以下結果：

    • Oracle Analytics Desktop 會在您的預設瀏覽器中以 SDK 模式開啟。使用瀏覽器的 JavaScript 除錯程式來測試並除錯應用程式。

    • 您建立的視覺化項目會在 Oracle Analytics Desktop 的「視覺化項目」窗格中。

    • 作業系統的工具列中會顯示一個系統匣，其中有三個連結：啟動瀏覽器 - 可供您啟動或重新啟動您的預設瀏覽器以顯示 Oracle Analytics Desktop；將 URL 複製到剪貼簿 - 可供您複製 URL 並將它貼到其他瀏覽器中；關閉 - 可供您關閉開發瀏覽器。

  2. 將您的視覺化拖放至工作簿的工作區並新增資料元素，以進行測試。
  3. 如有需要，可繼續開發視覺化 Plug-in。在瀏覽器中以 SDK 模式進行工作時，您可以更新 .JS 定義，然後重新整理瀏覽器以查看變更。

驗證視覺化 Plug-in

測試您的視覺化 Plug-in 之後，您必須先進行驗證，才能夠封裝並部署視覺化 Plug-in。

  1. 執行 gradlew validate 命令。例如： 
    cd C:\OracleDVDev
.\gradlew validate
    此步驟會驗證 JSON 組態檔的格式是否正確，以及當中是否包含適當的視覺化組態。如果驗證發現任何錯誤，系統便會顯示錯誤訊息。
  2. 若要檢查 JavaScript 來源檔案中是否有錯誤，請使用您瀏覽器的開發工具。

組建、封裝及部署視覺化 Plug-in

驗證視覺化 Plug-in 之後，您必須組建並封裝 Plug-in，然後將產生的分送項目複製到您的安裝目錄中。

組建並封裝處理作業會針對您開發目錄中的所有視覺化項目執行，而且每個 Plug-in 都會包含在自己的壓縮檔中。不過，某些特定的視覺化項目是無法組建並封裝的。如果不想要組建並封裝某些視覺化項目，您必須先將這些要排除的視覺化項目移出開發目錄或將它們自目錄中刪除，再執行組建。請參閱刪除開發環境中的 Plug-in。
  1. 執行 gradlew build 命令。例如： 
    cd C:\OracleDVDev
.\gradlew clean build
    系統會新增一個組建目錄至您的開發環境。例如 C:\OracleDVDev\build\distributions。此目錄包含每個視覺化項目的壓縮檔。壓縮檔的名稱是您在建立視覺化架構時所指定的視覺化名稱。例如 basicviz.zip。
  2. 將壓縮檔複製到您的安裝目錄中。例如，%localappdata%\OracleAnalyticsDesktop\plugins。

刪除開發環境中的 Plug-in

您可以使用 bideleteplugin 命令檔，刪除開發環境中不需要的 Plug-in。

組建並封裝處理作業會包括開發目錄中的所有視覺化項目。不過，某些特定的視覺化項目是無法組建並封裝的。若不要組建不想要的視覺化項目，您可以在執行組建並封裝處理作業之前先將它們刪除。
  1. 若要刪除視覺化 Plug-in，請使用下列語法執行 bideleteplugin 命令： 
    cd C:\<your_development_directory>
bideleteplugin viz -id <name_of_your_domain>.<name_of_viz_plugin>
  2. 若要刪除未分類的 Plug-in，請使用下列語法執行 bideleteplugin 命令： 
    cd C:\<your_development_directory>
bideleteplugin unclassified -id <name_of_your_domain>.<name_of_unclassified_plugin>
  3. 若要刪除外觀 Plug-in，請使用下列語法執行 bideleteplugin 命令： 
    cd C:\<your_development_directory>
bideleteplugin skin -id <name_of_your_domain>.<name_of_skin_plugin>