管理巨集、偏好設定和執行階段引數

Cloud Data Fusion 巨集、偏好設定和執行階段引數可讓您動態參數化管道,並建立可重複使用的範本。您可以在各環境中建立階層式預設設定,並在預覽或執行管道時覆寫設定值。

重要詞彙

巨集
巨集是 Cloud Data Fusion 外掛程式設定中的預留位置。這些變數會以 ${ } 括住,例如 ${input_file_path}。巨集可讓您使用預留位置值,並在執行階段替換為實際值,提高管道的彈性。這樣一來,您就能動態設定參數,例如檔案路徑和資料表名稱。
偏好設定
偏好設定是預先定義的設定,適用於 Cloud Data Fusion 內的多個層級,包括系統本身、命名空間、應用程式 (包含管道),以及管道內的個別程式。您可以透過偏好設定,為常用設定指定預設值。預設值可由較低層級的管道和計畫沿用,減少重複的設定工作。
執行階段引數
執行階段引數是鍵/值組合,可在您部署或執行管道時,為巨集提供值,並可能覆寫偏好設定。可自訂性高,可讓您依據每個 pipeline 執行作業調整設定,而不必修改基礎 pipeline 或偏好設定。

設定巨集

如要使用巨集做為外掛程式屬性值,請按照下列步驟操作:

  1. 在 Cloud Data Fusion Studio 中,前往外掛程式節點,然後按一下「Properties」(屬性)。
  2. 前往要使用巨集的欄位,然後按一下欄位旁的「M」。
  3. 輸入巨集的鍵。例如,在檔案來源的外掛程式屬性中,在「Format」(格式) 欄位輸入下列鍵:${format.type}。

設定巨集值

請先設定巨集的值,再預覽管道資料及執行管道。您可以在下列位置設定巨集值:

  • 引數設定器外掛程式
  • 執行階段引數
  • 應用程式偏好設定
  • 命名空間偏好設定
  • 系統偏好設定

使用巨集執行管道時,會執行下列作業:

  • Cloud Data Fusion 會先檢查管道是否包含引數 setter 外掛程式:
    • 如果外掛程式有引數設定工具,Cloud Data Fusion 會使用該工具中的巨集值。
    • 如果沒有引數設定器,或引數設定器中未指派巨集,Cloud Data Fusion 會改用管道執行階段引數中的值。
  • 執行階段引數會沿用應用程式偏好設定中的巨集。
  • 應用程式偏好設定會沿用命名空間偏好設定的巨集
  • 命名空間偏好設定會沿用系統偏好設定的巨集。

範例

巨集常用於路徑欄位。您可以使用動態路徑,而非硬式編碼路徑。舉例來說,在 Cloud Storage 來源外掛程式中,您可以使用多個巨集取代路徑值。下列值會分隔 bucket、資料夾和檔案元素:gs://${bucket.name}/${folder}/${file.name}。

以下範例會從靜態 bucket 和名稱非靜態的檔案載入資料,請輸入 bucket 名稱,並使用巨集做為檔案名稱:gs://<BUCKET_NAME>/${folder}/${file.name}。

詳情請參閱「巨集和巨集函式」。

設定偏好

以下各節說明偏好設定階層,以及偏好設定的設定、繼承或覆寫方式。

設定系統偏好設定

您可以設定系統偏好設定。由於巨集名稱不得重複,因此每項偏好設定都會套用至使用該巨集的所有管道。

舉例來說,假設您有一個管道,其來源為資料庫,並使用巨集來表示資料庫名稱和使用者名稱。您可以在系統偏好設定中,設定資料庫和使用者名稱偏好設定。該執行個體中的每個命名空間和管道都會沿用這些偏好設定。

如要設定系統偏好設定,請按照下列步驟操作:

  1. 在 Cloud Data Fusion Studio 中,依序點選「System admin」(系統管理員) > 「Configuration」(設定)。
  2. 依序點選「 系統偏好設定」>「編輯系統偏好設定」。
  3. 在「Preferences」(偏好設定) 對話方塊中,輸入新的偏好設定或編輯現有偏好設定。
  4. 按一下「Save & Close」。所有命名空間、應用程式和管道都可使用這些偏好設定。

設定命名空間偏好設定

您可以為個別命名空間設定偏好設定。

設定命名空間偏好設定時,系統會顯示所有沿用的系統偏好設定。設定命名空間的偏好設定時,您可以設定不同的值,覆寫沿用的偏好設定。您也可以新增命名空間偏好設定。

如要設定命名空間偏好設定,請按照下列步驟操作:

  1. 在 Cloud Data Fusion Studio 中,依序點選「System admin」(系統管理員) >「Configuration」(設定)。
  2. 按一下「 Namespaces」(命名空間),然後選取命名空間,開啟設定頁面。
  3. 如要編輯沿用的偏好設定或新增偏好設定,請前往「Preferences」(偏好設定) 分頁,然後按一下「Edit」(編輯)。「Preferences」對話方塊隨即開啟,您可以在其中輸入新的偏好設定,或覆寫沿用的系統偏好設定。按一下 「Add」(新增),然後輸入巨集的鍵和新值。
  4. 按一下「Save & Close」。系統會以新值建立命名空間偏好設定,其優先順序高於系統偏好設定。

