建立及管理資料串流

從使用者介面建立資料串流

從左側導覽窗格中，選取資料串流以開啟「資料串流」頁面。
按一下新增資料串流按鈕。將會顯示「新增資料流」對角線方塊。
在資料流資訊頁面上，在名稱方塊中輸入唯一的資源名稱。

名稱必須介於 1 到 32 個字元。以字母為開頭。檢查點的作用領域為串流合約，因此請使用穩定的名稱。按下一步。
新增業務擁有者、來源歷程檔、表格、用戶以及復原目標的描述。
在來源選項頁面上，提供下列影像中所顯示之選項的值：
- 歷程檔名稱：來源歷程檔的名稱。歷程檔名稱必須是識別服務接受之來源歷程檔前置碼或來源端點的兩個字元。
- 歷程檔子目錄：儲存歷程檔的子目錄路徑。當來源歷程檔不在預設位置時，此目錄位於儲存來源歷程檔的 GoldenGate 建置底下。
- 編碼：此選項會控制資料串流的記錄編碼。目前支援 JSON 編碼。使用 YAML 編輯器或 REST 組態設定進階 JSON 選項。
- 緩衝區大小：此值控制資料串流服務中使用的記憶體緩衝區大小。資料串流處理服務會在記憶體內訊息佇列的總位元組大小超過指定的值後清除佇列，並將記錄傳遞給從屬端。範圍 131,072 至 10,485,760；預設值為 1,048,576。這不是持久的保留。
- 服務品質：此選項會定義資料串流重複隱藏與復原行為。exactlyOnce、atLeastOnce 或 atMostOnce。
  
  在選取非預設值之前，請參閱檢查點、復原及傳遞語意。
  
  資料串流服務支援三種層次的服務品質：
  - 精確一次：此模式是最具限制性的模式，服務會在復原來源歷程檔中的 RESTART OK/ABEND 記錄時篩選出任何重複的記錄。客戶看不到重複的記錄。如果服務找不到指定最後處理職位的記錄，就會發生錯誤。
  - 至少一次：此模式不會在復原期間隱藏重複的記錄，或是在來源歷程檔中查看 RESTART OK/ABEND 記錄。客戶可能會在資料串流中看到重複的記錄。此外，如果服務找不到指定最後處理職位的記錄，就會發生錯誤。
  - 最多一次：此模式會在復原期間隱藏重複的記錄，或查看來源歷程檔中的 RESTART OK/ABEND 記錄。從屬端在資料串流中看不到重複的記錄。如果服務找不到具有指定最後處理職位的記錄，就會找到下一個可用記錄並向前移動。
- CloudEvents 格式：資料串流服務支援以 CloudEvents 格式傳輸資料記錄。它會包裹 CloudEvents JSON 中的 GoldenGate 記錄。預設會停用此選項。建立資料串流通道時，預設會停用此格式，而且可以使用切換開關啟用特性來控制此格式。
在篩選選項頁面上，可以使用包含和排除篩選規則的選項，如下圖所示：

指定篩選規則選項，如下所示：
- 規則動作：選取「排除」或「包含」選項。
- 篩選類型：篩選類型包含下列項目：
  
  物件類型：您可以從下拉式清單中選取多個選項，包括 DML 、 DDL 、 INSERT 、 UPDATE 、 UPSERT 、 DELETE 。
  
  物件名稱：先前建立之篩選物件的名稱。

按一下新增，即可將篩選規則新增至「資料串流」處理作業。

按一下建立資料串流。您將會返回列出「資料流」的「分送服務」首頁。
按一下建立的資料流，以檢視串流的 YAML 文件資料流 AsyncAPI 定義。

從使用者介面編輯資料串流組態

若要編輯「資料串流」組態：

從左側導覽窗格中，按一下「資料串流」。
選取需要修改的資料串流名稱。
在「資料串流」頁面中，使用動作資料欄來檢視資料串流詳細資訊、刪除資料串流，以及變更其篩選。
如果您按一下動作功能表中的變更篩選選項，就會顯示編輯資料串流篩選規則對話方塊。您可以從此方塊變更規則動作 (包括、排除) 和篩選類型 (物件名稱或物件類型)。
按一下新增以套用篩選。
按一下送出，即可傳回「資料串流」頁面。

