Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

使用 Datastream API

Datastream

Datastream REST API 可讓您透過程式輔助方式，將地端部署和雲端來源的變更資料複製到 Google Cloud 目的地，以便進行近乎即時的分析。在本教學課程中，您將建立連線設定檔和串流，將 Oracle 結構定義、資料表和資料複製到 Cloud Storage bucket。在複製期間，Datastream 會將來源記錄轉換為具有 JSON 結構定義的 Avro 檔案，讓下游應用程式能以統一的方式讀取各來源的資料。

目標

在本教學課程中，您將瞭解以下內容：

設定環境變數。向 Datastream 提出要求，建立及管理連線設定檔和串流時，會用到這些變數。
為來源資料庫和 Cloud Storage 中的目的地 bucket 建立及管理連線設定檔。建立這些連線設定檔，即代表您建立的記錄包含來源資料庫和目的地 Cloud Storage bucket 的資訊。Datastream 中的串流會使用連線設定檔中的資訊，將資料從來源資料庫轉移至目的地 bucket 中的資料夾。
建立及管理串流。Datastream 會使用這個串流，將資料、結構定義和資料表從來源資料庫轉移至目的地 bucket 中的資料夾。
確認 Datastream 將與來源 Oracle 資料庫結構定義相關聯的資料和資料表，轉移至目的地 bucket 中的資料夾，並將這些資料轉譯為 Avro 檔案格式。
清理在 Datastream 建立的資源，以免占用配額，並避免日後產生費用。

費用

在本文件中，您會使用下列 Google Cloud計費元件：

Cloud Storage

您可以使用 Pricing Calculator，根據預測用量估算費用。

初次使用 Google Cloud 的使用者可能符合免費試用期資格。

事前準備

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
- Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.
Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector
Verify that billing is enabled for your Google Cloud project.
啟用 Datastream API。
啟用 API
確認您的使用者帳戶具備 Datastream 管理員角色。
前往「IAM」頁面
請確認您有 Datastream 可存取的來源資料庫。在本教學課程中，Oracle 資料庫會做為來源。
將來源資料庫設為接受從 Datastream 公開 IP 位址傳出的連入連線。如要查看所有 Datastream 區域的位置和相關聯的公開 IP 位址，請參閱「IP 許可清單和區域」。
請務必設定目的地 Cloud Storage bucket，讓 Datastream 能透過 IP 許可清單、轉送 SSH 通道或虛擬私有雲對接網路連線方法存取。
確認來源資料庫中有資料、資料表和結構定義，可供 Datastream 移轉至目的地 Cloud Storage bucket 中的資料夾。
下載並安裝 Cloud Shell。這個用戶端應用程式可讓您透過指令列存取雲端資源 (包括 Datastream)。
安裝及設定 jq 公用程式。這項公用程式是輕量且靈活的指令列 JSON 處理器。您將使用這個處理器，以易於閱讀的文字顯示複雜的 cURL 指令。

設定環境變數

在這個程序中，您將設定下列變數：

$PROJECT：這個變數與您的 Google Cloud 專案相關聯。您分配和使用的所有Google Cloud 資源，都必須位於專案中。
$TOKEN：這個變數與存取權杖相關聯。存取權杖會提供工作階段，Cloud Shell 會使用該工作階段，透過 REST API 在 Datastream 中執行工作。

啟動 Cloud Shell 應用程式。
使用 Google 帳戶驗證應用程式後，請輸入下列指令：
```
gcloud auth login
```
在 Do you want to continue (Y/n)? 提示中輸入 Y。
開啟網路瀏覽器，然後將網址複製到瀏覽器中。
使用 Google 帳戶向 Google Cloud SDK 進行驗證。「登入」頁面會顯示一組代碼。這組代碼就是您的存取權杖。
複製存取權杖，貼到 Cloud Shell 應用程式的 Enter verification code: 參數，然後按下 Enter。
在提示中輸入 PROJECT=\"YOUR_PROJECT_NAME\"，將 $PROJECT 環境變數設為 Google Cloud專案。
在提示中輸入 gcloud config set project YOUR_PROJECT_NAME，將要處理的專案設為 Google Cloud專案。

命令提示字元會更新，反映您目前使用的專案，並採用以下格式：USERNAME@cloudshell:~ (YOUR_PROJECT_NAME)$
在提示中輸入 TOKEN=$(gcloud auth print-access-token)，擷取存取權杖並儲存為變數。
在提示中輸入下列指令，確保 $PROJECT 和 $TOKEN 變數設定正確：
- echo $PROJECT
- echo $TOKEN

設定變數後，即可向 Datastream 提出要求，建立及管理連線設定檔和串流。

建立及管理連線設定檔

在本節中，您將為來源 Oracle 資料庫和 Cloud Storage 中的目的地 bucket 建立及管理連線設定檔。

建立這些連線設定檔時，您會建立記錄，其中包含來源資料庫和目的地 Cloud Storage bucket 的資訊。Datastream 會使用連線設定檔中的資訊，將來源資料庫中的資料移轉至目的地 bucket 中的資料夾。

建立及管理連線設定檔，包括：

為來源 Oracle 資料庫和 Cloud Storage 中的目的地 bucket 建立連線設定檔
擷取連線設定檔的相關資訊
修改連線設定檔
對來源 Oracle 連線設定檔執行探索 API 呼叫。這項呼叫可讓您查看資料庫內部，瞭解與其相關聯的物件。這些物件包括含有資料庫資料的結構定義和資料表。使用 Datastream 設定串流時，您可能不想從資料庫提取所有物件，而是提取部分物件 (例如僅限資料庫的特定資料表和結構定義)。使用 Discover API 找出 (或探索) 要提取的資料庫物件子集。

建立連線設定檔

在這個程序中，您會建立兩個連線設定檔：一個連至來源 Oracle 資料庫，另一個連至 Cloud Storage 中的目的地 bucket。

建立來源 Oracle 資料庫的連線設定檔。在提示中輸入下列指令：

