ADD EXTRACT

適用於支援的 Db2、HP NonStop、MySQL、Oracle、PostgreSQL、SQL Server、Sybase ASE 和 Yugabyte 資料庫。

使用 ADD EXTRACT 來建立來源資料庫擷取處理作業，稱為 Extract。您可將 Extract 建立為變更資料 Extract，從資料庫日誌或透過其他方式 (依資料庫廠商而定) 擷取目前的異動，也可以建立為起始載入 Extract，擷取存在於資料庫表格中的記錄。

建議每個來源資料庫只建立一個變更資料或一個起始載入 Extract，不過在極少數的情況下，每個資料庫使用多個 Extract 可提升擷取傳輸量。

視作業系統的可用資源多寡而定，Oracle GoldenGate 可對每個部署支援大量的並行 Extract 及 Replicat 處理作業。不過，建議在新增更多 Extract 或 Replicat 處理作業時監督系統資源，將每個部署的處理作業總數維持在不超過 300 個。

備註：

如果您正在建立與舊 Extract 相同名稱的 Extract，請確定已完全移除並刪除舊的 Extract。您可以使用 DELETE EXTRACT 來移除 EXTRACT 及其所有元件。
所有關鍵字和輸入的這個命令大小不能超過 500 個位元組，包括您為 DESC 選項輸入的任何文字。
對於 Db2 for i，此命令的第一個必要步驟是先為所有日記帳建立一個全域的起始點。在發出 ADD EXTRACT 指令之後，您可以使用 ALTER EXTRACT 指令搭配適當的分錄選項，選擇性地將任何給定的分錄放置在特定的分錄序號。
對於 Oracle 和 PostgreSQL 資料庫，請使用 DBLOGIN USERIDALIAS 建立與來源資料庫的連線，然後在新增 Extract 之前發出 REGISTER EXTRACT 命令。如需詳細資訊，請參閱 REGISTER EXTRACT 指令。
若為 SQL Server，請在新增 Extract 之前，先使用 DBLOGIN USERIDALIAS 建立來源資料庫連線。這對「管理服務」使用 Extract 處理作業連結證明資料資訊而言是必要的。

語法