設定應用程式偏好

您可以為命名空間中每個已部署的管道設定偏好設定。設定應用程式偏好設定時,系統會顯示所有繼承的系統和命名空間偏好設定。設定應用程式的偏好設定時,您可以設定不同的值來覆寫沿用的偏好設定,或為應用程式新增偏好設定:

  1. 在 Cloud Data Fusion Studio 中,按一下 ,然後點選「Namespace」(命名空間) 選單,選取要新增應用程式偏好設定的命名空間。
  2. 按一下「控制中心」。
  3. 按一下「設定偏好設定」扳手圖示。系統會顯示所有沿用偏好設定的清單。
  4. 如要編輯沿用的偏好設定或新增偏好設定,請前往「Preferences」(偏好設定) 分頁,然後按一下「Edit」(編輯)。「Preferences」對話方塊隨即開啟,您可以在其中輸入新的偏好設定,或覆寫沿用的系統偏好設定。按一下 「Add」(新增),然後輸入巨集的鍵和新值。
  5. 按一下「Save & Close」。系統會以新值建立應用程式偏好設定,覆寫系統或命名空間偏好設定。執行已部署的管道時,應用程式偏好設定會顯示為執行階段引數,您可以視需要編輯。

設定執行階段引數

設定執行階段引數,在部署或執行管道時,為巨集提供值,並可能覆寫偏好設定。

預覽資料的執行階段引數

如要在 Cloud Data Fusion Studio 預覽資料時,設定管道中各巨集的值,請依序點選「List」(清單) >「Configure」(設定)。

執行已部署管道的執行階段引數

如果管道包含巨集,請在部署管道後新增執行階段引數,設定巨集的值。

部署含有巨集的管道時,請按一下「Run」(執行) 旁的 下拉式選單,開啟「Runtime arguments」(執行階段引數) 對話方塊,並設定每個巨集的值。

設定管道偏好設定

如要設定管道偏好設定,請按照下列步驟操作:

  1. 在 Cloud Data Fusion Studio 中,依序點選 「List」(清單) > 「Deployed」(已部署),然後選取已部署的管道來查看。
  2. 在管道畫布中,按一下「Run」(執行) 旁邊的 下拉式選單。「Runtime arguments」(執行階段引數) 對話方塊隨即開啟。
  3. 在開啟的「Runtime arguments」(執行階段引數) 對話方塊中,指定管道中每個巨集的值。

偏好設定、巨集和執行階段引數總覽

您可以在下列層級設定偏好設定:

  • 系統偏好設定:設定整個執行個體偏好設定 (例如預設值) 的最高層級。
  • 命名空間偏好設定:沿用系統偏好設定。您可以為特定命名空間設定偏好設定。
  • 應用程式偏好設定:沿用命名空間偏好設定。這些變數可以專屬於個別應用程式 (包含管道)。
  • 執行階段引數:鍵/值組合,會覆寫較高層級的偏好設定。

如果您在系統偏好設定層級設定偏好設定,巨集值會自動填入命名空間偏好設定、應用程式偏好設定和執行階段引數。

如果您在命名空間層級設定偏好設定,這些設定會顯示在應用程式偏好設定的繼承偏好設定清單中。如果管道使用偏好設定中定義的巨集,執行階段引數會使用偏好設定中定義的鍵/值組合。您可以在每個偏好設定層級和執行階段引數中覆寫偏好設定的值。

偏好設定、巨集和執行階段引數適用於下列用途:

  • 開發管道。在需要外掛程式屬性動態值的位置嵌入巨集。
  • 選用:設定偏好設定。在不同層級的偏好設定中,為巨集設定預設值。
  • 部署及執行管道。執行管道時,會發生以下情況:
    • 系統會套用相關層級的偏好設定,例如系統偏好設定或命名空間偏好設定。
    • 您提供的任何執行階段引數,都會覆寫偏好設定中指派給巨集的值。
    • Cloud Data Fusion 會從執行階段引數 (如果未提供執行階段引數,則為偏好設定) 替換巨集的值,藉此解析巨集。

範例

管道具有 BigQuery 接收器,其資料表名稱值必須動態變更。如要設定,請按照下列步驟操作:

  1. 設定巨集。在接收器的屬性中,在「Table name」(資料表名稱) 欄位中使用下列巨集:${output_table}.
  2. 設定偏好設定。在應用程式偏好設定中,為 ${output_table} 設定偏好設定,並使用下列預設值:data_staging。
  3. 設定執行階段引數。執行管道時,請提供執行階段引數,例如 output_table=final_analytics_data。

在管道執行期間,巨集 ${output_table}, 會替換為 final_analytics_data。

後續步驟