ORACLE="{\"displayName\":\"DISPLAY_NAME\",\"oracle_profile\":{\"hostname\":\"HOSTNAME\",\"username\":\"USERNAME\",\"password\":\"PASSWORD\",\"database_service\":\"DATABASE_SERVICE\",\"port\":"PORT_NUMBER\"},\"no_connectivity\":{}}"

請參閱下表，瞭解來源 Oracle 資料庫的參數值：

參數值	取代憑證
`DISPLAY_NAME`	來源資料庫連線設定檔的顯示名稱。
`HOSTNAME`	來源資料庫伺服器的主機名稱。
`USERNAME`	來源資料庫帳戶的使用者名稱 (例如 `ROOT`)。
`PASSWORD`	來源資料庫帳戶的密碼。
`DATABASE_SERVICE`	這項服務可確保來源資料庫受到保護及監控。如果是 Oracle 資料庫，資料庫服務通常是 `ORCL`。
`PORT_NUMBER`	為來源資料庫保留的通訊埠編號。Oracle 資料庫的通訊埠編號通常是 1521。

注意： 在本教學課程中，您已將來源 Oracle 資料庫設為允許來自 Datastream 公開 IP 位址的連入連線，因此會使用no_connectivity網路連線方式。除了no_connectivity，您還可以使用兩種支援的網路連線方法，在來源資料庫和目的地 Cloud Storage bucket 中的資料夾之間建立連線。

IP 許可清單：這個方法會設定來源資料庫，接受來自 Datastream 公開 IP 位址的連線。如果使用 IP 許可清單做為網路連線方式，請將 no_connectivity 替換為 StaticIpConnectivity。
轉送 SSH 通道：這個方法會透過安全的 SSH 通道，建立來源資料庫與 Datastream 之間的連線。如果您使用轉送 SSH 通道做為網路連線方式，請將 no_connectivity 替換為 forwardSshTunnelConnectivity。如要瞭解可為這個網路連線方法設定的值，請參閱參考文件。

在提示中輸入 echo $ORACLE | jq 指令，以易於閱讀的文字查看您建立的來源連線設定檔。

{
  "displayName": "DISPLAY_NAME",
  "oracle_profile": {
    "hostname": "HOSTNAME",
    "username": "USERNAME",
    "password": "PASSWORD",
    "database_service": "DATABASE_SERVICE",
    "port": PORT_NUMBER
   },
  "no_connectivity": {}
}

提交 Oracle 連線設定檔，以便建立設定檔。在提示中輸入下列指令：

curl -X POST -d $ORACLE -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" https://datastream.googleapis.com/DATASTREAM_API_VERSION/PROJECT_PATH/connectionProfiles?connection_profile_id=SOURCE_CONNECTION_PROFILE_ID

請參閱下表，瞭解這個指令的參數值：

參數值	取代憑證
`DATASTREAM_API_VERSION`	Datastream API 的目前版本 (例如 `v1`)。
`PROJECT_PATH`	Google Cloud 專案的完整路徑 (例如 `projects/$PROJECT/locations/YOUR_PROJECT_LOCATION`)。
`SOURCE_CONNECTION_PROFILE_ID`	這個連線設定檔的專屬 ID (例如 `cp-1`)。

確認您看到下列程式碼：

{
  "name": "PROJECT_PATH/operations/operation-SOURCE_CONNECTION_PROFILE_OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.datastream.DATASTREAM_API_VERSION.OperationMetadata",
    "createTime": "DATE_AND_TIME_STAMP",
    "target": "datastream.googleapis.com/DATASREAM_VERSION/PROJECT_PATH/connectionProfiles/SOURCE_CONNECTION_PROFILE_ID",
    "verb": "create",
    "requestedCancellation": false,
    "apiVersion": "DATASTREAM_API_VERSION"
  },
  "done": false
}

建立連線設定檔，連結至 Cloud Storage 中的目的地 bucket。在提示中輸入下列指令：

GOOGLECLOUDSTORAGE="{\"displayName\":\"DISPLAY_NAME\",\"gcs_profile\":{\"bucket\":\"BUCKET_NAME\",\"root_path\":\"/FOLDER_PATH\"},\"no_connectivity\":{}}"

請參閱下表，瞭解目的地 bucket 的參數值：

參數值	取代憑證
`DISPLAY_NAME`	目的地 bucket 連線設定檔的顯示名稱。
`BUCKET_NAME`	目的地 bucket 的名稱。
`FOLDER_PATH`	目的地 bucket 中的資料夾，Datastream 會將來源資料庫中的資料移轉至該資料夾 (例如 `/root/path`)。

在提示中輸入 echo $GOOGLECLOUDSTORAGE | jq 指令，以易於閱讀的文字查看您建立的目的地連線設定檔。

{
  "displayName": "DISPLAY_NAME",
  "gcs_profile": {
    "bucket": "BUCKET_NAME",
    "root_path": "/FOLDER_PATH"
  },
  "no_connectivity": {}
}

提交 Cloud Storage 連線設定檔，以便建立。在提示中輸入下列指令：

curl -X POST -d $GOOGLECLOUDSTORAGE -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" https://datastream.googleapis.com/DATASTREAM_API_VERSION/PROJECT_PATH/connectionProfiles?connection_profile_id=DESTINATION_CONNECTION_PROFILE_ID

確認您看到下列程式碼：

{
  "name": "PROJECT_PATH/operations/operation-DESTINATION_CONNECTION_PROFILE_OPERATION_ID",
  "metadata": {
    "@type": "@type": "type.googleapis.com/google.cloud.datastream.DATASTREAM_API_VERSION.OperationMetadata",
    "createTime": "DATE_AND_TIME_STAMP",
    "target": "datastream.googleapis.com/DATASTREAM_VERSION/PROJECT_PATH/connectionProfiles/DESTINATION_CONNECTION_PROFILE_ID",
    "verb": "create",
    "requestedCancellation": false,
    "apiVersion": "DATASTREAM_API_VERSION"
  },
  "done": false
}

