DBMS_CLOUD_PIPELINE 套裝軟體

必備條件

身為開發人員，您可以將 DBMS_CLOUD 程序與部署在 Oracle Public Cloud 、多重雲端或 Exadata Cloud@Customer 上的 Autonomous Database 搭配使用。

視部署選擇而定，必須符合下列先決條件，才能將 DBMS_CLOUD 程序與 Amazon S3 、Azure Blob Storage 及 Google Cloud Storage 服務提供者搭配使用。

Oracle Public Cloud 或多雲端
Exadata 客戶私有雲

機組管理員必須使用 NAT 閘道設定輸出連線，如下所述：

請依照 Oracle Cloud Infrastructure 文件中建立 NAT 閘道的指示，在 Autonomous Database 資源所在的虛擬雲端網路 (VCN) 中建立 NAT 閘道。
建立 NAT 閘道之後，請在 Autonomous Database 資源所在的每個子網路新增路由規則和傳出安全規則 (在 VCN 中)，以便這些資源能夠使用此閘道從您的 Azure AD 執行處理取得公開金鑰：
1. 移至子網路的子網路詳細資訊頁面。
2. 在子網路資訊頁籤中，按一下子網路的路由表名稱，以顯示其路由表詳細資訊頁面。
3. 在現有路由規則的表格中，檢查是否已有具有下列特性的規則：
  - 目標：0.0.0.0/0
  - 目標類型：NAT 閘道
  - 目標：剛在 VCN 中建立的 NAT 閘道名稱
  如果沒有這類規則，請按一下新增路由規則，然後新增具有這些特性的路由規則。
4. 返回子網路的子網路詳細資訊頁面。
5. 在子網路的安全清單表格中，按一下子網路安全清單的名稱，以顯示其安全清單詳細資訊頁面。
6. 在側邊功能表的資源下，按一下傳出規則。
7. 在現有傳出規則的表格中，檢查是否已有具有下列特性的規則：
  - 目標類型： CIDR
  - 目的地：0.0.0.0/0
  - IP 協定： TCP
  - 來源連接埠範圍： 443
  - 目的地連接埠範圍：全部
  如果該規則不存在，請按一下新增輸出規則，然後新增具有這些特性的輸出規則。

您環境中的 HTTP 代理主機設定值必須允許資料庫存取雲端服務提供者。

這些設定值是由機組管理員在建立 Exadata Cloud@Customer 基礎架構時定義的，如使用主控台在 Cloud@Customer 上佈建 Exadata 資料庫服務中所述。

附註：

必須等到 Exadata 基礎架構為需要啟用狀態後，才能編輯網路組態 (包括 HTTP 代理主機)。啟用之後，您就無法編輯這些設定值。

在 My Oracle Support 中設定已啟動設定之 Exadata 基礎架構的 HTTP 代理主機時，必須要有服務要求 (SR)。請參閱在 My Oracle Support 中建立服務要求瞭解詳細資訊。

DBMS_CLOUD_PIPELINE 子程式摘要

此表格摘要 DBMS_CLOUD_PIPELINE 套裝軟體中包含的子程式。

子程式	描述
CREATE_PIPELINE 程序	建立新資料管線。
DROP_PIPELINE 程序	刪除現有的資料管線。
RESET_PIPELINE 程序	重設資料管線的追蹤狀態。使用重設管線從資料載入或匯出的初始狀態重新啟動管線。視管線類型而定，選擇性重設管線可以永久清除資料庫或物件存放區中的資料。
RUN_PIPELINE_ONCE 程序	在目前的前景階段作業執行管線的隨選執行，而非排定的工作。
SET_ATTRIBUTE 程序	設定管線屬性。有兩個超載程序，一個是設定單一屬性，另一個是使用屬性名稱 / 值組的 JSON 文件設定多個屬性
START_PIPELINE 程序	啟動資料管線。管線啟動後，管線作業將會根據管線屬性中設定的「間隔」，持續在排定的工作中執行。
STOP_PIPELINE 程序	停止資料管線。管線停止時，不會為管線排定任何未來的工作。

CREATE_PIPELINE 程序

此程序會建立新的資料管線。

語法

DBMS_CLOUD_PIPELINE.CREATE_PIPELINE(
      pipeline_name        IN   VARCHAR2,
      pipeline_type        IN   VARCHAR2,
      attributes           IN   CLOB        DEFAULT NULL,
      description          IN   VARCHAR2    DEFAULT NULL
);

