12 建立自訂資料動作 Plug-in
您可以建立要在 Oracle Analytics 中使用的自訂資料動作 Plug-in。
資料動作 Plug-in 可擴充 Oracle Analytics，並讓使用者能夠選取視覺化中的資料點及呼叫特定的動作。Oracle Analytics 提供一組核心的資料動作，該動作涵蓋許多常見使用案例，但您可以透過寫入自己的資料動作 Plug-in ，更進一步擴充此功能。
您必須對以下內容具有基本瞭解，才能建立自訂資料動作 Plug-in：
- JavaScript
- RequireJS
- JQuery
- KnockoutJS
關於資料動作 Plug-in 與資料動作架構
資料動作 Plug-in 利用資料動作架構來提供已緊密整合至 Oracle Analytics 使用者介面的自訂資料導向動作。
當使用者呼叫資料動作時，資料動作管理員會將要求相關資訊環境 (例如，限定資料參照、計量值、篩選和中繼資料) 傳遞給負責處理要求的資料動作 Plug-in。Oracle 提供四種類型的資料動作 Plug-in：CanvasDataAction、URLNavigationDataAction、HTTPAPIDataAction 和 EventDataAction。您可以延伸這些資料動作 Plug-in 類型及其抽象基礎類別，以提供自己的資料動作。
資料動作類別
資料動作類別包括「瀏覽至 URL」、「HTTP API」、「瀏覽至工作區」和「事件」動作：
- 瀏覽至 URL：以新的瀏覽器頁籤開啟指定的 URL。
- HTTP API：使用
GET/POST/PUT/DELETE/TRACE命令以 HTTP API 為目標，且不會產生新頁籤。相反地，會檢查 HTTP 狀態代碼，並顯示暫時成功或失敗訊息。 - 瀏覽至工作區：可讓使用者從來源工作區瀏覽至位於相同或不同視覺化中的目標工作區。來源工作區中的任何有效篩選會傳送至目標工作區作為外部篩選。當目標工作區開啟時，它會嘗試將外部篩選套用至視覺化。此處不描述套用外部篩選的機制。
- 事件動作：使用 Oracle Analytics 事件路由器來發布事件。任何 Javascript 程式碼 (例如第三方 Plug-in) 都可以訂閱這些事件，然後據此處理其自訂回應。這能提供最大的彈性，因為 Plug-in 開發人員可以選擇資料動作回應的方式。例如，他們可以選擇顯示使用者介面，或一次傳送資料至多個服務。
瀏覽至 URL 和 HTTP API 資料動作類別類型都會使用記號語法，將視覺化的資料或中繼資料引入 URL 和 POST 參數中。
URL 記號取代
HTTP 資料動作可以使用傳送至資料動作的相關資訊環境值取代 URL 中的記號。例如，限定資料參照值、篩選值、使用者名稱、工作簿路徑以及工作區名稱。
| 記號 | 附註 | 取代為 | 範例 | 結果 |
|---|---|---|---|---|
${valuesForColumn:COLUMN} |
NA | 限定資料參照的資料欄顯示值 | ${valuesForColumn: "Sales"."Products"."Brand"} |
BizTech,FunPod |
${valuesForColumn:COLUMN, separator:"/"} |
任何可能取代為多個值的記號皆支援選擇性區隔符號選項。separator 預設為逗號 (,)，但您可以將其設為任何字串。您可以使用反斜線 (\) 在此字串內遁離雙引號。 |
限定資料參照的資料欄顯示值 | ${valuesForColumn: "Sales"."Products"."Brand"} |
BizTech,FunPod |
${valuesForColumn:COLUMN, separationStyle:individual} |
任何 separationStyle 皆預設為 delimited，但如果使用者需要對每個值產生個別 URL 參數，您可以將它設為 individual。 |
限定資料參照的資料欄顯示值 | &myParam=${valuesForColumn: "Sales"."Products"."Brand"} |
&myParam=BizTech&myParam=FunPod |
${keyValuesForColumn:COLUMN} |
NA | 限定資料參照的資料欄索引鍵值。 | ${keyValuesForColumn:COLUMN} |
10001,10002 |
${env:ENV_VAR} |
支援的環境變數包括：sProjectPath、sProjectName、sCanvasName、sUserID 和 sUserName。 |
環境變數。 | ${env:'sUserID'} |
myUserName |
資料動作相關資訊環境
您可以定義當使用者呼叫資料動作時傳送的相關資訊環境。
您可以定義當您建立資料動作時要傳送多少相關資訊環境至資料動作。
限定資料參照
呼叫資料動作時，系統會使用 LogicalFilterTree 物件陣列為每個標示的資料點產生限定資料參照。LogicalFilterTree 包含多個在樹狀結構中排列的 LogicalFilterNode 物件。此物件包括：
- 資料版面配置的資料列或資料欄邊緣上的屬性。
- 處理每個標示的儲存格其計量邊緣上的特定計量。
- 每個標示的儲存格其特定計量值。
- 索引鍵值與顯示值。
環境變數
除了描述每個標示資料點的資料和中繼資料之外，某些資料動作可能還需要描述呼叫資料動作的環境其進一步的相關資訊環境。此類環境變數包括：
- 專案路徑
- 專案名稱
- 工作區名稱
- 使用者 ID
- 使用者名稱
資料動作程式碼設計
您可以使用 API 類別建立資料動作。
- 資料動作有四個繼承自
AbstractDataAction的具體類別：CanvasDataActionURLNavigationDataActionHTTPAPIDataActionEventDataAction
- 您可以使用資料動作 Plug-in API 建立新類型的資料動作。請參閱 Data Visualizer SDK 參考資料。
- 資料動作類型的登錄是由
DataActionPluginHandler所管理。 - 程式碼透過發布事件來建立、讀取、編輯、刪除或呼叫資料動作執行處理。
- 事件由
DataActionManager進行處理。
資料動作模型類別
資料動作模型類別有數種不同的類型。
AbstractDataAction
此類別負責下列作業：
- 儲存「剔除模型」(子類別可以使用自己的特性自由延伸此模型)。
- 定義子類別必須實行的抽象方法：
+ invoke(oActionContext: ActionContext, oDataActionContext:DataActionContext) <<abstract>>透過傳送的相關資訊環境呼叫資料動作 - 應該僅限由
DataActionManager呼叫。+ getGadgetInfos(oReport): AbstractGadgetInfo[] <<abstract>>建構並傳回負責呈現使用者介面欄位以編輯此類型之資料動作的
GadgetInfos。+ validate() : DataActionError驗證資料動作，如果有效則傳回空值，如果無效則傳回
DataActionError。
- 提供下列方法的預設實行，用來呈現資料動作使用者介面欄位的一般部分：
+ getSettings():JSON將資料動作的「剔除模型」序列化至已準備好包含在報表中的 JSON (使用 komapping.toJS(_koModel))。
+ createNameGadgetInfo(oReport) : AbstractGadgetInfo建構並傳回可呈現資料動作的名稱欄位的
GadgetInfo。+ createAnchorToGadgetInfo(oReport) : AbstractGadgetInfo建構並傳回可呈現資料動作的定錨至欄位的
GadgetInfo。+ createPassValuesGadgetInfo(oReport) : AbstractGadgetInfo建構並傳回可呈現資料動作的傳送值欄位的
GadgetInfo。
子類別可能不需要基礎類別提供的所有 GadgetInfo，因此它們可能不需要呼叫所有這些方法。透過此方式將每個欄位的呈現方式分離出來，子類別可以自由挑選其所需的小工具。某些子類別甚至可以選擇提供這些一般資料動作小工具的其他實行。
CanvasDataAction、URLNavigationDataAction、HTTPAPIDataAction、EventDataAction
這些是基本類型的資料動作其具體類別。這些類別可自行運作以提供給這些類型的資料動作一般使用者介面。它們也可以作為便利的基礎類別，讓自訂資料動作 Plug-in 延伸。
- CanvasDataAction：用於瀏覽至工作區。
- URLNavigationDataAction：用於以新的瀏覽器視窗開啟新的網頁。
- HTTPAPIDataAction：用於對 HTTP API 提出
GET/POST/PUT/DELETE/TRACE要求，並以程式設計的方式處理HTTP Response。 - EventDataAction：用於透過事件路由器發布 JavaScript 事件。
每個類別負責的作業如下：
- 從基礎類別實行抽象方法。
invoke(oActionContext: ActionContext, oDataActionContext:DataActionContext)此方法應藉由將在 KOModel 中定義的特性與指定的
DataActionContext物件結合來呼叫資料動作。getGadgetInfos(oReport): AbstractGadgetInfo[]此方法應：
- 建立包含
AbstractGadgetInfos的陣列。 - 呼叫將每個
AbstractGadgetInfo推送至陣列的個別createXXXGadgetInfo()方法。 - 傳回陣列。
- 建立包含
- 提供其他方法，供用於建立專屬於特定子類別之資料動作的個別小工具。
這些具體類別的子類別可能不需要使用其自訂使用者介面之超級類別所提供的所有小工具。透過此方式將每個小工具的建構分離出來，子類別可以自由挑選其所需的小工具。
DataActionKOModel、ValuePassingMode
DataActionKOModel 類別提供不同子類別之 AbstractDataAction 所共用的基礎 KOModel。請參閱 DataActionKOModel 類別。
資料動作服務類別
資料動作有數種不同的服務類別。
DataActionManager
所有與 DataActionManager 的通訊都使用實行事件處理程式的 ClientEvents.DataActionManager，以進行下列作業：
- 管理目前工作簿中定義的資料動作集。
- 呼叫資料動作。
- 擷取目前工作簿中定義的所有資料動作。
- 擷取適用於目前已標記資料點的所有資料動作。
DataActionContext、EnvironmentContext
呼叫資料動作時，DataActionContext 類別會包含已傳送至目標的相關資訊環境。
getColumnValueMap()傳回以屬性資料欄名稱作為索引鍵的屬性資料欄值對應。這些項目定義呼叫資料動作的資料點其限定資料參照。
getLogicalFilterTrees()傳回
LogicalFilterTrees物件，此物件描述呼叫資料動作的特定資料點其限定資料參照 (請參閱InteractionService以瞭解詳細資訊)。getEnvironmentContext()EnvironmentContext類別的執行處理，描述來源環境，例如：getProjectPath()getCanvasName()getUserID()getUserName()
getReport()傳回呼叫資料動作的報表。
DataActionHandler
DataActionHandler 類別會註冊各種資料動作 Plug-in。其 API 與其他 Plug-in 處理程式 (例如，VisualizationHandler) 大致一致。
DataActionHandler 類別提供下列公用方法：
getClassName(sPluginType:String) : String傳回指定資料動作類型的完整類別名稱。
getDisplayName(sPluginType:String) : String傳回指定資料動作類型的翻譯顯示名稱。
getOrder(sPluginType:String) : Number傳回用於將資料動作類型清單依偏好順序排序的數字。
DataActionHandler 類別提供下列靜態方法：
getDependencies(oPluginRegistry:Object) : Object.<String, Array>傳回涵蓋所有已註冊資料動作類型的相依性對應。
getHandler(oPluginRegistry:Object, sExtensionPointName:String, oConfig:Object) : DataActionPluginHandler建構並傳回
DataActionHandler類別的新執行處理。
DataActionUpgradeHandler
當報表開啟時，UpgradeService 會呼叫 DataActionUpgradeHandler 類別。
DataActionHandler 類別提供兩個主要方法：
deferredNeedsUpgrade(sCurrentVersion, sUpgradeTopic, oDataActionJS, oActionContext) : Promise傳回解析為布林值的
Promise，指出指定的資料動作是否必須升級 (true) 或 (false)。此方法是藉由比較資料動作執行處理與從資料動作的建構子，來決定是否必須升級資料動作。performUpgrade(sCurrentVersion, sUpgradeTopic, oDataActionJS, oActionContext, oUpgradeContext) : Promise在指定的資料動作上執行升級，並解析
Promise。升級本身是透過呼叫資料動作的upgrade()方法執行 (只有正在升級的資料動作其特定的子類別本身可以升級)。getOrder(sPluginType:String) : Number傳回用於將資料動作類型清單依偏好順序排序的數字。
資料動作程式碼互動
資料動作在建立使用者介面欄位時，以及在使用者呼叫資料動作時，會與 Oracle Analytics 程式碼互動。
建立新資料動作執行處理的欄位
此互動會在 Oracle Analytics 想要呈現資料動作使用者介面欄位時啟動。方法為：
- 建立
PanelGadgetInfo，作為資料動作傳回的GadgetInfos其父項GadgetInfo。 - 在資料動作上呼叫
getGadgetInfos()。 - 新增資料動作的
GadgetInfos，作為第一個步驟中所建立的PanelGadgetInfo其子項。 - 建立呈現
PanelGadgetInfo的PanelGadgetView。 - 設定
PanelGadgetView，此為HTMLElement的容器。 - 將
PanelGadgetView註冊為已經連附至HostedComponent樹狀結構的HostedComponent其子項HostedComponent。這會在「面板」小工具內，依照
getGadgetInfos()所傳回陣列中的顯示順序，呈現資料動作的小工具。
呼叫資料動作
此互動會在使用者透過 Oracle Analytics 使用者介面 (例如，從視覺化中資料點上的彈出式功能表) 呼叫資料動作時啟動。
程式碼會執行下列作業以回應使用者互動：
- 發布
INVOKE_DATA_ACTION事件，其中包含資料動作的 ID、呼叫資料動作的DataVisualization，以及TransientVizContext物件。 DataActionManager透過下列方法處理此事件：- 從該 ID 取得資料動作執行處理。
- 在指定的
DataVisualization中取得已標記資料點的LogicalFilterTrees。 - 建構
DataActionContext，其中包含所有要傳送至資料動作其目標的資訊。 - 在資料動作上呼叫
invoke(oDataActionContext)。
資料動作 plugin.xml 檔案範例
本主題顯示 CanvasDataAction 資料動作的 plugin.xml 檔案範例。
plugin.xml 範例
<?xml version="1.0" encoding="UTF-8"?>
<tns:obiplugin xmlns:tns="http://plugin.frameworks.tech.bi.oracle"
xmlns:viz="http://plugin.frameworks.tech.bi.oracle/extension-points/visualization"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
id="obitech-currencyconversion"
name="Oracle BI Currency Conversion"
version="0.1.0.@qualifier@"
optimizable="true"
optimized="false">
<tns:resources>
<tns:resource id="currencyconversion" path="scripts/currencyconversion.js" type="script" optimizedGroup="base"/>
<tns:resource-folder id="nls" path="resources/nls" optimizable="true">
<tns:extensions>
<tns:extension name="js" resource-type="script"/>
</tns:extensions>
</tns:resource-folder>
</tns:resources>
<tns:extensions>
<tns:extension id="oracle.bi.tech.currencyconversiondataaction" point-id="oracle.bi.tech.plugin.dataaction" version="1.0.0">
<tns:configuration>
{
"resourceBundle": "obitech-currencyconversion/nls/messages",
"properties":
{
"className": "obitech-currencyconversion/currencyconversion.CurrencyConversionDataAction",
"displayName": { "key" : "CURRENCY_CONVERSION", "default" : "Currency Conversion" },
"order": 100
}
}
</tns:configuration>
</tns:extension>
</tns:extensions>
</tns:obiplugin>選擇要延伸的最佳資料動作類別
開始寫入自訂資料動作 Plug-in 之前，請決定要延伸的現有資料動作類別。選擇可提供與您想要的資料動作執行功能最相符的資料動作類別。
每個資料動作都繼承自類別圖表所示的 AbstractDataAction 類別。類別圖表顯示兩個抽象資料動作類別 (AbstractDataAction 和 AbstractHTTPDataAction) 以及您可以延伸的四個具體動作類別 (CanvasDataAction、URLNavigationDataAction、HTTPAPIDataAction 和 EventDataAction)。您提供的每個資料動作必須延伸其中一個類別。您要延伸的類別取決於當您呼叫資料動作時想要實行的行為。大多數的第三方資料動作可能會延伸 URLNavigationDataAction、HTTPAPIDataAction 或 EventDataAction。
無論您延伸哪一個類別，呼叫您的資料動作時，將會提供您描述呼叫資料動作的完整資料點相關資訊環境的中繼資料。請參閱資料動作相關資訊環境。
AbstractDataAction 類別
AbstractDataAction 是抽象基礎類別，所有類型的資料動作皆繼承自此類別。它負責提供子類別可以使用的通用功能和預設行為。
AbstractDataAction
所有類型的資料動作皆為 AbstractDataAction 基礎類別的子類別。它提供一組所有資料動作皆通用的核心功能。除非是要建立在呼叫時會執行多個類型動作的複雜資料動作，或者您必須執行具體類別不支援的一些動作，否則您不應直接延伸此類別。如果您需要建立複雜資料動作，請考慮延伸最能提供您所需功能的具體類別。
AbstractDataAction 語法
+ AbstractDataAction(oKOModel)
+ getKOViewModel():DataActionKOModel
+ createFromJS(fDataActionConstructor, sClassName, oDataActionKOModelUS) : AbstractDataAction
+ invoke(oActionContext, oDataActionContext) + getGadgetInfos(oReport) : AbstractGadgetInfo[] + validate() : DataActionError
+ getSettings() : Object + requiresActionContextToInvoke() : Boolean + isAllowedHere() : Boolean
# createNameGadgetInfo(oReport) : AbstractGadgetInfo # createAnchorToGadgetInfo(oReport) : AbstractGadgetInfo # createPassValuesGadgetInfo(oReport) : AbstractGadgetInfo
DataActionKOModel 類別
AbstractDataAction 的每個子類別都有可能建立 DataActionKOModel 自己的子類別。DataActionKOModel 基礎類別提供下列特性：
DataActionKOModel、ValuePassingMode
sID:String指定給資料動作執行處理的唯一 ID。
sClass:String此特定類型的資料動作其類別名稱。
sName:String指定給資料動作執行處理的顯示名稱。
sVersionsScopeIDeValuePassingMode:ValuePassingMode傳送相關資訊環境值時所使用的模式。模式可以是其中一個
ValuePassingMode值 (ALL、ANCHOR_DATA、NONE、CUSTOM)。aAnchorToColumns: ColumnKOViewModel[]將此資料動作定錨至的資料欄。此為選擇性特性。若未提供，則資料動作可在所有資料欄上使用。
aContextColumns : ColumnKOViewModel[]相關資訊環境中包含此資料動作的資料欄，已於呼叫資料動作時傳送至資料動作目標。若未提供，所有標示的資料欄都會包含在相關資訊環境中。
CanvasDataAction 類別
CanvasDataAction 是 AbstractDataAction 基礎類別的子類別。您可以延伸此實體類別來提供您需要的功能。
CanvasDataAction
使用 CanvasDataAction 類別從視覺化中的資料點瀏覽至不同的工作區。您要瀏覽的工作區可以位於相同或不同的工作簿中。所有來源視覺化的作用中篩選條件會與描述資料點本身的「限定資料參照」一起傳送至目標工作區。如果您的資料動作需要瀏覽至其他工作區，則此類別為您的資料動作應該延伸的類別。
+ CanvasDataAction(oKOModel)
+ create(s)ID_sName) : CanvasDataAction + upgrade(oOldDataActionJS) : Object
+ invoke(oActionContext: ActionContext, oDataActionContext:DataActionContext) + getGadgetInfos(oReport) : AbstractGadgetInfo[] + validate() : DataActionError
# createProjectGadgetInfo(oReport) : AbstractGadgetInfo # createCanvasGadgetInfo(oReport) : AbstractGadgetInfo
EventDataAction 類別
EventDataAction 是 AbstractDataAction 基礎類別的子類別。您可以延伸此實體類別來提供您需要的功能。
EventDataAction
使用 EventDataAction 類別來發布從屬端事件。您可以接著註冊一或多個監聽事件並執行自己動作的訂戶。在較複雜的使用案例中使用此類型的資料動作，其中您已具有大量的程式碼，且能讓資料動作程式碼與呼叫資料動作時執行必要動作的程式碼保持鬆散結合。
+ EventDataAction(oKOModel)
+ create(sID_sName) : EventDataAction + upgrade(oOldDataActionJS) : Object
+ invoke(oActionContext: ActionContext, oDataActionContext:DataActionContext) + getGadgetInfos(oReport) : AbstractGadgetInfo[] + validate() : DataActionError
# createEventGadgetInfo(oReport) : AbstractGadgetInfo
AbstractHTTPDataAction 類別
AbstractHTTPDataAction 是抽象基礎類別，URLNavigationDataAction 和 HTTPAPIDataAction 子類別會繼承此類別的通用功能與預設行為。
AbstractHTTPDataAction
AbstractHTTPDataAction 抽象基礎類別由 URLNavigationDataAction 和 HTTPAPIDataAction 類別所共用。如果資料動作必須以新的瀏覽器頁籤開啟網頁，您必須延伸 URLNavigationDataAction。如果資料動作必須呼叫 HTTP API，則您應延伸 HTTPAPIDataAction。您可以決定最好是直接延伸 AbstractHTTPDataAction。
+ HTTPDataAction(oKOModel)
+ validate() : DataActionError
# createURLGadgetInfo(oReport) : AbstractGadgetInfo
URLNavigationDataAction 類別
URLNavigationDataAction 是 AbstractHTTPDataAction 基礎類別的子類別。
URLNavigationDataAction
使用 URLNavigationDataAction 類別以在新的瀏覽器頁籤中開啟特定的 URL。您可以使用當使用者呼叫資料動作時，選取的資料點衍生的值所取代的記號來撰寫 URL。資料點值會作為資料動作相關資訊環境的一部分傳送至外部網頁。例如，使用 CustomerID 資料欄建立呼叫的資料動作，此動作會在客戶關係管理應用程式 (例如 Oracle Sales Cloud) 中開啟客戶的網頁。
+ URLNavigationDataAction(oKOModel)
+ create(sID_sName) : URLNavigationDataAction + upgrade(oOldDataActionJS) : Object
+ invoke(oActionContext: ActionContext, oDataActionContext:DataActionContext) + getGadgetInfos(oReport) : AbstractGadgetInfo[]
HTTPAPIDataAction 類別
HTTPAPIDataAction 是 AbstractHTTPDataAction 基礎類別的子類別。您可以延伸此實體類別來提供您需要的功能。
HTTPAPIDataAction
使用 HTTPAPIDataAction 類別來呼叫 HTTP API，方法是建立非同步 XMLHTTPRequest (XHR) 並將其送出至指定的 URL。HTTP 回應代碼可讓訊息短暫顯示在工作區上。例如，您可以自訂要求將 JSON 或 XML 有效負載傳送至 REST 或 SOAP 伺服器，也可以自訂回應處理程式以顯示自訂使用者介面。
為了讓 HTTPAPIDataAction 資料動作運作，您必須將要存取的 HTTP API 其 URL 新增至「安全網域」清單，並對其授予連線存取權。請參閱註冊安全網域。
+ HTTPAPIDataAction(oKOModel)
+ create(sID_sName) : HTTPAPIDataAction + upgrade(oOldDataActionJS) : Object
+ invoke(oActionContext: ActionContext, oDataActionContext:DataActionContext) + getGadgetInfos(oReport) : AbstractGadgetInfo[]
# createHTTPMethodGadgetInfo(oReport) : AbstractGadgetInfo # createPostParamGadgetInfo(oReport) : AbstractGadgetInfo
從範本產生資料動作 Plug-in
您使用一系列的命令產生開發環境，並在其中填入 HTTP API 資料動作，以及建立自訂資料動作 Plug-in 時所需的資料夾和檔案。
所有 Plug-in 檔案都遵循相同的基本結構。您可以手動建立檔案和資料夾，也可以從範本產生。可使用的工具是 Oracle Analytics Desktop 隨附的 Oracle Analytics Desktop 軟體開發套件 (SDK) 的一部分。請參閱 Oracle Analytics Desktop SDK 參考資料。
使用下列命令產生開發環境，並在其中填入 HTTP API 資料動作。
產生的資料夾和檔案
新產生的資料動作開發環境包含下列資料夾和檔案：
1 %PLUGIN_DEV_DIR%\src\customdataaction 2 company-mydataaction\ 3 extensions\ 4 oracle.bi.tech.plugin.dataaction\ 5 company.mydataaction.json 6 nls\ 7 root\ 8 messages.js 9 messages.js 10 mydataaction.js 11 mydataactionstyles.css 12 plugin.xml
- 行 2：
company-mydataaction資料夾為您所指定的 ID。 - 行 6：
nls資料夾包含用於具體化字串的檔案，以便讓 Plug-in 提供原生語言支援。 - 行 7：
nls\root資料夾底下之檔案中的字串為預設字串，在沒有要求語言的翻譯時使用。 - 行 8：
messages.js檔案包含您可新增的 Plug-in 具體化字串。 - 行 9：
messages.js檔案必須包含對每個要為其提供本地化字串之額外語言所新增的項目。您必須在每個您要為其新增翻譯的地區設定nls資料夾底下新增相對應的資料夾。每個資料夾必須包含同一組檔案，且檔案名稱與nls\root資料夾底下新增的檔案名稱相同。 - 行 10：
mydataaction.js檔案是新產生的 JavaScript 模組範本，提供開發自訂資料動作的起始點。 - 行 11：
mydataactionstyles.css檔案可包含任何您要新增的 CSS 樣式，以及資料動作的使用者介面可以使用的 CSS 樣式。 - 行 12：
plugin.xml檔案會在 Oracle Analytics 註冊您的 Plug-in 與其檔案。
延伸資料動作基礎類別
選擇您要延伸的資料動作子類別，並已產生必要的資料夾與檔案之後，就可以開始寫入新資料動作特定的程式碼。
您可以從 %PLUGIN_DEV_DIR%\src\dataaction 底下找到新產生的資料動作程式碼。請參閱產生的資料夾和檔案以取得檔案與資料夾結構的說明。您必須編輯的主要檔案是 JavaScript 檔案。例如，如果您的自訂資料動作 ID 為 company.MyDataaction，則您要尋找的檔案是 %PLUGIN_DEV_DIR%\src\dataaction\company-mydataaction\mydataaction.js。
如果資料動作具有需要儲存的其他特性，您必須將它們作為可監測特性新增至「剔除模型」。如果提供給資料動作的 ID 為company.MyDataaction，則「剔除模型」的名稱為 mydataaction.MyDataActionKOModel (靠近 mydataaction.js 頂端的位置)。依照預設，會設定此「剔除模型」以延伸資料動作其超級類別所使用的「剔除模型」，因此您只需要新增其他特性至該模型中。
對於延伸 HTTPAPIDataAction 基礎類別的資料動作，請使用類似如下的程式碼：
1 - mydataaction.MydataactionKOModel = function (sClass, sID, sName, sVersion, sScopeID, aAnchorToColumns, eValuePassingMode, sURL,
eHTTPMethod, sPOSTParams)
2 - {
3 - mydataaction.MydataactionKOModel.baseConstructor.call(this, sClass, sID, sName, sVersion, sScopeID, aAnchorToColumns, eValuePassingMode, sURL, eHTTPMethod, sPOSTParams);
4 - };
5 - jsx.extend(mydataaction.MydataactionKOModel, dataaction.HTTPAPIDataActionKOModel);
- 行 1：此為「剔除模型」的建構子。它接受模型要加以儲存的特性。
- 行 3：此為超級類別的建構子 (也稱為
baseConstructor)，您會將其中一個「剔除模型」其超級類別處理的所有特性值傳送至此建構子。 - 行 5：這會設定此「剔除模型」類別的超級類別。
使用類似如下的程式碼新增字串和陣列，以設定由資料動作進行保存的特性。
1 mydataaction.MydataactionKOModel = function (sClass, sID, sName, sVersion, sScopeID, aAnchorToColumns, eValuePassingMode, sURL, eHTTPMethod, sPOSTParams)
2 {
3 mydataaction.MydataactionKOModel.baseConstructor.call(this, sClass, sID, sName, sVersion, sScopeID, aAnchorToColumns, eValuePassingMode, sURL, eHTTPMethod, sPOSTParams);
4
5
6 // Set Defaults
7 sMyString = sMyString || "My default string value";
8 aMyArray = aMyArray || [];
9
10
11 // Asserts
12 jsx.assertString(sMyString, "sMyString");
13 jsx.assertArray(aMyArray, "aMyArray");
14
15
16 // Add observable properties
17 this.sMyString = ko.observable(sMyString);
18 this.aMyArray = ko.observableArray(aMyArray);
19 };
20 jsx.extend(mydataaction.MydataactionKOModel, dataaction.HTTPAPIDataActionKOModel);選擇要覆寫的資料動作繼承方法
每個資料動作都必須實行各種不同的方法才能正常運作，因此您只需要覆寫這些實行您要變更之行為的方法。
一般方法
假設延伸其中一個具體資料動作類別，例如 HTTPAPIDataAction，其中大多數的必要方法都已經實行，因此您只需要覆寫實行想要變更之行為的方法。
本節描述各種方法及其預期的功能。
所有類型的資料動作必須實行此處描述的方法。
create(sID, sName)
當您建立的是新資料動作，並從下拉式功能表中選取資料動作類型時，會呼叫 create() 靜態方法。此方法負責下列作業：
- 建構您的資料動作使用的「剔除模型」類別。
「剔除模型」類別必須具有與所有其他特性的合理預設值一同傳送給
create()方法的 ID 和名稱。例如，針對幣別轉換資料動作，您可能想要設定要轉換為「美元」的預設幣別。「剔除模型」是可提供您預設值的正確位置。 - 從「剔除模型」建構資料動作的執行處理。
- 傳回資料動作的執行處理。
invoke(oActionContext, oDataActionContext)
當使用者從視覺化中的資料點其彈出式功能表呼叫您的資料動作時，系統會呼叫 invoke() 方法。此方法會傳送 DataActionContext 引數，此引數包含描述所選資料點、視覺化、篩選、工作簿及階段作業的中繼資料。請參閱資料動作服務類別。
validate()
當使用者按一下資料動作對話方塊中的確定時，系統會對每個資料動作呼叫 validate() 方法。validate() 方法會傳回 null 來指出所有項目皆有效，如果部分內容無效則傳回 DataActionError。如果對話方塊中的其中一個資料動作有錯誤，則錯誤會讓對話方塊無法關閉，並會向使用者顯示錯誤訊息。此方法使用 this.validateName() 方法驗證資料動作的名稱。
getGadgetInfos(oReport)
系統會呼叫 getGadgetInfos() 方法，讓使用者介面顯示資料動作特性欄位。此方法會按照您要在使用者介面顯示的順序傳回 GadgetInfos 陣列。系統提供所有最常見類型之欄位 (例如文字、下拉式清單、密碼、複選、選項按鈕、核取方塊) 的小工具，但如果您想要更複雜的欄位 (例如，其中多個小工具群組在一起，或視您選取的選項顯示不同的小工具欄位)，您可以建立自訂小工具。最佳做法是建立您要在陣列中建構每個 GadgetInfo 的方法，因為這會讓潛在子類別更容易從您提供的 GadgetInfo 中挑選。如果您遵循此最佳做法，則已經有不同的資料動作基礎類別實行的各種方法，可為它們在其使用者介面中所使用的每個欄位傳回 GadgetInfo。如果您還需要其中一個 GadgetInfo，則您可以呼叫對應的 create****GadgetInfo() 方法，並將其傳回值推送至小工具陣列。
isAllowedHere(oReport)
當使用者在視覺化中的資料點上按一下滑鼠右鍵，且使用者介面開始產生彈出式功能表時，系統會呼叫 isAllowedHere() 方法。如果有與所選資料點相關的資料動作，則方法會傳回 true，且資料動作會顯示在彈出式功能表中。如果方法傳回 false，則資料動作不會顯示在彈出式功能表中。請考量接受繼承自超級類別的預設行為。
upgrade(oOldDataActionJS)
若是要建立您的第一個資料動作，請勿使用 upgrade(oOldDataActionJS) 方法。只有在您已建立第一個「剔除模型」之後，且正在對第二版「剔除模型」的特性進行大幅變更時，才使用此模型。例如，如果第一版的資料動作將 URL 儲存在其「剔除模型」中，但您決定下一版會將 URL 元件部分儲存在個別的特性中 (例如 protocol、hostname、port、path、queryString 和 bookmark)。
第二版「剔除模型」程式碼會要求開啟已與第一版「剔除模型」程式碼一起儲存的資料動作，這會造成問題。為了解決此問題，系統會識別目前的資料動作程式碼版本比正在開啟的資料動作版本還要新，並對新資料動作類別呼叫 upgrade() 方法，然後在舊的資料動作「剔除模型」中傳送 (序列化至 JSON 物件)。接著您可以使用舊 JSON 物件來填入新的「剔除模型」，並傳回升級版本的 JSON 物件。這可確保當您改善資料動作程式碼時，舊資料動作中繼資料會繼續運作。
HTTPAPIDataAction 方法
延伸 HTTPAPIDataAction 類別時，它會提供下列的其他方法供您選擇覆寫：
getAJAXOptions(oDataActionContext)
getAJAXOptions() 方法由資料動作的 invoke() 方法呼叫。getAJAXOptions() 方法會建立 AJAX Options 物件，此物件描述您要資料動作提出的 HTTP 要求。oDataActionContext 物件會傳送給 getAJAXOptions() 方法，該物件包含描述所選資料點、視覺化、篩選、工作簿及階段作業的中繼資料。依據您嘗試整合的 HTTP API 要求設定 AJAX Options，並指定當 HTTPRequest 成功或產生錯誤時所要呼叫的函數。請參閱 JQuery 網站以取得 jQuery.ajax 物件及其特性的說明。
下列實行繼承自 HTTPAPIDataAction 類別。您必須重新寫入用以指定需求的繼承方法。例如，形成 HTTP 要求與處理 HTTP 回應的程式碼。此實行非常實用，因為它會顯示傳送給 getAJAXOptions() 函數的參數、預期傳回的物件及提供如何在該方法內建構程式碼的明確範例。
1 /**
2 * This method returns an object containing the AJAX settings used when the data action is invoked.
3 * Subclasses may wish to override this method to provide their own behavior.
4 * @param {module:obitech-reportservices/dataactionmanager.DataActionContext} oDataActionContext The context metadata describing where the data action was invoked from.
5 * @returns {?object} A JQuery AJAX settings object (see http://api.jquery.com/jQuery.ajax/ for details) - returns null if there is a problem.
6 */
7 dataaction.HTTPAPIDataAction.prototype.getAJAXOptions = function (oDataActionContext)
8 {
9 jsx.assertInstanceOfModule(oDataActionContext, "oDataActionContext", "obitech-reportservices/dataactionmanager", "DataActionContext");
10
11 var oAJAXOptions = null;
12 var oKOViewModel = this.getKOViewModel();
13 var sURL = oKOViewModel.sURL();
14 if (sURL)
15 {
16 // Parse the URL
17 var sResultURL = this._parseURL(sURL, oDataActionContext);
18 if (sResultURL)
19 {
20 // Parse the POST parameters (if required)
21 var eHTTPMethod = oKOViewModel.eHTTPMethod()[0];
22 var sData = null;
23 if (eHTTPMethod === dataaction.HTTPDataActionKOModel.HTTPMethod.POST)
24 {
25 var sPOSTParams = oKOViewModel.sPOSTParams();
26 sData = sPOSTParams.replace(dataaction.AbstractHTTPDataAction.RegularExpressions.LINE_END, "&");
27 sData = this._parseURL(sData, oDataActionContext, false);
28 }
29 oAJAXOptions = {
30 type: eHTTPMethod,
31 url: sResultURL,
32 async: true,
33 cache: false,
34 success: function (/*oData, sTextStatus, oJQXHR*/)
35 {
36 oDataActionContext.getReport().displaySuccessMessage(messages.HTTP_API_DATA_ACTION_INVOCATION_SUCCESSFUL.format(oKOViewModel.sName()));
37 },
38 error: function (oJQXHR/*, sTextStatus, sError*/)
39 {
40 oDataActionContext.getReport().displayErrorMessage(messages.HTTP_API_DATA_ACTION_INVOCATION_FAILED.format(oKOViewModel.sName(), oJQXHR.statusText, oJQXHR.status));
41 }
42 };
43 if (sData)
44 {
45 oAJAXOptions.data = sData;
46 }
47 }
48 }
49 return oAJAXOptions;
50 };使用升級處理程式進行剔除模型變更
對於部分「剔除模型」變更，您需要使用升級處理程式來升級資料動作 Plug-in。
改善資料動作 Plug-in 但不變更剔除模型時，通常要編輯 JavaScript 或 CSS 檔案、建立新壓縮檔，以及使用新壓縮檔取代現有資料動作 Plug-in。不過，如果您已變更資料動作的「剔除模型」，則可能需要變更資料動作 VERSION 特性以及提供升級處理程式。
決定是否需要使用升級處理程式：
- 如果您在「剔除模型」中重新命名特性。
- 如果您在「剔除模型」中將多個特性結合成單一特性。
- 如果您在「剔除模型」中將單一特性分割成多個特性。
- 如果您新增「剔除模型」特性，且其正確的預設值取決於「剔除模型」中的其他值。
- 如果您新增「剔除模型」特性，且可以提供對資料動作的所有用法都正確的預設值。
- 如果您移除「剔除模型」中的特性，因為您的資料動作程式碼不再使用該特性。
資料動作 Plug-in 檔案參照
每個資料動作 Plug-in 都需要 plugin.xml 檔案，且每個 plugin.xml 檔案可以包含任意數目的資料動作。
資料動作 plugin.xml 檔案範例
plugin.xml 檔案包含 tns:obiplugin、tns:resources 以及 tns:extension 這三個主要區段。
plugin.xml 範例
此範例顯示一個資料動作的典型 plugin.xml 檔案。
1 <?xml version="1.0" encoding="UTF-8"?>
2 <tns:obiplugin xmlns:tns="http://plugin.frameworks.tech.bi.oracle"
3 id="obitech-currencyconversion"
4 name="Oracle BI Currency Conversion"
5 version="0.1.0.@qualifier@"
6 optimizable="true"
7 optimized="false">
8
9
10 <tns:resources>
11 <tns:resource id="currencyconversion" path="scripts/currencyconversion.js" type="script" optimizedGroup="base"/>
12 <tns:resource-folder id="nls" path="resources/nls" optimizable="true">
13 <tns:extensions>
14 <tns:extension name="js" resource-type="script"/>
15 </tns:extensions>
16 </tns:resource-folder>
17 </tns:resources>
18
19
20 <tns:extensions>
21 <tns:extension id="oracle.bi.tech.currencyconversiondataaction" point-id="oracle.bi.tech.plugin.dataaction" version="1.0.0">
22 <tns:configuration>
23 {
24 "host": { "module": "obitech-currencyconversion/currencyconversion" },
25 "resourceBundle": "obitech-currencyconversion/nls/messages",
26 "properties":
27 {
28 "className": "obitech-currencyconversion/currencyconversion.CurrencyConversionDataAction",
29 "displayName": { "key" : "CURRENCY_CONVERSION", "default" : "Currency Conversion" },
30 "order": 100
31 }
32 }
33 </tns:configuration>
34 </tns:extension>
35 </tns:extensions>
36
37 </tns:obiplugin>資料動作 plugin.xml 檔案特性區段 - tns:obiplugin
tns:obiplugin 區段主要定義所有類型之 Plug-in 的通用特性。
Plug-in 特性
tns:obiplugin 區段會定義所有 Plug-in 類型通用的特性。
1 <?xml version="1.0" encoding="UTF-8"?> 2 <tns:obiplugin xmlns:tns="http://plugin.frameworks.tech.bi.oracle" 3 id="obitech-currencyconversion" 4 name="Oracle BI Currency Conversion" 5 version="0.1.0.@qualifier@" 6 optimizable="true" 7 optimized="false">
- 行 1：XML 宣告。
- 行 2：Plug-in 之根 XMLElement 的開頭標記，以及整個 plugin.xml 檔案中使用的
tns命名空間宣告。 - 行 3：Plug-in 的唯一 ID。
- 行 4：Plug-in 的預設顯示名稱 (無法使用本地化版本時使用)。
- 行 5：Plug-in 的版本號碼。
- 行 6：指示 JS/CSS 是否可以最佳化 (壓縮) 的布林值。
- 行 7：指示 JS/CSS 是否已經最佳化 (壓縮) 的布林值。
資料動作 plugin.xml 檔案資源區段 - tns:resources
tns:resources 區段主要註冊計入 Plug-in 的所有檔案。
資源
1 <tns:resources> 2 <tns:resource id="currencyconversion" path="scripts/currencyconversion.js" type="script" optimizedGroup="base"/> 3 <tns:resource-folder id="nls" path="resources/nls" optimizable="true"> 4 <tns:extensions> 5 <tns:extension name="js" resource-type="script"/> 6 </tns:extensions> 7 </tns:resource-folder> 8 </tns:resources>
您需要在此處註冊每個 JavaScript、CSS、影像以及翻譯資源檔案。此區段包含在 <tns:resources> 元素內，其中包含下列任何數目的元素：
<tns:resource>這些元素用來註冊單一檔案 (例如，JavaScript 或 CSS 檔案)。
<tns:resource-folder>這些元素用來同時註冊指定資料夾底下的所有檔案。例如，影像資料夾或包含原生語言支援的資源檔案的資料夾。
以下各節提供如何註冊每個檔案類型的其他資訊。
JavaScript 檔案
Plug-in 中的每個 JavaScript 檔案必須使用類似下列所示的行註冊。
<tns:resource id="currencyconversion" path="scripts/currencyconversion.js" type="script" optimizedGroup="base"/>
其中：
- id 是指定給檔案的 ID。
將 ID 設為與沒有 .js 副檔名的 JavaScript 檔案名稱相同。
- path 是從 plugin.xml 檔案至 JavaScript 檔案的相對路徑。JavaScript 檔案必須儲存在 Plug-in 的
scripts目錄底下。請對 JavaScript 檔案全部使用小寫字元，不可包含特殊字元 (例如，底線、連字號)。
- type 是正在註冊的檔案類型。對於 JavaScript 檔案，它必須設為
script。 - optimizedGroup 將多個 JavaScript 檔案分組成單一壓縮檔案。第三方 Plug-in 必須將此項目保留為
base。
CSS 檔案
Plug-in 中的每個 CSS 檔案必須使用類似下列所示的行註冊。
<tns:resource id="currencyconversionstyles" path="resources/currencyconversion.css" type="css"/>
其中：
- id 是指定給檔案的 ID。
將 ID 設為與沒有 .css 副檔名的 CSS 檔案名稱相同。
- path 是從 plugin.xml 檔案至 CSS 檔案的相對路徑。CSS 檔案必須儲存在 Plug-in 的
resources目錄底下。請對 CSS 檔案全部使用小寫字元，不可包含特殊字元 (例如，底線、連字號)。
- type 是正在註冊的檔案類型。對於 CSS 檔案，它必須一律設為
css。
影像資料夾
如果 Plug-in 具有您需要從 Javascript 程式碼內進行參照的影像，請將它們放置在 Plug-in 目錄結構內的 resources/images 目錄中，並將 <tns:resource-folder> 元素新增至 plugin.xml 檔案，如下所示：
<tns:resource-folder id="images" path="resources/images" optimizable="false"/>
如果只有 CSS 檔案參照您的影像，則您不需要將 <tns:resource-folder> 元素新增至 plugin.xml 檔案。在此情況下，您仍然必須將它們新增至 resources/images 目錄，以便可以從 CSS 檔案使用相對路徑參照它們。
原生語言支援資源資料夾
Oracle Analytics 實行原生語言支援。這需要開發人員將顯示在其使用者介面中的字串具體化成個別的 JSON 資源檔案。您可以接著在指定的目錄結構中提供這些檔案的各種本地化版本，Oracle Analytics 會針對使用者選擇的語言自動使用正確的檔案。您可以視需要提供資源檔案所需的翻譯版本。原生語言支援資源資料夾會將 Oracle Analytics 指向 Plug-in 所使用之指定的原生語言支援目錄結構的根。使用原生語言支援資源檔案的所有 Plug-in 必須具有與以下範例所示完全相同的 <tns:resource-folder> 項目。
1 <tns:resource-folder id="nls" path="resources/nls" optimizable="true"> 2 <tns:extensions> 3 <tns:extension name="js" resource-type="script"/> 4 </tns:extensions> 5 </tns:resource-folder>
請參閱產生的資料夾和檔案以瞭解檔案內容與應遵循的指定目錄結構詳細資訊。
資料動作 plugin.xml 檔案擴充區段 - tns:extension
對於您要 Plug-in 提供的每個資料動作，您必須使用 <tns:extension> 元素註冊資料動作擴充，類似以下所示：
<tns:extension id="oracle.bi.tech.currencyconversiondataaction" point-id="oracle.bi.tech.plugin.dataaction" version="1.0.0">
<tns:configuration>
{
"host": { "module": "obitech-currencyconversion/currencyconversion" },
"resourceBundle": "obitech-currencyconversion/nls/messages",
"properties":
{
"className": "obitech-currencyconversion/currencyconversion.CurrencyConversionDataAction",
"displayName": { "key" : "CURRENCY_CONVERSION", "default" : "Currency Conversion" },
"order": 100
}
}
</tns:configuration>
</tns:extension>
其中：
- id 是您提供給資料動作的唯一 ID。
- point-id 是您要註冊的擴充類型。針對資料動作擴充，此項目必須設為
oracle.bi.tech.plugin.dataaction。 - version 是您的擴充定義使用的擴充 API 版本 (請保留設定為 1.0.0)。
<tns:configuration> 元素包含進行下列定義的 JSON 字串：
- host.module - 此為包含資料動作之模組的完整名稱。此完整模組名稱採用
%PluginID%/%ModuleName%的格式，其中：%PluginID%必須取代為您在<tns:obiplugin>元素之 ID 屬性中指定的 Plug-in ID。%ModuleName%必須取代為包含資料動作之 JavaScript 檔案的<tns:resource>元素 ID 屬性中指定的資源 ID。
- resourceBundle - 此為包含此資料動作之本地化資源的資源檔案其「原生語言支援」路徑。如果您的資源檔案名稱為 messages.js 且正確儲存在指定的
nls目錄結構中，則請將此特性設為%PluginID%/nls/messages(其中%PluginID%必須取代為您在plugin.xml檔案頂端之<tns:obiplugin>元素的 ID 屬性中指定的 Plug-in ID)。 - properties.className - 此為指定給正在進行註冊之資料動作的完整類別名稱。此完整類別名稱採用
%PluginID%/%ModuleName%.%ClassName%的格式，其中：%PluginID%必須取代為您在<tns:obiplugin>元素之 ID 屬性中指定的 Plug-in ID。%ModuleName%必須取代為包含資料動作之 JavaScript 檔案的<tns:resource>元素 ID 屬性中指定的資源 ID。%ClassName%必須取代為您在 JavaScript 檔案中提供給資料動作類別的名稱。
- properties.displayName - 此特性包含一個物件以及兩個進一步的特性：
- key為「原生語言支援」訊息索引鍵，可用來在指定的
resourceBundle內查尋資料動作的本地化顯示名稱。 - default 為預設顯示名稱，會在因某些原因找不到本地化版本的顯示名稱時使用。
- key為「原生語言支援」訊息索引鍵，可用來在指定的
- properties.order - 此特性可讓您提供提示，可用來決定此資料動作在資料動作中顯示時應該顯示的位置。在順序特性中具有較小號碼的資料動作會出現在具有較大號碼的資料動作之前。如果出現等值的情況，資料動作將依系統載入它們的順序顯示。