確認兩個連線設定檔都已建立。在提示中輸入下列指令：
```
curl -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" https://datastream.googleapis.com/DATASTREAM_API_VERSION/PROJECT_PATH/connectionProfiles
```
注意： 指令結尾的 connectionProfiles 字串表示您要擷取兩個連線設定檔的資訊，確認設定檔已建立。

確認來源和目的地連線設定檔都傳回兩個結果。

{
  "connectionProfiles": [
    {
      "name": "PROJECT_PATH/connectionProfiles/DESTINATION_CONNECTION_PROFILE_ID",
      "createTime": "DATE_AND_TIME_STAMP",
      "updateTime": "DATE_AND_TIME_STAMP",
      "displayName": "DISPLAY_NAME",
      "gcsProfile": {
        "bucket": "BUCKET_NAME",
        "rootPath": "FOLDER_PATH"
      },
      "noConnectivity": {}
    },
   {
    "name": "PROJECT_PATH/connectionProfiles/SOURCE_CONNECTION_PROFILE_ID",
    "createTime": "DATE_AND_TIME_STAMP",
    "updateTime": "DATE_AND_TIME_STAMP",
    "displayName": "DISPLAY_NAME",
    "oracleProfile": {
      "hostname": "HOSTNAME",
      "port": PORT_NUMBER,
      "username": "USERNAME",
      "databaseService": "DATABASE_SERVICE"
    },
    "noConnectivity": {}
    }
  ]
}

管理連線設定檔

在這個程序中，您將管理為來源 Oracle 資料庫和 Cloud Storage 目的地 bucket 建立的連線設定檔。包括：

正在擷取目的地 Cloud Storage 連線設定檔的相關資訊
修改這個連線設定檔，在本教學課程中，您會將目的地 Cloud Storage bucket 的資料夾變更為 /root/tutorial。Datastream 會將來源資料庫中的資料移轉至這個資料夾。
對來源 Oracle 連線設定檔執行探索 API 呼叫

擷取目的地 Cloud Storage 連線設定檔的相關資訊。在提示中輸入下列指令：

curl -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" https://datastream.googleapis.com/DATASTREAM_API_VERSION/PROJECT_PATH/connectionProfiles/DESTINATION_CONNECTION_PROFILE_ID

確認您看到這個連線設定檔的相關資訊。

{
  "name": "PROJECT_PATH/connectionProfiles/DESTINATION_CONNECTION_PROFILE_ID",
  "createTime": "DATE_AND_TIME_STAMP",
  "updateTime": "DATE_AND_TIME_STAMP",
  "displayName": "DISPLAY_NAME",
  "gcsProfile": {
    "bucket": "BUCKET_NAME",
    "rootPath": "FOLDER_PATH"
  },
  "noConnectivity": {}
}

修改這個連線設定檔。首先，請設定 UPDATE 變數。這個變數包含要變更的連線設定檔值。在本教學課程中，您會將目的地 bucket 的資料夾變更為 /root/tutorial。

如要設定變數，請在提示中輸入下列指令：
```
UPDATE="{\"gcsProfile\":{\"rootPath\":\"/root/tutorial\"}}"
```

在提示中輸入下列指令：

curl -X PATCH -d $UPDATE -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" https://datastream.googleapis.com/DATASTREAM_API_VERSION/PROJECT_PATH/connectionProfiles/DESTINATION_CONNECTION_PROFILE_ID?update_mask=gcsProfile.rootPath

確認您看到下列程式碼：

{
  "name": "PROJECT_PATH/operations/operation-DESTINATION_CONNECTION_PROFILE_OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.datastream.DATASTREAM_API_VERSION.OperationMetadata",
    "createTime": "DATE_AND_TIME_STAMP",
    "target": "PROJECT_PATH/connectionProfiles/DESTINATION_CONNECTION_PROFILE_ID",
    "verb": "update",
    "requestedCancellation": false,
    "apiVersion": "DATASTREAM_API_VERSION"
  },
  "done": false
}

確認連線設定檔已修改。在提示中輸入下列指令：

curl -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" https://datastream.googleapis.com/DATASTREAM_API_VERSION/PROJECT_PATH/connectionProfiles/DESTINATION_CONNECTION_PROFILE_ID

確認 Cloud Storage 連線設定檔的目的地 bucket 資料夾現在是 /root/tutorial。

{
  "name": "PROJECT_PATH/connectionProfiles/DESTINATION_CONNECTION_PROFILE_ID",
  "createTime": "DATE_AND_TIME_STAMP",
  "updateTime": "DATE_AND_TIME_STAMP",
  "displayName": "DISPLAY_NAME",
  "gcsProfile": {
    "bucket": "BUCKET_NAME",
    "rootPath": "/root/tutorial"
  },
  "noConnectivity": {}
}

使用 Datastream 探索 API，探索來源 Oracle 資料庫的結構定義和資料表。Datastream 會透過來源連線設定檔，提供這個資料庫的存取權。
1. 探索 Oracle 資料庫的結構定義。在提示中輸入下列指令：
```
curl -X POST -d "{\"connection_profile_name\":\"projects/YOUR_PROJECT_NUMBER/locations/YOUR_PROJECT_LOCATION/connectionProfiles/SOURCE_CONNECTION_PROFILE_ID\", \"oracle_rdbms\":{\"oracleSchemas\":[{\"schema\":\"ROOT\"}]}}" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" https://datastream.googleapis.com/DATASTREAM_API_VERSION/PROJECT_PATH/connectionProfiles:discover
```
  注意： 請將 YOUR_PROJECT_NUMBER 預留位置替換為 Google Cloud 專案的 10 位數識別碼。程式碼的 connectionProfiles:discover 部分表示您要使用來源 Oracle 資料庫的連線設定檔，探索該資料庫的所有結構定義。
