跳至主要內容
文件
文件
Adaptive Planning
上次更新時間 ：2024-03-08
建立自訂雲端載入器

建立自訂雲端載入器

建立自訂雲端載入器需要徹底的 JavaScript 程式設計知識和經驗。如果您沒有經驗豐富的 JavaScript 程式設計人員，則不該開始建立自訂雲端載入器。您還必須在嘗試建立自訂雲端載入器之前，被指派「管理 > 權限集」中的整合開發人員權限。
自訂雲端載入器可讓您匯出
Adaptive Planning
 將規劃資料直接傳送至第三方雲端系統。
觀看影片
︰3 分 16 秒

基本步驟

  1. 輸入資料來源設定。
  2. 定義參數。
  3. 使用 CCDS API 撰寫 JavaScript， ai Namespace。
  4. 定義業務規則。
  5. 執行或排程載入器。

Prerequisites

  • 驗證您是否具有整合開發人員權限
  • 驗證
    Adaptive Planning
     您要匯出的計畫資料已存在於階段處理表中。
  • 為您的外部系統建立 OAuth 憑證，或取得可明確包含在 JavaScript 中的憑證
  • 了解您需要將哪些參數傳遞至外部系統，以及外部系統預期的預設值
  • 了解如何寫入至外部系統的端點

導覽

Compass.png From the nav menu, go to
Integration
Design Integrations

輸入資料來源設定

「資料來源設定」可讓您從實例的階段處理資料中選擇要使用的來源表格，決定要使用的憑證，以及在載入器執行期間要記錄的記錄詳細資料層級。

新建自訂雲端載入器

  1. 前往
    整合 > 設計整合
    ，以存取資料設計工具。
  2. 在元件庫的「載入器」資料夾中，選取
    新建載入器
    。
  3. 選取
    自訂雲端載入器
    做為載入器類型並輸入名稱。
    如果您沒看到「自訂雲端載入器」這個選項，則表示此實例未啟用該選項，或者您沒有存取所需的整合開發人員權限。
  4. 選取
    建立
    。

選取來源表格、憑證和記錄層級

  1. 輸入自訂雲端載入器的資訊︰
    • 來源表格︰
       選取包含以下項目的階段處理表︰
      Adaptive Planning
       匯出的規劃資料。
    • 需要憑證︰
      如果外部系統需要 OAuth，而且您需要具有整合操作人員權限的使用者才能選取適當的 OAuth 憑證，則選取此項。
    • 憑證︰
      選取原有的 OAuth 憑證。
    • 記錄層級︰
      選取載入器執行時要記錄多麼詳細的資料︰
      • 「錯誤」
        ：
        僅記錄錯誤。
      • 「資訊」
        ：
        記錄所有基本資訊，例如資料來源的更新時間
      • 「詳細資訊」
        ：
        提供所有階段和動作的詳盡資訊主要用於偵錯或稽核，因為其產生的記錄資訊可能超過一般用途的實際情況。
  2. 在「動作」功能表中按一下
    儲存
    。

定義參數

定義您的 javaScript 匯出所需參數
Adaptive Planning
 資料複製到您的外部系統。參數可包含連線 URL、使用者名稱、密碼和維度
Adaptive Planning
，以及其他資訊。參數化設定可讓您在執行階段變更其值。靜態設定在載入器執行期間持續有效。
  1. 選取
    設計工具設定
    。
  2. 將「參數化」或「靜態」設定項目從
    設定元件
    窗格拖曳到
    設計工具設定
    中。
    • 如果您在載入器執行階段未提供其他設定值，則在此輸入的參數化設定值會變成載入器預設值。
    • 您在此輸入的靜態設定會在每次載入器執行時使用，因此不需要在執行階段輸入。
      • 布林值︰表示為 1 或 0 的值。
      • 維度︰內的維度管理中的維度
        Adaptive Planning
        。
      • 整數︰非負數的整數。
      • 密碼︰密碼。此值一旦儲存便無法檢視。
      • 期間範圍︰以下的時段範圍︰
        Adaptive Planning
        。
      • 文字︰英數字元值。
  3. 連按兩下參數項目以輸入名稱並變更其值。
  4. 拖入您所需的任意數量項目以在 JavaScript 中參照。
  5. 儲存載入器。
  6. 在 JavaScript 中使用參數的名稱來參照它。

撰寫 JavaScript

  1. 選取
    指令碼
    。
  2. 選取既有的範本並進行變更，或選取
    新增指令碼
    ，自行建立範本。
  3. 使用 CCDS API，撰寫您希望載入器執行的 javaScript ai Namespace。
  4. 驗證指令碼是否包含必要的︰
  5. 按名稱參照您在「設計工具設定」中建立的任何參數。
  6. 儲存指令碼。