參數

Parameter - 參數	描述
`pipeline_name`	指定管線的名稱。管線名稱必須遵循 Oracle SQL ID 的命名規則。如需詳細資訊，請參閱 Oracle Database Database PL/SQL Language Reference 中的 Identifiers 或 Oracle Database 23ai Database PL/SQL Language Reference 。此為必要參數。
`pipeline_type`	指定管線類型。有效值：`LOAD`、`EXPORT` 此為必要參數。
`attributes`	JSON 格式的管線屬性。預設值：`NULL` 如需詳細資訊，請參閱 DBMS_CLOUD_PIPELINE 屬性。
`description`	管線的描述。預設值：`NULL`

DROP_PIPELINE 程序

此程序會刪除現有的資料管線。如果已啟動管線，則必須先將其停止，才能將它刪除。

語法

DBMS_CLOUD_PIPELINE.DROP_PIPELINE(
       pipeline_name        IN   VARCHAR2,
       force                IN   BOOLEAN DEFAULT FALSE
 );

參數

Parameter - 參數描述

Parameter - 參數	描述
`pipeline_name`	指定管線名稱。此為必要參數。
`force`	強制刪除管線，即使管線為已啟動狀態。有效值：`TRUE`、`FALSE` 預設值：`FALSE`

pipeline_name

指定管線名稱。

此為必要參數。

force

強制刪除管線，即使管線為已啟動狀態。

有效值：TRUE、FALSE

預設值：FALSE

使用備註

若要刪除處於已啟動狀態的管線，請將 force 參數設為 TRUE。

RESET_PIPELINE 程序

重設資料管線的追蹤狀態。使用重設管線從資料載入或匯出的初始狀態重新啟動管線。視管線類型而定，選擇性重設管線可以永久清除資料庫或物件存放區中的資料。資料管線必須為已停止狀態才能重設。

語法

DBMS_CLOUD_PIPELINE.RESET_PIPELINE(
       pipeline_name        IN   VARCHAR2,
       purge_data           IN   BOOLEAN DEFAULT FALSE
 );

參數

Parameter - 參數描述

Parameter - 參數	描述
`pipeline_name`	指定管線的名稱。此為必要參數。
`purge_data`	永久清除資料適用於載入管線或匯出管線：若為載入管線，當 `TRUE` 時，會截斷資料庫表格中的資料。若為匯出管線，當 `TRUE` 時，請刪除物件存放區位置中的檔案。有效值：`TRUE`、`FALSE` 預設值：`FALSE`

pipeline_name

指定管線的名稱。

此為必要參數。

purge_data

永久清除資料適用於載入管線或匯出管線：

若為載入管線，當 TRUE 時，會截斷資料庫表格中的資料。
若為匯出管線，當 TRUE 時，請刪除物件存放區位置中的檔案。

有效值：TRUE、FALSE

預設值：FALSE

使用注意事項

資料管線必須為已停止狀態才能重設。如需詳細資訊，請參閱STOP_PIPELINE 程序。
對於負載管線，重設管線會清除管線所載入檔案的記錄。當您在重設載入管線之後呼叫 START_PIPELINE 或 RUN_PIPELINE_ONCE 時，管線會重複資料載入，並包括物件存放區位置中的所有檔案。

當 purge_data 設為 TRUE 時，DBMS_CLOUD_PIPELINE.RESET_PIPELINE 會執行下列作業：
- 截斷使用 table_name 屬性指定之管線資料庫表格中的資料。
- 刪除管線的狀態表格，以及管線的錯誤檔案表格和錯誤表格 (如果存在)。
若為匯出管線，重設管線會清除資料庫表格中上次追蹤的資料。當您在重設匯出管線之後呼叫 START_PIPELINE 或 RUN_PIPELINE_ONCE 時，管線會重複從表格或查詢匯出資料。

當 purge_data 設為 TRUE 時，DBMS_CLOUD_PIPELINE.RESET_PIPELINE 會刪除物件存放區位置中以 location 屬性指定的現有檔案。

RUN_PIPELINE_ONCE 程序

此程序會在目前的前景階段作業中執行管線的隨選執行，而不是在排定的工作中執行。使用 DBMS_CLOUD_PIPELINE.RUN_PIPELINE_ONCE 以在將管線啟動為連續工作之前測試管線。

語法

DBMS_CLOUD_PIPELINE.RUN_PIPELINE_ONCE(
       pipeline_name  IN  VARCHAR2
);

參數