2. 確認 Datastream 擷取資料庫的所有結構定義。
3. 擷取資料庫中結構定義的資料表。在本教學課程中，您將使用探索 API 擷取 ROOT 結構定義的資料表。不過，您可以探索資料庫中任何結構定義的資料表。
  
  在提示中輸入下列指令：
```
curl -X POST -d "{\"connection_profile_name\":\"projects/YOUR_PROJECT_NUMBER/locations/YOUR_PROJECT_LOCATION/connectionProfiles/SOURCE_CONNECTION_PROFILE_ID\", \"oracle_rdbms\":{\"oracleSchemas\":[{\"schema\":\"ROOT\"}]}}" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" https://datastream.googleapis.com/DATASTREAM_API_VERSION/PROJECT_PATH/connectionProfiles:discover
```
1. 確認 Datastream 擷取了您指定結構定義的所有資料表 (在本教學課程中，為 ROOT 結構定義)。

您已為來源 Oracle 資料庫和 Cloud Storage 中的目的地 bucket 建立及管理連線設定檔，現在可以在 Datastream 建立及管理串流。

建立及管理串流

在本節中，您將建立及管理串流。Datastream 會使用這個串流，將資料、結構定義和資料表從來源資料庫轉移至目的地 Cloud Storage bucket 中的資料夾。

建立及管理串流包括：

驗證串流，確保串流能順利執行，且通過所有驗證檢查。這些檢查包括：
- 來源是否已正確設定，可讓 Datastream 從中串流資料。
- 串流是否能同時連線至來源和目的地。
- 串流的端對端設定。
使用下列清單建立串流：
- 許可清單。這份清單指定來源資料庫中的資料表和結構定義，Datastream 可將這些資料表和結構定義轉移至 Cloud Storage 目的地 bucket 中的資料夾。在本教學課程中，這是 /root/tutorial 資料夾。
- 拒絕清單。這份清單會指定來源資料庫中的資料表和結構定義，Datastream 不得將這些資料表和結構定義轉移至 Cloud Storage 目的地 bucket 中的資料夾。
擷取串流相關資訊
修改串流
啟動串流，讓 Datastream 將來源資料庫中的資料、結構定義和資料表，移轉至目的地 Cloud Storage bucket 中的資料夾。
使用 Fetch Errors API 偵測與串流相關的任何錯誤
暫停串流。串流暫停時，Datastream 不會將任何新資料從來源資料庫提取至目的地 bucket。
恢復暫停的串流，讓 Datastream 繼續將資料移轉至目的地 bucket。

建立串流

在這個程序中，您會建立串流，將來源 Oracle 資料庫的資料傳輸到目的地 Cloud Storage bucket 中的資料夾。您建立的串流會包含許可清單和拒絕清單。

設定 SCHEMAS 變數。這個變數定義的結構定義，包含您要 Datastream 從來源資料庫擷取，並移轉至 Cloud Storage 目的地 bucket /root/tutorial 資料夾的資料和資料表。在本教學課程中，您會將 SCHEMAS 變數設為與 ROOT 結構定義建立關聯。

在提示中輸入下列指令：
```
SCHEMAS="{\"oracleSchemas\":[{\"schema\":\"ROOT\"}]}"
```
在提示中輸入 echo $SCHEMAS | jq 指令，即可查看您為這個變數定義的 ROOT 結構定義，並以易於閱讀的文字呈現。

建立串流。在提示中輸入下列指令：

STREAM="{\"display_name\":\"DISPLAY_NAME\",\"source_config\":{\"source_connection_profile_name\":\"PROJECT_PATH/connectionProfiles/SOURCE_CONNECTION_PROFILE_ID",\"oracle_source_config\":{\"allowlist\":$SCHEMAS,\"rejectlist\":{}}},\"destination_config\":{\"destination_connection_profile_name\":\"PROJECT_PATH/connectionProfiles/DESTINATION_CONNECTION_PROFILE_ID\",\"gcs_destination_config\":{\"file_rotation_mb\":5,\"file_rotation_interval\":{\"seconds\":15},\"avro_file_format\":{}},\"backfill_all\":{}}}"

在提示中輸入 echo $STREAM | jq 指令，以易於閱讀的文字查看您建立的串流。

{
  "display_name": "DISPLAY_NAME",
  "source_config": {
    "source_connection_profile_name": "PROJECT_PATH/connectionProfiles/SOURCE_CONNECTION_PROFILE_ID",
    "oracle_source_config": {
      "allowlist": {
        "oracleSchemas": [
          {
            "schema": "ROOT"
          }
        ]
      },
      "rejectlist": {}
    }
  },
  "destination_config": {
    "destination_connection_profile_name": "PROJECT_PATH/connectionProfiles/DESTINATION_CONNECTION_PROFILE_ID",
    "gcs_destination_config": {
      "file_rotation_mb": 5,
      "file_rotation_interval": {
        "seconds": 15
      },
      "avro_file_format": {}
    }
  },
  "backfill_all": {}
}

請參閱下表，瞭解串流的下列參數：