您可以使用鍵盤快速鍵
CTRL + Shift + B
 在編輯器中修改指令碼的格式和美化指令碼。以
Ctrl+H
 啟動尋找及取代功能。
您可以將較長的指令碼劃分成多個檔案，以便維護。
範例︰您可以包含所有
testConnection
 一個指令碼中的邏輯，稱為
testconnectionscript
。第二個指令碼，名為
exportdatascript
, 可包含
exportData
 邏輯
如果在多個指令碼中宣告了相同的函數，則會使用最近新增的指令碼中的函數。

在自訂雲端載入器指令碼中使用 OAuth

當您選取自訂雲端載入器需要憑證時，您的指令碼必須包含
ai.https.authorizedRequest.
請參閱 「使用 OAuth 驗證」， 以了解如何建立 OAuth 憑證。
執行參照憑證的自訂雲端載入器的人員應該︰
  1. 在執行載入器前選取
    要求授權
    。
  2. 提供外部系統端點所需的任何其他授權詳細資料，例如範圍。
  3. 選取
    測試連線
    ，確認 OAuth 憑證已成功傳遞至端點。
  4. 請注意授權狀態中的授權日期和使用者 ID。外部系統的授權到期日期各不相同。在「動作」窗格中選取「重設授權」，視需要重新授權。

定義業務規則

您可以使用業務規則來建立 SQL 運算式，以限制匯出至外部系統的階段處理資料。只會載入符合篩選條件的記錄。
業務規則分頁包含用於輸入 SQL 的文字區域。
  1. 選取
    業務規則
    分頁。
  2. 選取
    編輯
    。
  3. 輸入 SQL 運算式。您可以按一下「可用欄」中的項目，將該欄帶入 SQL 運算式，而不需加以輸入。
  4. 選取
    套用
    以檢查您的語法。錯誤會使運算式周圍的框線變成紅色。將滑鼠移至運算式上方，以查看語法錯誤資訊。
  5. 更正語法中的任何錯誤，然後選取
    套用
    。只會載入符合 SQL 運算式的階段處理列。

在整合任務中包含自訂雲端載入器

自訂雲端載入器必須做為整合任務執行。任何任務都可包含一或多個載入器，任務還可以包含其他整合任務和載入器。請參閱「」 Create Integration Tasks。
最佳做法︰每個載入器各有不同的整合任務。
如果任務包含多個載入器，則在執行任務時會顯示每個載入器的參數。如果在任務內的載入器中使用了一般/共用參數，則該任務只會提示輸入參數一次。您可以選擇覆寫參數提示。
執行排定的任務時，系統會使用在建立載入器時儲存的參數預設值。

CCL 指令碼範例

使用以下範例連線至您的 AWS S3 實例，以便匯出和檢視您的試算表資料。您將需要儲存區名稱、金鑰、存取金鑰、秘密金鑰和區域值。如需更多資訊和範例代碼，請參閱 「ai.awss3」。
  1. 設定試算表資料來源。
  2. 在
    載入器
    窗格中新建自訂雲端載入器。
  3. 導覽至
    資料來源設定
    分頁，並在
    來源表格
    欄位中選取您的試算表資料來源。
  4. 在
    指令碼
    分頁中復制以下範例指令碼。 
    
 // Manually invoke this method via 'Test connection'
function testConnection(context) {
    return true;
}
// Manually invoke this method via 'Run manually'
function exportData(context) {
   //"xxx" is the name of your Amazon S3 bucket. 
    var bucketName = 'xxx';
    //Name of the sample CSV file to which data from your spreadsheet data source is exported
    var key = 'exampleTest.csv';
    //"xxxx" is the access key for your AWS S3 bucket.
    var awsAccessKey = 'xxxx';
    //"xxxx" is the secret key of your AWS S3 bucket. 
    var awsSecretKey = 'xxxx';
    var region = 'us-west-1';
    // Step 1: Get the data
    var reader = context.createTableReader();
    // Step 2: Process and export the data
    var result = "Column,Heading,Names\n";
    var row = null;
    while ((row = reader.readRow()) !== null) {
       // remove meta columns we don't need
       row.length = row.length - 2;
       result += row.join() + '\n';
   }
    ai.awss3.putFile(bucketName, key, result, region, awsAccessKey, awsSecretKey);
}
  5. 在
    動作
    窗格中選取
    儲存
    。
  6. 若要執行指令碼，請在
    動作
    窗格中選取
    手動執行
    。