Parameter - 參數描述

Parameter - 參數	描述
`pipeline_name`	指定要執行的管線名稱。此為必要參數。

pipeline_name

指定要執行的管線名稱。

此為必要參數。

使用注意事項

執行管線的測試執行後，您可以使用 DBMS_CLOUD_PIPELINE.RESET_PIPELINE 重設管線狀態。這可讓您在排定的工作中啟動管線之前，重設管線狀態。
管線若為已啟動狀態，就無法在前景階段作業中執行。

SET_ATTRIBUTE 程序

此程序會設定管線屬性。有兩個超載程序，一個是設定單一屬性，另一個是使用屬性名稱 / 值組的 JSON 文件來設定多個屬性。

語法

PROCEDURE DBMS_CLOUD_PIPELINE.SET_ATTRIBUTE(
      pipeline_name        IN   VARCHAR2,
      attribute_name       IN   VARCHAR2,
      attribute_value      IN   CLOB
);
 
PROCEDURE DBMS_CLOUD_PIPELINE.SET_ATTRIBUTE(
      pipeline_name        IN   VARCHAR2,
      attributes           IN   CLOB
);

參數

Parameter - 參數	描述
`pipeline_name`	指定管線的名稱以設定屬性。此為必要參數。
`attribute_name`	指定要設定之屬性的屬性名稱。如需詳細資訊，請參閱 DBMS_CLOUD_PIPELINE 屬性。
`attribute_value`	指定要設定之管線屬性的值。如需詳細資訊，請參閱 DBMS_CLOUD_PIPELINE 屬性。
`attributes`	指定包含屬性名稱和值的 JSON 文件。如需詳細資訊，請參閱 DBMS_CLOUD_PIPELINE 屬性。

使用備註

當您使用 DBMS_CLOUD_PIPELINE.SET_ATTRIBUTE 以 attributes 參數設定多個屬性時，所有現有屬性都會被刪除並以 JSON 文件中的指定屬性覆寫。

START_PIPELINE 程序

程序會啟動資料管線。啟動管線時，管線作業會根據使用管線屬性設定的 interval，在排定的工作中持續執行。

語法

DBMS_CLOUD_PIPELINE.START_PIPELINE(
      pipeline_name        IN   VARCHAR2,
      start_date           IN   TIMESTAMP WITH TIME ZONE DEFAULT NULL
);

參數

Parameter - 參數描述

Parameter - 參數	描述
`pipeline_name`	指定管線的名稱。此為必要參數。
`start_date`	指定業務進程工作的開始日期。預設值：`NULL`

pipeline_name

指定管線的名稱。

此為必要參數。

start_date

指定業務進程工作的開始日期。

預設值：NULL

使用注意事項

依照預設，管線工作會在管線啟動後立即開始。若要在稍後啟動管線工作，請使用 start_date 參數指定有效的日期或時戳。
如需有關管線 interval 和其他管線屬性的資訊，請參閱 DBMS_CLOUD_PIPELINE 屬性。

STOP_PIPELINE 程序

此程序會停止資料管線。管線停止時，不會為管線排定任何未來的工作。

語法

DBMS_CLOUD_PIPELINE.STOP_PIPELINE(
      pipeline_name        IN   VARCHAR2,
      force                IN   BOOLEAN  DEFAULTFALSE
);

參數

Parameter - 參數描述

Parameter - 參數	描述
`pipeline_name`	指定管線的名稱。此為必要參數。
`force`	如果以 `TRUE` 方式傳送強制參數，則會終止管線的所有執行中工作。有效值：`TRUE, FALSE` 預設值：`FALSE`

pipeline_name

指定管線的名稱。

此為必要參數。

force

如果以 TRUE 方式傳送強制參數，則會終止管線的所有執行中工作。

有效值：TRUE, FALSE

預設值：FALSE

DBMS_CLOUD_PIPELINE 屬性

屬性可協助控制及設定資料管線的行為。

屬性

附註：

如業務進程類型資料欄中所示，視業務進程類型 LOAD 或 EXPORT 而定，業務進程支援一組不同的屬性。