參數	說明
`allowlist`	包含資料表和資料的結構定義，會從來源資料庫移轉至 Cloud Storage 目的地 bucket 的資料夾。在本教學課程中，`ROOT` 結構定義中的所有資料表和資料 (且僅限這個結構定義) 都會移轉至目的地 bucket 的 `/root/tutorial` 資料夾。
`rejectlist`	任何包含資料表和資料的結構定義，都不會移轉至 Cloud Storage 目的地 bucket 的資料夾。在本教學課程中，`{}` 值表示來源資料庫中的所有資料表和資料，都能轉移至目的地 bucket。
`file_rotation_mb`	檔案大小 (以 MB 為單位)，這些檔案包含從來源資料庫移轉至 Cloud Storage 目的地 bucket 中資料夾的資料。在本教學課程中，從來源資料庫擷取的資料會寫入 5 MB 的檔案。如果資料超過這個大小，就會分割成多個 5 MB 的檔案。
`file_rotation_interval`	Datastream 關閉 Cloud Storage 目的地 bucket 資料夾中的現有檔案，並開啟另一個檔案來包含從來源資料庫移轉的資料，兩者之間相隔的秒數。在本教學課程中，檔案輪替間隔設為 15 秒。
`avro_file_format`	Datastream 從來源資料庫移轉至 Cloud Storage 目的地 bucket 資料夾的檔案格式。在本教學課程中，檔案格式為 Avro。除了 Avro 之外，Datastream 現在也支援 JSON 輸出格式，可將檔案寫入 Cloud Storage。這項資訊會以 `json_file_format` 參數表示，而非 `avro_file_format`。如果是 JSON 格式，您可以：在路徑中新增一致類型的結構定義檔案。因此，Datastream 會將兩個檔案寫入 Cloud Storage：JSON 資料檔案和 Avro 結構定義檔案。結構定義檔案的名稱與資料檔案相同，但副檔名為 `.schema`。啟用 gzip 壓縮功能，讓 Datastream 壓縮寫入 Cloud Storage 的檔案。由於這兩項屬性不適用於 Avro，因此 `avro_file_format` 參數的值會設為空白字典 (`{}`)。
`backfill_all`	這個參數與歷來資料回填有關。將這個參數設為空白字典 (`{}`)，Datastream 就會補充：從來源資料庫到目的地的歷來資料，以及資料的持續變更。結構定義和資料表，從來源到目的地。

驗證串流，確保串流能順利執行，且所有驗證檢查均通過。在提示中輸入下列指令：
```
curl -X POST -d $STREAM -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" "https://datastream.googleapis.com/DATASTREAM_API_VERSION/PROJECT_PATH/streams?stream_id=STREAM_ID&validate_only=true"
```
將 STREAM_ID 參數值替換為這個串流專用的專屬 ID (例如 stream-1)。

&validate_only=true 值表示您只會驗證串流，不會建立串流。請將整個網址放在引號內，這樣一來，Datastream 就會擷取 &validate_only=true 值來驗證串流。
確認您看到 {} 程式碼行。這表示串流已通過所有驗證檢查，且沒有任何相關錯誤。

如果驗證檢查未通過，系統會顯示失敗原因和修正問題的方法。

完成適當修正後，請再次提出要求，確保所有驗證檢查都通過。

提交串流，以便建立。在提示中輸入下列指令：

curl -X POST -d $STREAM -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" https://datastream.googleapis.com/DATASTREAM_API_VERSION/PROJECT_PATH/streams?stream_id=STREAM_ID

確認您看到下列程式碼：

{
  "name": "PROJECT_PATH/operations/operation-STREAM_OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.datastream.DATASTREAM_API_VERSION.OperationMetadata",
    "createTime": "DATE_AND_TIME_STAMP",
    "target": "PROJECT_PATH/streams/STREAM_ID",
    "verb": "create",
    "requestedCancellation": false,
    "apiVersion": "DATASTREAM_API_VERSION"
  },
  "done": false
}

確認串流已建立。在提示中輸入下列指令：
```
curl -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" https://datastream.googleapis.com/DATASTREAM_API_VERSION/PROJECT_PATH/streams
```
注意： 指令結尾的 streams 字串表示您要擷取串流相關資訊，確認串流已建立。

確認您建立的串流有傳回結果。

{
  "streams": [
    {
      "name": "PROJECT_PATH/streams/STREAM_ID",
      "createTime": "DATE_AND_TIME_STAMP",
      "updateTime": "DATE_AND_TIME_STAMP",
      "displayName": "DISPLAY_NAME",
      "sourceConfig": {
        "sourceConnectionProfileName": "projects/YOUR_PROJECT_NUMBER/locations/YOUR_PROJECT_LOCATION/connectionProfiles/SOURCE_CONNECTION_PROFILE_ID",
        "oracleSourceConfig": {
          "allowlist": {
            "oracleSchemas": [
              {
                "schema": "ROOT"
              }
            ]
          },
          "rejectlist": {}
        }
      },
      "destinationConfig": {
        "destinationConnectionProfileName": "projects/YOUR_PROJECT_NUMBER/locations/YOUR_PROJECT_LOCATION/connectionProfiles/DESTINATION_CONNECTION_PROFILE_ID",
      "gcsDestinationConfig": {
          "fileRotationMb": 5,
          "fileRotationInterval": "15s"
          "avroFileFormat": {}
        }
      },
      "state": "CREATED",
      "backfillAll": {}
    }
  ]
}

管理直播

在這項程序中，您會使用建立的串流，將資料從來源 Oracle 資料庫轉移到 Cloud Storage 目的地 bucket 中的資料夾。包括：

擷取串流相關資訊
修改串流
開始串流
使用 Fetch Errors API 偵測與串流相關的任何錯誤
暫停及繼續串流

擷取串流相關資訊。在提示中輸入下列指令：

curl -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" https://datastream.googleapis.com/DATASTREAM_API_VERSION/PROJECT_PATH/streams/STREAM_ID

確認您看到這個串流的相關資訊。

{
  "name": "PROJECT_PATH/streams/STREAM_ID",
  "createTime": "DATE_AND_TIME_STAMP",
  "updateTime": "DATE_AND_TIME_STAMP",
  "displayName": "DISPLAY_NAME",
  "sourceConfig": {
    "sourceConnectionProfileName": "projects/YOUR_PROJECT_NUMBER/locations/YOUR_PROJECT_LOCATION/connectionProfiles/SOURCE_CONNECTION_PROFILE_ID",
    "oracleSourceConfig": {
      "allowlist": {
        "oracleSchemas": [
          {
            "schema": "ROOT"
          }
        ]
      },
      "rejectlist": {}
     }
    },
    "destinationConfig": {
      "destinationConnectionProfileName": "projects/YOUR_PROJECT_NUMBER/locations/YOUR_PROJECT_LOCATION/connectionProfiles/DESTINATION_CONNECTION_PROFILE_ID",
      "gcsDestinationConfig": {
        "fileRotationMb": 5,
        "fileRotationInterval": "15s"
        "avroFileFormat": {}
      }
    },
    "state": "CREATED",
    "backfillAll": {}
  }