您可以從名稱資料欄按一下資料串流，進一步編輯資料串流。這會顯示完整的資料串流組態。使用每個組態設定旁邊的鉛筆圖示來變更它。您可以變更資料串流所使用的來源歷程檔、篩選規則以及服務品質。您也可以使用 YAML 編輯器，使用「YAML 編輯器」旁邊的上傳變更圖示來變更資料串流組態及上傳變更。

使用 REST API 建立資料串流

使用 POST /services/v2/stream/{streamName} 與管理員帳戶。最小的要求會識別來源歷程檔：

{
  "$schema": "ogg:dataStream",
  "source": {
    "trail": "ea",
    "path": "./dirdat"
  }
}

生產要求通常會明確設定服務品質、篩選條件、JSON 綱要排放、描述資料欄位及大小控制項。支援檔案 data_stream_create_request.json 包含完整的處理範例。

{
  "$schema": "ogg:dataStream",
  "description": "Streams sales order changes",
  "source": {"trail": "ea", "path": "./dirdat"},
  "qualityOfService": "exactlyOnce",
  "bufferSize": 1048576,
  "tcpKeepAliveTimeout": 120,
  "cloudEventsFormat": false,
  "rules": [
    {
      "action": "include",
      "filter": {"objectNames": ["SALES.ORDERS", "SALES.ORDER_ITEMS"]}
    }
  ],
  "encoding": {
    "json": {
      "$schema": "ogg:outputFormatJson",
      "model": "op",
      "includeJSONSchemaRecord": true,
      "includeObjectMetadataRecords": true,
      "includeStreamMetadataRecord": true,
      "metaFields": {
        "qualifiedTable": true,
        "opType": true,
        "opTs": true,
        "pos": true,
        "xid": true,
        "csn": "csn",
        "opSeqno": "op_seqno",
        "transInd": "trans_ind"
      }
    }
  }
}

最上層組態特性

下表提供用來設定串流的組態特性。

財產	類型 / 預設	說明
`$schema`	字串 / `ogg:dataStream`	組態綱要 ID。
`source`	物件 / 必要	來源歷程檔和選擇性路徑。
`description`	字串 / 無	描述資料流的 1 到 4,096 個字元。
`qualityOfService`	列舉 / `exactlyOnce`	`atLeastOnce`、`exactlyOnce` 或 `atMostOnce`。
`bufferSize`	整數 / 1,048,576	排清臨界值 (位元組)。最小值為 131,072；最大值為 10,485,760。
`tcpKeepAliveTimeout`	整數 / 120	TCP 持續作用逾時 (秒)。最小值 1，最大值 10,800。
`cloudEventsFormat`	布林 / `false`	啟用 CloudEvents JSON 信封。
`rules`	陣列 / 無	1 至 1,024 包含或不包含規則。
`encoding`	字串或物件 / `json`	使用 `"json"` 作為預設值，使用 `{"json": {...}}` 作為進階輸出設定值。

擷取、更新、列出及刪除資料串流

使用下表來管理或刪除資料流：

任務	方法與路徑	角色
列出串流	`GET /services/v2/stream`	使用者
取得組態	`GET /services/v2/stream/{streamName}`	運算子
取得產生的 YAML	`GET /services/v2/stream/{streamName}/yaml`	使用者
更新組態	`PATCH /services/v2/stream/{streamName}`	管理員
更新 YAML	`PATCH /services/v2/stream/{streamName}/yaml`	管理員
刪除串流	`DELETE /services/v2/stream/{streamName}`	管理員

注意：變更欄位名稱、作業字串、記錄模型、篩選或結構描述排放會變更用戶合約。在生產推出之前，協調變更、啟動合約的版本，以及從現有檢查點重新啟動測試。

使用產生的 YAML 作為已部署的合約

產生的 YAML 包括部署特定伺服器、通道位址、begin 查詢參數、訊息有效負載和支援的記錄綱要。建立後並在每次組態變更後擷取。將已複查的副本儲存至用戶版本，但一律在部署驗證期間將其與執行時期版本進行比較。