ADD EXTRACT extract-name
|             { SOURCEISTABLE |
|              [ INTEGRATED ] TRANLOG
|               {, BEGIN     [ NOW | yyyy-mm-ddThh:mm.ssZ | LSN value | EOL | EOF | EXTRBA archive-offset-number |  SCN  scn }
|               [, DESC        description    ]
|               [, CRITICAL    [ YES | NO ]     ]
|               [, ENCRYPTIONPROFILE     encryption-profile-name]
|               [, GTIDSET gtidset
|               [, PROFILE
|                 [ AUTOSTART   [ YES | NO ]
|                       [ DELAY     delay-number   ] ]
|                 [ AUTORESTART [ YES | NO ]
|                       [ RETRIES          retries-number ]
|                       [ WAITSECONDS      wait-number    ]
|                       [ RESETSECONDS     reset-number   ]
|                       [ DISABLEONFAILURE [ YES | NO ] ] ] ]
|               [ LOGNUM lognum]
|               [ LOGPOS logpos]

extract_name

Extract 的名稱。最多可包含 8 個字元，請參閱選擇處理和檔案的名稱。

SOURCEISTABLE

建立 Extract 作業，以使用 Oracle GoldenGate 從起始載入的指定表格擷取完整記錄。使用 SOURCEISTABLE 時，請勿指定任何服務選項。

必須在參數檔中指定工作參數，請參閱 Oracle GoldenGate Microservices Documentation 中的使用管理從屬端新增起始載入擷取。

TRANLOG [bsds_name]

此選項適用於所有資料庫。TRANLOG 需要 BEGIN 選項。

(z/OS 上的 Db2) 您可以在 z/OS 系統上的 Db2 使用 bsds_name 選項，指定交易記錄的「啟動安裝資料集」檔案名稱 (雖然不需要，但未使用)。您不需要變更現有的 TRANLOG 參數。

(Oracle) Extract 會直接讀取 Oracle 重做日誌。請參閱 INTEGRATED TRANLOG 以取得替代組態。

INTEGRATED TRANLOG

適用於 Oracle。

以整合式擷取模式新增 Extract。在此模式下，Extract 與資料庫日誌探勘伺服器整合，因此邏輯變更記錄 (LCR) 會直接傳送至 Extract。使用 INTEGRATED TRANLOG 之前，請先使用 REGISTER EXTRACT 指令。

BEGIN {NOW yyyy-mm-ddthh:mm.ssZ}

指定資料來源中用來開始處理的時戳。

注意：您必須先註冊 Extract，才能將 Extract 定位至特定時戳。

NOW

NOW 指定 ADD EXTRACT 命令的發行時間，以及 Extract 啟動的時間，會嘗試定位至該特定時間或之後的交易界限。依 NOW 定位 Extract 與其他方法 (例如定位 LSN、SCN 或 LRI) 不相同，而且需要將資料庫伺服器和 Oracle GoldenGate 伺服器設為相同的時間和時區。

若為 Db2 LUW，只有確認及結束異動記錄包含時戳，因此只能計算出與這些時戳相對的 Extract 開始位置。這是 Oracle GoldenGate 所使用的 API 限制。請注意，依時戳定位並不準確，而且耗費的時間可能也很長。建議儘可能使用 LRI 或 EOL 選項。
yyyy-mm-ddthh:mm.ssZ

以指定格式表示的日期與時間 (時戳)。例如，2017-07-14T14:54:45Z。
yyyy-mm-ddT[ hh:mi:[ss[.cccccc]]]Z

以指定格式表示的日期與時間 (時戳)。針對 Oracle Extract 和適用於 PostgreSQL 的 Extract，此時戳值必須大於向資料庫註冊 Extract 的時戳。

在 PostgreSQL 中依時戳定位包括下列情況：
- 案例 1
  
  如果 track_commit_timestamp 是 off，則不論使用何種定位方法，當 Extract 處理作業啟動時，將會顯示下列輸出：
```
2020-04-29T02:15:54Z
```
- 案例 2
  
  如果在註冊 Extract 之前啟用 track_commit_timestamp，則在來源資料庫中植入記錄後，將會顯示正確的時間戳記，如下列範例所述：
```
2020-04-29 02:19:07 INFO OGG-01515 Positioning to begin time Apr 29,2020 2:18:38 AM.
```
- 案例 3
  
  如果在註冊 Extract 之後啟用 track_commit_timestamp，則可能會有較舊的記錄存在於日誌中，而日誌中未使用關聯的 transaction ID 建立確認時戳。在此情況下，如果 Extract 未取得時戳，則會改用情況 1 中提及的預設時戳。輸出與下列類似：
```
020-04-29 01:55:07 INFO OGG-01517 Position of first record processed LSN: 0/221D028, Jan 1, 1970 12:00:00 PM.
```
- 如果複製插槽已移到別處，則無法指定過去時戳。

EXTRBA archive-offset_number

適用於 Db2 z/OS。

指定異動日誌內用來開始擷取資料的相對位元組位址。

必要格式為 0Xnnn，其中 nnn 是 1 到 20 位數十六進位數字 (第一個字元是數字零，第二個字元可以是大寫或小寫的字元 x)。

EOL

適用於 Db2 for i、Db2 LUW、MySQL、PostgreSQL 及 SQL Server。

將處理作業設定在日誌檔 (或日記帳) 結尾處開始，也就是寫入下一筆記錄的位置。將不會擷取任何作用中的異動。

對於 Db2 LUW，它會設定處理從日誌檔中的作用中 LRI 值開始。作用中的 LRI 是將寫入下一筆記錄之日誌檔結尾的位置。將不會擷取任何作用中的異動。

對於 PostgreSQL，EOL 需有 DBLOGIN 才能定位。

若為 MySQL，它會尋找與檔案結尾相對應的位置，然後從那裡開始讀取異動。若持續將資料寫入二進位日誌，EOL 位置就會不精確。

EOF

適用於 MySQL、Db2 z/OS、Db2 LUW、SQL Server、PostgreSQL、Oracle GoldenGate for DAA。

LSN value

適用於 Db2 z/OS、PostgreSQL 及 SQL Server。

指定開始擷取資料的交易 LSN。此選項的別名為 EXTLSN。精確定位至 LSN。

對於 Db2 z/OS，LSN 值可以是一系列十六進位數字或一系列十進位數字。如果是十六進位格式，則前面必須加上 0X 或 0x，後面接著 1 到 20 個十六進位數字：0-9、a-g 或 A-G。如果是十進位格式，則沒有前置碼，並且使用 1-25 位十進位數字：0-9。

PostgreSQL 的 LSN 值可以是 hi 或 lo。將日誌檔進入點的值設為 hi。Lo 是日誌檔中的位移。LSN 位置應該位於複製插槽重新啟動位置與寫入日誌目前位置之間。如果指定的位置本身就在所提及的範圍內，則 Extract 將會發出錯誤。

若為 SQL Server，LSN 會指定開始擷取資料的交易 LSN。此選項的別名為 EXTLSN。

指定的 LSN 應存在為在 cdc.lsn_time_mapping 系統表格中找到的有效 tran_begin_lsn，否則 Extract 將嘗試定位在提供的 LSN 的值之後。

SQL Server 的有效 LSN 規格包含下列項目：

以冒號區隔的十六進位字串 (8:8:4)，使用前置零與 0X前置碼填補，例如 0X00000d7e:0000036b:0001
以冒號區隔的十六進位字串，使用 0X 前置碼但不使用前置零，例如 0Xd7e:36b:1

您可以查詢下列範例以尋找可用的最小 LSN：

SELECT min([tran_begin_lsn]) FROM [cdc].[lsn_time_mapping] with (nolock) where tran_id <> 0x00

下列範例顯示 Db2 z/OS LSN 值的用法：

範例 1：

ADD EXTRACT extn TRANLOG, LSN 0xDEE40E4F27A3245400

範例 2：

ADD EXTRACT extn TRANLOG, LSN 22216433159121980904448

下列範例顯示 SQL Server 的 LSN 值：

ADD EXTRACT extn TRANLOG, LSN 0X00000d7e:0000036b:0001

LRI value

適用於 Db2 LUW。指定 Extract 在異動日誌中的開始位置。

您可以使用 Db2 LUW 系統的 LRI 選項來指定 LRI，讓 Extract 可以開始從交易日誌擷取記錄。您可以使用 Db2 公用程式 db2logsForRfwd 來取得 LRI (時的)。此公用程式提供 Db2 日誌中存在的 LRI 範圍。

請注意，雖然 Extract 可以定位至指定的 LRI，但 LRI 可能不一定是 Extract 將處理的第一個項目。日誌檔中有許多 Extract 忽略的記錄類型，例如 Db2 內部日誌記錄。Extract 會將實際開始的 LRI 報告至 Extract 報表檔案。

LOGNUM lognum

適用於 MySQL。

這是日誌檔編號。如果 LOGNUM 值在值前面包含零，ADD EXTRACT 就會失敗。例如，ADD EXTRACT ext1, TRANLOG, LOGNUM 000001, LOGPOS 0 會失敗。請改為將 LOGNUM 設為 1，以便讓此範例成功。

LOGPOS logpos

這是日誌檔中的事件偏移值，用於識別特定的異動記錄。事件偏移值儲存在日誌記錄的標頭區段中。若要在 binlog 檔案的開頭進行定位，請將 LOGPOS 設為 0。

SEQNO sequence_number

適用於 Db2 for i。從某個系統序號或之後開始擷取，序號為長度在 20 個位數內的十進位數字。

SCN value

適用於 Oracle。

在重做日誌中具有指定 Oracle 系統變更編號 (SCN) 的異動啟動 Extract。針對整合式模式的 Extract，此 SCN 值必須大於向資料庫註冊 Extract 的 SCN。如需更多資訊，請參閱 REGISTER EXTRACT 。

PARAMS file_name

指定 Extract 參數檔在 Oracle GoldenGate 目錄內預設為 dirprm 之外的位置的完整路徑名稱。

REPORT file_name

指定 Extract 報表檔案在 Oracle GoldenGate 目錄內預設為 dirrpt 之外的位置的完整路徑名稱。

DESC ‘description’

指定群組的說明，例如 'Extracts account_tab on Serv1'。以單引號括住描述。

ENCRYPTIONPROFILE

指定與特定從屬端關聯的 Oracle GoldenGate 加密設定檔名稱。

GTIDSET gtidset

適用於 MySQL。

使用 MySQL GTID 式擷取的定位類型作為 GTID 集，指定 Extract 的起始定位。GTID 集支援的 MySQL 來源為 MySQL Server 8.0 和更新版本。支援的 GTID 集大小上限為 64 KB。

語法：

ADD EXTRACT extract_name, TRANLOG, GTIDSET gtidset

CRITICAL

指示處理作業對於部署是否至關重要。

PROFILE

自動啟動設定檔的名稱。

AUTOSTART

指定受管理的處理作業是否要在管理服務啟動時自動啟動。預設值為 YES。

DELAY

啟動處理作業前應等待的時間 (秒)。

AUTORESTART

控制處理作業若終止時的重新啟動方式。

RETRIES

作業取消重試前應重新啟動的次數上限。這是選擇性選項。

WAITSECONDS

計算重試次數的持續時間 (秒)。

RESETSECONDS

重設計算重試次數的持續時間。

DISABLEONFAILURE

如果設為 TRUE，則重試次數用完時會停用工作。

SOCKSPROXY {host_name IP_address}[:port] [PROXYCSALIAS credential_store_alias [PROXYCSDOMAIN credential_store_domain]

用於別名 Extract。指定代理主機伺服器的 DNS 主機名稱或 IP 位址。您可使用任何一項來定義主機，但若無法連線 DNS 伺服器，則必須使用 IP 位址。如果使用 IP 位址，請依照目的地系統的堆疊，使用 IPv6 或 IPv4 對應位址。您必須指定 PROXYCSALIAS。此外，您可以指定要使用的連接埠，以及證明資料存放區網域。

範例

下列範例會建立一個名為 exte 的 Extract 群組，從交易日誌擷取資料庫變更。擷取會在 Extract 群組建立並啟動 ADD EXTRACT 時，從產生的記錄開始。

ADD EXTRACT extn, TRANLOG, BEGIN NOW

在下列範例中，會建立 Extract 群組名稱 extw，透過將 Extract 定位至特定時戳，從交易日誌取得資料庫變更：

ADD EXTRACT extn, TRANLOG, BEGIN NOW

REGISTER EXTRACT extn DATABASE

ALTER EXTRACT extn BEGIN 2020-08-02T06:05:30.000Z

下列範例建立整合式 Extract 群組。

ADD EXTRACT extn, INTEGRATED TRANLOG, BEGIN NOW

下列範例會建立名為 extei 的初始載入 Extract。

ADD EXTRACT extn, SOURCEISTABLE

下列範例包括 GTID 集有效格式的所有組合。

範例 1：

ADD EXTRACT exte, TRANLOG, GTIDSET "E11FA47-71CA-11E1-9E33-C80AA9429562:4"

範例 2：

ADD EXTRACT exts, TRANLOG, GTIDSET "3E11FA47-71CA-11E1-9E33-C80AA9429562:1-10"

範例 3：

ADD EXTRACT extn, TRANLOG, GTIDSET "3E11FA47-71CA-11E1-9E33-C80AA9429562:1-3:11:47-49"

範例 4：

ADD EXTRACT extw, TRANLOG, GTIDSET "2174B383-5441-11E8-B90A-C80AA9429562:1-3,24DA167-0C0C-11E8-8442-00059A3C7B00:1-19"

備註：如範例 4 所示，當 GTID 集包含多個 UUID 時，為了形成 REST API 要求，此 GTID 集會使用逗號分隔符號細分為多個 GTID 集。

下列範例建立 Extract 並將其定位在重做日誌中的特定 Oracle 系統變更編號 (SCN)。

ADD EXTRACT extn TRANLOG SCN 123456

ADD EXTRACT extn INTEGRATED TRANLOG SCN 123456

下列範例在 Db2 LUW 系統上建立 Extract。

ADD EXTRACT extn, TRANLOG LRI 8066.322711

下列範例使用「管理從屬端」，以自動啟動選項建立 Extract。

ADD EXTRACT extn, TRANLOG , BEGIN NOW , AUTOSTART yes