修改這個串流。首先，請設定 UPDATE 變數。這個變數包含要變更的串流值。在本教學課程中，請將檔案大小 (以 MB 為單位) 從 5 MB 變更為 100 MB。這些檔案包含從來源資料庫移轉至 Cloud Storage 目的地 bucket 資料夾的資料。從來源資料庫擷取資料時，系統會將資料寫入 100 MB 的檔案。如果資料超過這個大小，系統會將資料分割成多個 100 MB 的檔案。

如要設定變數，請在提示中輸入下列指令：
```
UPDATE="{\"destination_config\":{\"gcs_destination_config\":{\"file_rotation_mb\":100}}}"
```

在提示中輸入下列指令：

curl -X PATCH -d $UPDATE -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" https://datastream.googleapis.com/DATASTREAM_API_VERSION/PROJECT_PATH/streams/STREAM_ID/?update_mask=destination_config.gcs_destination_config.file_rotation_mb

確認您看到下列程式碼：

{
  "name": "PROJECT_PATH/operations/operation-STREAM_OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.datastream.DATASTREAM_API_VERSION.OperationMetadata",
    "createTime": "DATE_AND_TIME_STAMP",
    "target": "PROJECT_PATH/streams/STREAM_ID",
    "verb": "update",
    "requestedCancellation": false,
    "apiVersion": "DATASTREAM_API_VERSION"
  },
  "done": false
}

確認串流已修改。在提示中輸入下列指令：

curl -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" https://datastream.googleapis.com/DATASTREAM_API_VERSION/PROJECT_PATH/streams/STREAM_ID

確認 Cloud Storage 連線設定檔的 fileRotationMb 參數值現在是 100。

{
  "name": "PROJECT_PATH/streams/STREAM_ID",
  "createTime": "DATE_AND_TIME_STAMP",
  "updateTime": "DATE_AND_TIME_STAMP",
  "displayName": "DISPLAY_NAME",
  "sourceConfig": {
    "sourceConnectionProfileName": "projects/YOUR_PROJECT_NUMBER/locations/YOUR_PROJECT_LOCATION/connectionProfiles/SOURCE_CONNECTION_PROFILE_ID",
    "oracleSourceConfig": {
      "allowlist": {
        "oracleSchemas": [
          {
            "schema": "ROOT"
          }
        ]
      },
      "rejectlist": {}
     }
    },
    "destinationConfig": {
      "destinationConnectionProfileName": "projects/YOUR_PROJECT_NUMBER/locations/YOUR_PROJECT_LOCATION/connectionProfiles/DESTINATION_CONNECTION_PROFILE_ID",
      "gcsDestinationConfig": {
        "fileRotationMb": 100,
        "fileRotationInterval": "15s"
        "avroFileFormat": {}
      }
    },
    "state": "CREATED",
    "backfillAll": {}
  }

啟動串流。方法如下：
1. 變更 UPDATE 變數。在提示中輸入下列指令：
```
UPDATE="{\"state\":\"RUNNING\"}"
```
2. 接著輸入下列指令：
```
curl -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" https://datastream.googleapis.com/DATASTREAM_API_VERSION/PROJECT_PATH/streams/STREAM_ID?updateMask=state
```
  在要求中使用 updateMask 參數，即可只在要求主體中加入指定欄位。
  
  在本例中，指定的欄位是 state 欄位，代表串流的狀態。啟動串流後，狀態會從「CREATED」變更為「RUNNING」。

確認您看到下列程式碼。

{
  "name": "PROJECT_PATH/operations/operation-STREAM_OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.datastream.DATASTREAM_API_VERSION.OperationMetadata",
    "createTime": "DATE_AND_TIME_STAMP",
    "target": "PROJECT_PATH/streams/STREAM_ID",
    "verb": "start",
    "requestedCancellation": false,
    "apiVersion": "DATASTREAM_API_VERSION"
  },
  "done": false
}

幾分鐘後，擷取串流相關資訊，確認串流已啟動：

curl -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" https://datastream.googleapis.com/DATASTREAM_API_VERSION/PROJECT_PATH/streams/STREAM_ID

確認串流狀態已從「CREATED」變更為「RUNNING」。

{
  "name": "PROJECT_PATH/streams/STREAM_ID",
  "createTime": "DATE_AND_TIME_STAMP",
  "updateTime": "DATE_AND_TIME_STAMP",
  "displayName": "DISPLAY_NAME",
  "sourceConfig": {
    "sourceConnectionProfileName": "projects/YOUR_PROJECT_NUMBER/locations/YOUR_PROJECT_LOCATION/connectionProfiles/SOURCE_CONNECTION_PROFILE_ID",
    "oracleSourceConfig": {
      "allowlist": {
        "oracleSchemas": [
          {
            "schema": "ROOT"
          }
        ]
      },
      "rejectlist": {}
    }
  },
  "destinationConfig": {
    "destinationConnectionProfileName": "projects/YOUR_PROJECT_NUMBER/locations/YOUR_PROJECT_LOCATION/connectionProfiles/DESTINATION_CONNECTION_PROFILE_ID",
    "gcsDestinationConfig": {
      "fileRotationMb": 100,
      "fileRotationInterval": "15s"
      "avroFileFormat": {}
    }
  },
  "state": "RUNNING",
  "backfillAll": {}
}

使用 Fetch Errors API 擷取與串流相關的任何錯誤。

在提示中輸入下列指令：

curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" https://datastream.googleapis.com/DATASTREAM_API_VERSION/PROJECT_PATH/streams/STREAM_ID:fetchErrors