屬性名稱	描述	管道類型	管線開始後可修改
`credential_name`	存取來源雲端物件儲存的證明資料名稱。預設值：`NULL`。如果您未提供 `credential_name`，則 `credential_name` 會設為 `NULL`。	`LOAD`, `EXPORT`	是
`field_list`	識別來源檔案中的欄位及其資料類型。此引數的語法與一般 Oracle 外部表格中的 `field_list` 子句相同。如需詳細資訊，請參閱 Oracle Database 19c Utilities 或 Oracle Database 23ai Utilities 中的 field_list 。預設值：`NULL` 預設值指定欄位及其資料類型是由 `table_name` 屬性中指定之表格的資料欄所決定。	`LOAD`	是
`format`	描述管線類型格式的選項。如需載入管線的資訊，請參閱 DBMS_CLOUD 套件格式選項。如需匯出管線，請參閱 EXPORT_DATA 的 DBMS_CLOUD 套件格式選項匯出管線不支援資料汲取 `format`。 `LOAD` 和 `EXPORT` 管線都必須要有此屬性。	`LOAD`, `EXPORT`	是
`interval`	排定之管線工作連續執行之間的時間間隔 (分鐘)。預設值：15 分鐘	`LOAD`, `EXPORT`	是
`key_column`	指定之 `table` 或 `query` 中的時戳或日期資料欄，用於持續將較新的資料匯出至物件存放區。「匯出」管線會追蹤上次執行時戳或日期，並與 `key_column` 中的值進行比較，以識別匯出至物件存放區的新資料。預設值：空值如果未指定匯出管線的 `key_column`，則 `table` 或 `query` 的整個內容會上傳至每個管線工作執行中的物件存放區。	`EXPORT`	編號
`location`	此參數指定來源檔案 URI、目錄以及來源檔案。您可以在檔案名稱中使用萬用字元。此參數為必要參數。雲端來源檔案 URI 您可以指定儲存桶或子資料夾的來源檔案 URI。您可以使用萬用字元來指定子資料夾或檔案名稱樣式。字元 "" 可以作為多個字元的萬用字元使用，而字元 "?" 可以用來作為單一字元的萬用字元。使用萬用字元的範例： `location_uri => 'https://objectstorage.my$region.oraclecloud.com/n/namespace-string/b/bucketname/o/year=????/month=??/.csv` URI 的格式取決於您使用的雲端物件儲存服務，如需詳細資訊，請參閱雲端物件儲存 URI 格式。目錄您可以指定一個目錄和檔案名稱。指定目錄的格式為 `'MY_DIR:filename.ext'`。依照預設，目錄名稱 `MY_DIR` 是資料庫物件，不區分大小寫。檔案名稱有大小寫之別。您只能使用萬用字元在目錄中指定檔案名稱。字元 `""` 可作為多個字元的萬用字元使用，而字元 `"?"` 則可用來作為單一字元的萬用字元。例如：`'MY_DIR:"` 或 `'MY_DIR:test?'` 使用雙引號來指定區分大小寫的目錄名稱。例如：`'"my_dir1":*, "my_dir2":Test?'` 若要包含引號字元，請使用兩個引號。例如：`'MY_DIR:''filename.ext'`。這會指定檔案名稱開頭為引號 `(')`。
`priority`	指定一個字串值，決定對管線執行的平行作業數目。在載入管線中，它會決定平行載入的檔案數目。在匯出管線中，它會決定從資料庫擷取資料的平行程度。優先順序較高的作業會耗用更多的資料庫資源，且會較快完成。以下為其有效值： `HIGH`：決定使用資料庫的 ECPU 數目處理的平行檔案數目 (如果您的資料庫使用 OCPU，則為 OCPU 數目 ) 。 `MEDIUM`：使用「中」服務的並行限制來決定同時處理的數目。預設值是 4。 `LOW`：依序執行管線工作。預設值：`MEDIUM` 並行檔案作業的數目上限為 64。	`LOAD`, `EXPORT`	是
`query`	指定 `SELECT` 敘述句，只匯出必要的資料。此查詢會決定您匯出為文字檔 ( CSV、JSON、Parquet 或 XML) 或傾印檔的檔案內容。舉例而言： `SELECT warehouse_id, quantity FROM inventories` 預設值：`NULL` 對於匯出管線，必須要有 `table_name` 或 `query`。	`EXPORT`	編號
`table_name`	指定用於載入或匯出資料的目標表格名稱。必須輸入負載管線 `table_name`。對於匯出管線，必須要有 `table_name` 或 `query`。	`LOAD`, `EXPORT`	編號
`table_owner`	目標表格所在的綱要名稱，用於載入或匯出資料。預設值：`NULL` 使用 `NULL` 值時，目標表格與執行程序的使用者位於相同的綱要中。	`LOAD`, `EXPORT`	編號