確認您看到下列程式碼：

  {
    "name": "PROJECT_PATH/operations/operation-FETCH_ERRORS_OPERATION_ID",
    "metadata": {
      "@type": "type.googleapis.com/google.cloud.datastream.DATASTREAM_API_VERSION.OperationMetadata",
      "createTime": "DATE_AND_TIME_STAMP",
      "target": "PROJECT_PATH/streams/STREAM_ID",
      "verb": "fetchErrors",
      "requestedCancellation": false,
      "apiVersion": "DATASTREAM_API_VERSION"
    },
    "done": false
  }

在提示中輸入下列指令：

curl -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" https://datastream.googleapis.com/DATASTREAM_API_VERSION/PROJECT_PATH/operations/operation-FETCH_ERRORS_OPERATION_ID

確認您看到下列程式碼：

  {
    "name": "PROJECT_PATH/operations/operation-FETCH_ERRORS_OPERATION_ID",
    "metadata": {
      "@type": "type.googleapis.com/google.cloud.datastream.DATASTREAM_API_VERSION.OperationMetadata",
      "createTime": "DATE_AND_TIME_STAMP",
      "endTime": "DATE_AND_TIME_STAMP",
      "target": "PROJECT_PATH/streams/STREAM_ID",
      "verb": "fetchErrors",
      "requestedCancellation": false,
      "apiVersion": "DATASTREAM_API_VERSION"
    },
    "done": true,
    "response": {
      "@type": "type.googleapis.com/google.cloud.datastream.DATASTREAM_API_VERSION.FetchErrorsResponse"
    }
  }

暫停串流。方法如下：

變更 UPDATE 變數。在提示中輸入下列指令：
```
UPDATE="{\"state\":\"PAUSED\"}"
```

接著輸入下列指令：

curl -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" https://datastream.googleapis.com/DATASTREAM_API_VERSION/PROJECT_PATH/streams/STREAM_ID?updateMask=state

暫停串流後，狀態會從 RUNNING 變更為 PAUSED。

確認您看到下列程式碼。

{
  "name": "PROJECT_PATH/operations/operation-STREAM_OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.datastream.DATASTREAM_API_VERSION.OperationMetadata",
    "createTime": "DATE_AND_TIME_STAMP",
    "target": "PROJECT_PATH/streams/STREAM_ID",
    "verb": "start",
    "requestedCancellation": false,
    "apiVersion": "DATASTREAM_API_VERSION"
  },
  "done": false
}

擷取串流相關資訊，確認串流已暫停。

curl -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" https://datastream.googleapis.com/DATASTREAM_API_VERSION/PROJECT_PATH/streams/STREAM_ID

確認串流狀態已從「RUNNING」變更為「PAUSED」。

{
  "name": "PROJECT_PATH/streams/STREAM_ID",
  "createTime": "DATE_AND_TIME_STAMP",
  "updateTime": "DATE_AND_TIME_STAMP",
  "displayName": "DISPLAY_NAME",
  "sourceConfig": {
    "sourceConnectionProfileName": "projects/YOUR_PROJECT_NUMBER/locations/YOUR_PROJECT_LOCATION/connectionProfiles/SOURCE_CONNECTION_PROFILE_ID",
    "oracleSourceConfig": {
      "allowlist": {
        "oracleSchemas": [
          {
            "schema": "ROOT"
          }
        ]
      },
      "rejectlist": {}
    }
  },
  "destinationConfig": {
    "destinationConnectionProfileName": "projects/YOUR_PROJECT_NUMBER/locations/YOUR_PROJECT_LOCATION/connectionProfiles/DESTINATION_CONNECTION_PROFILE_ID",
    "gcsDestinationConfig": {
      "fileRotationMb": 100,
      "fileRotationInterval": "15s"
      "avroFileFormat": {}
    }
  },
  "state": "PAUSED",
  "backfillAll": {}
}

繼續播放暫停的串流。方法如下：

變更 UPDATE 變數。在提示中輸入下列指令：
```
UPDATE="{\"state\":\"RUNNING\"}"
```

接著輸入下列指令：

curl -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" https://datastream.googleapis.com/DATASTREAM_API_VERSION/PROJECT_PATH/streams/STREAM_ID?updateMask=state

恢復串流後，狀態會從「PAUSED」變回「RUNNING」。

確認您看到下列程式碼。

{
  "name": "PROJECT_PATH/operations/operation-STREAM_OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.datastream.DATASTREAM_API_VERSION.OperationMetadata",
    "createTime": "DATE_AND_TIME_STAMP",
    "target": "PROJECT_PATH/streams/STREAM_ID",
    "verb": "start",
    "requestedCancellation": false,
    "apiVersion": "DATASTREAM_API_VERSION"
  },
  "done": false
}

幾秒後，擷取串流相關資訊，確認串流已再次執行。

curl -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" https://datastream.googleapis.com/DATASTREAM_API_VERSION/PROJECT_PATH/streams/STREAM_ID

確認串流狀態已從「PAUSED」變回「RUNNING」。

{
  "name": "PROJECT_PATH/streams/STREAM_ID",
  "createTime": "DATE_AND_TIME_STAMP",
  "updateTime": "DATE_AND_TIME_STAMP",
  "displayName": "DISPLAY_NAME",
  "sourceConfig": {
    "sourceConnectionProfileName": "projects/YOUR_PROJECT_NUMBER/locations/YOUR_PROJECT_LOCATION/connectionProfiles/SOURCE_CONNECTION_PROFILE_ID",
    "oracleSourceConfig": {
      "allowlist": {
        "oracleSchemas": [
          {
            "schema": "ROOT"
          }
        ]
      },
      "rejectlist": {}
    }
  },
  "destinationConfig": {
    "destinationConnectionProfileName": "projects/YOUR_PROJECT_NUMBER/locations/YOUR_PROJECT_LOCATION/connectionProfiles/DESTINATION_CONNECTION_PROFILE_ID",
    "gcsDestinationConfig": {
      "fileRotationMb": 100,
      "fileRotationInterval": "15s"
      "avroFileFormat": {}
    }
  },
  "state": "RUNNING",
  "backfillAll": {}
}

您已建立及管理串流、確認串流沒有任何相關錯誤，且串流狀態為「RUNNING」，現在可以驗證串流能否將資料從來源資料庫，移轉至 Cloud Storage 目的地 bucket 中的資料夾。

驗證串流

在這個程序中，您會確認 Datastream：

將與來源 Oracle 資料庫 ROOT 結構定義相關聯的所有資料表資料，轉移至 Cloud Storage 目的地 bucket 的 /root/tutorial 資料夾。
將資料轉譯為 Avro 檔案格式。

前往 Cloud Storage 的「Storage browser」(Storage 瀏覽器) 頁面。

前往「Storage 瀏覽器」頁面
按一下包含 bucket 的連結。
如果「物件」分頁未啟用，請點選該分頁。
依序點選「root」資料夾和「tutorial」資料夾。

注意： 您將目的地 bucket 的資料夾變更為 /root/tutorial，修改目的地連線設定檔後，Datastream 建立了 root 和 tutorial 資料夾。
確認您看見代表來源 Oracle 資料庫 ROOT 結構定義資料表的資料夾。
按一下其中一個資料表資料夾，並向下展開，直到看見與資料表相關聯的資料。
按一下代表資料的檔案，然後點選「下載」。
在 Avro 工具 (例如 Avro Viewer) 中開啟這個檔案，確保內容可讀。這表示 Datastream 也將資料轉譯為 Avro 檔案格式。

清除所用資源

完成本教學課程後，您可以清除在 Datastream 建立的資源，以免占用配額及產生費用。下列各節將說明如何刪除或停用這些資源。

刪除專案

如要避免付費，最簡單的方法就是刪除您為了本教學課程所建立的專案。

刪除專案的方法如下：

前往 Google Cloud 控制台的「Manage resources」(管理資源) 頁面。
前往「Manage resources」(管理資源)
在專案清單中選取要刪除的專案，然後點選「Delete」(刪除)。
在對話方塊中輸入專案 ID，然後按一下 [Shut down] (關閉) 以刪除專案。

刪除 Cloud Storage 目的地 bucket

在 Cloud Storage 左側的導覽匣中，按一下「Browser」(瀏覽器)。
勾選 bucket 左側的核取方塊，然後按一下「刪除」。
在「要刪除 bucket 嗎？」視窗中，在文字欄位輸入 bucket 名稱，然後點選「確認」。

刪除串流

確認 Cloud Shell 應用程式處於啟用狀態。

在提示中輸入下列指令：

curl -X DELETE -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" https://datastream.googleapis.com/DATASTREAM_API_VERSION/PROJECT_PATH/streams/STREAM_ID

確認您看到下列程式碼：

{
  "name": "PROJECT_PATH/operations/operation-STREAM_OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.datastream.DATASTREAM_API_VERSION.OperationMetadata",
    "createTime": "DATE_AND_TIME_STAMP",
    "target": "PROJECT_PATH/streams/STREAM_ID",
    "verb": "delete",
    "requestedCancellation": false,
    "apiVersion": "DATASTREAM_API_VERSION"
  },
  "done": false
}

確認串流已刪除。在提示中輸入下列指令：

curl -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" https://datastream.googleapis.com/DATASTREAM_API_VERSION/PROJECT_PATH/streams

確認傳回空值 {}。這表示 Datastream 中已沒有任何串流，您建立的串流已刪除。

刪除連線設定檔

刪除來源 Oracle 資料庫的連線設定檔。在提示中輸入下列指令：

curl -X DELETE -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" https://datastream.googleapis.com/DATASTREAM_API_VERSION/PROJECT_PATH/connectionProfiles/SOURCE_CONNECTION_PROFILE_ID

確認您看到下列程式碼：

{
  "name": "PROJECT_PATH/operations/operation-SOURCE_CONNECTION_PROFILE_OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.datastream.DATASTREAM_API_VERSION.OperationMetadata",
    "createTime": "DATE_AND_TIME_STAMP",
    "target": "PROJECT_PATH/connectionProfiles/SOURCE_CONNECTION_PROFILE_ID",
    "verb": "delete",
    "requestedCancellation": false,
    "apiVersion": "DATASTREAM_API_VERSION"
  },
  "done": false
}

刪除 Cloud Storage 中目的地 bucket 的連線設定檔。在提示中輸入下列指令：

curl -X DELETE -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" https://datastream.googleapis.com/DATASTREAM_API_VERSION/PROJECT_PATH/connectionProfiles/DESTINATION_CONNECTION_PROFILE_ID

確認您看到下列程式碼：

{
  "name": "PROJECT_PATH/operations/operation-DESTINATION_CONNECTION_PROFILE_OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.datastream.DATASTREAM_API_VERSION.OperationMetadata",
    "createTime": "DATE_AND_TIME_STAMP",
    "target": "PROJECT_PATH/connectionProfiles/DESTINATION_CONNECTION_PROFILE_ID",
    "verb": "delete",
    "requestedCancellation": false,
    "apiVersion": "DATASTREAM_API_VERSION"
  },
  "done": false
}

確認兩個連線設定檔都已刪除。在提示中輸入下列指令：

curl -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" https://datastream.googleapis.com/DATASTREAM_API_VERSION/PROJECT_PATH/connectionProfiles

確認傳回空值 {}。這表示 Datastream 中已沒有任何連線設定檔，您建立的設定檔也已刪除。

後續步驟

進一步瞭解 Datastream。
歡迎自行試用其他 Google Cloud 功能，並參考我們的教學課程。

使用 Datastream API 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

目標

費用

事前準備

設定環境變數

建立及管理連線設定檔

建立連線設定檔

管理連線設定檔

建立及管理串流

建立串流

管理直播

驗證串流

清除所用資源

刪除專案

刪除 Cloud Storage 目的地 bucket

刪除串流

刪除連線設定檔

後續步驟

使用 Datastream API