使用 Datastream API

Datastream

如果企業有許多獨立的資料來源,可能難以存取整個機構的企業資料,尤其是即時資料。這會導致資料存取受限且速度緩慢,進而妨礙機構進行內省。

Datastream 可近乎即時地存取各種內部部署和雲端資料來源的變更資料,以建立組織資料的存取權。Datastream 提供統一的取用 API,讓機構內各部門都能存取最新的企業資料,並支援近乎即時的整合情境。

其中一個例子是將資料從來源資料庫移轉至雲端儲存服務或訊息佇列,並將這些資料轉換為其他應用程式和服務可讀取的格式,以便與該儲存服務或訊息佇列通訊。

在本教學課程中,您將瞭解如何使用 Datastream,將來源 Oracle 資料庫中的結構定義、表格和資料,轉移到 Cloud Storage bucket 中的資料夾。Cloud Storage 是一項網路服務,可讓您在 Google Cloud儲存及存取資料。這項服務結合了 Google 雲端的效能和可擴充性,以及進階安全性和共用功能。

將這項資訊轉移至目標 Cloud Storage 值區的資料夾時,Datastream 會將這項資訊轉換為 Avro。Avro 是以 JavaScript 物件標記法 (JSON) 編寫的結構定義。完成這項轉換後,您就能以統一的方式讀取不同資料來源的資料。

目標

在本教學課程中,您將瞭解以下內容:

  • 設定環境變數。向 Datastream 發出要求,建立及管理連線設定檔串流時,您會使用這些變數。
  • 為來源資料庫和 Cloud Storage 中的目的地 bucket 建立及管理連線設定檔。建立這些連線設定檔時,您會建立包含來源資料庫和目的地 Cloud Storage bucket 相關資訊的記錄。Datastream 中的串流會使用連線設定檔中的資訊,將資料從來源資料庫轉移至目的地值區中的資料夾。
  • 建立及管理串流。Datastream 會使用這個串流,將來源資料庫中的資料、結構定義和資料表,轉移至目的地 bucket 中的資料夾。
  • 確認 Datastream 會將與來源 Oracle 資料庫結構定義相關聯的資料和資料表,轉移至目的地 bucket 中的資料夾,並將這些資料轉換為 Avro 檔案格式。
  • 清除在 Datastream 上建立的資源,這樣資源就不會占用配額,日後也無須為其付費。

費用

在本文件中,您會使用 Google Cloud的下列計費元件:

  • Cloud Storage

如要根據預測用量估算費用,請使用 Pricing Calculator

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

事前準備

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Make sure that billing is enabled for your Google Cloud project.

  4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  5. Make sure that billing is enabled for your Google Cloud project.

  6. 啟用 Datastream API。

    啟用 API

  7. 確認您的使用者帳戶已獲派 Datastream 管理員角色。

    前往「IAM」頁面

  8. 請確認您有 Datastream 可存取的來源資料庫。在本教學課程中,我們使用 Oracle 資料庫做為來源。
  9. 將來源資料庫設為允許來自 Datastream 公開 IP 位址的連入連線。如要查看所有 Datastream 地區的位置及其相關聯的公開 IP 位址,請參閱「IP 許可清單和區域」。
  10. 請確認您已設定 Datastream 可存取的目的地 Cloud Storage 儲存空間,並使用 IP 許可清單、轉送 SSH 通道或虛擬私有雲對等互連網路連線方法
  11. 請確認來源資料庫中有資料、資料表和結構定義,Datastream 才能將這些項目轉移至目標 Cloud Storage bucket 中的資料夾。
  12. 下載並安裝 Cloud Shell。這個用戶端應用程式可讓您透過指令列存取雲端資源 (包括 Datastream)。
  13. 安裝及設定 jq 公用程式。這個公用程式是輕量級的彈性指令列 JSON 處理器。您可以使用這個處理器,以易於閱讀的文字顯示複雜的 cURL 指令。

設定環境變數

在本程序中,您將設定下列變數:

  • $PROJECT:這個變數與您的 Google Cloud 專案相關聯。您分配及使用的任何Google Cloud 資源都必須位於專案中。
  • $TOKEN:這個變數與存取權杖相關聯。存取權杖會提供 Cloud Shell 使用的連線工作階段,以便透過 REST API 在 Datastream 中執行工作。
  1. 啟動 Cloud Shell 應用程式。

  2. 使用 Google 帳戶驗證應用程式後,請輸入下列指令:

    gcloud auth login
    
  3. Do you want to continue (Y/n)? 提示中,輸入 Y

  4. 開啟網路瀏覽器,然後將網址複製到瀏覽器中。

  5. 使用 Google 帳戶向 Google Cloud SDK 進行驗證。「登入」頁面會顯示驗證碼。這組代碼就是存取權杖。

  6. 複製存取權杖,然後貼到 Cloud Shell 應用程式的 Enter verification code: 參數中,並按下 Enter

  7. 在提示中輸入 PROJECT=\"YOUR_PROJECT_NAME\",將 $PROJECT 環境變數設為您的 Google Cloud專案。

  8. 在提示中輸入 gcloud config set project YOUR_PROJECT_NAME,將您要使用的專案設為 Google Cloud專案。

    命令提示字元會更新,以反映您目前使用的專案,並遵守以下格式:USERNAME@cloudshell:~ (YOUR_PROJECT_NAME)$

  9. 在提示中輸入 TOKEN=$(gcloud auth print-access-token),即可擷取存取權杖並儲存為變數。

  10. 在提示中輸入下列指令,確保 $PROJECT$TOKEN 變數設定正確:

    • echo $PROJECT
    • echo $TOKEN

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

建立及管理連線設定檔

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

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

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

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

建立連線設定檔

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

  1. 建立來源 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。

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

    {
      "displayName": "DISPLAY_NAME",
      "oracle_profile": {
        "hostname": "HOSTNAME",
        "username": "USERNAME",
        "password": "PASSWORD",
        "database_service": "DATABASE_SERVICE",
        "port": PORT_NUMBER
       },
      "no_connectivity": {}
    }
  2. 提交 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)。
  3. 確認您看到下列幾行程式碼:

    {
      "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
    }
  4. 建立連線設定檔,連結至 Cloud Storage 中的目的地 bucket。在提示中輸入下列指令:

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

    請參閱下表,瞭解目的地 bucket 的參數值:

    參數值取代憑證
    DISPLAY_NAME目的地 bucket 的連線設定檔顯示名稱。
    BUCKET_NAME目的地 bucket 的名稱。
    FOLDER_PATHDatastream 將來源資料庫中的資料轉移至目的地值區的資料夾 (例如 /root/path)。
  5. 在提示中輸入 echo $GOOGLECLOUDSTORAGE | jq 指令,即可查看您建立的目的地連線設定檔,並以易於閱讀的文字呈現。

    {
      "displayName": "DISPLAY_NAME",
      "gcs_profile": {
        "bucket_name": "BUCKET_NAME",
        "root_path": "/FOLDER_PATH"
      },
      "no_connectivity": {}
    }
  6. 提交 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
  7. 確認您看到下列幾行程式碼:

    {
      "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
    }
  8. 確認已建立這兩個連線設定檔。在提示中輸入下列指令:

    curl -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" https://datastream.googleapis.com/DATASTREAM_API_VERSION/PROJECT_PATH/connectionProfiles
  9. 確認來源和目的地連線設定檔都傳回兩項結果。

    {
      "connectionProfiles": [
        {
          "name": "PROJECT_PATH/connectionProfiles/DESTINATION_CONNECTION_PROFILE_ID",
          "createTime": "DATE_AND_TIME_STAMP",
          "updateTime": "DATE_AND_TIME_STAMP",
          "displayName": "DISPLAY_NAME",
          "gcsProfile": {
            "bucketName": "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 值區的資料夾變更為 /root/tutorial。Datastream 會將資料從來源資料庫轉移至這個資料夾。
  • 對來源 Oracle 連線設定檔執行探索 API 呼叫
  1. 擷取目的地 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
  2. 確認畫面顯示這個連線設定檔的相關資訊。

    {
      "name": "PROJECT_PATH/connectionProfiles/DESTINATION_CONNECTION_PROFILE_ID",
      "createTime": "DATE_AND_TIME_STAMP",
      "updateTime": "DATE_AND_TIME_STAMP",
      "displayName": "DISPLAY_NAME",
      "gcsProfile": {
        "bucketName": "BUCKET_NAME",
        "rootPath": "FOLDER_PATH"
      },
      "noConnectivity": {}
    }
  3. 修改這個連線設定檔。如要這麼做,請先設定 UPDATE 變數。這個變數包含您要變更的連線設定檔值。在本教學課程中,您會將目的地 bucket 的資料夾變更為 /root/tutorial

    如要設定變數,請在提示中輸入下列指令:

    UPDATE="{\"gcsProfile\":{\"rootPath\":\"/root/tutorial\"}}"
  4. 在提示中輸入下列指令:

    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
  5. 確認您看到下列幾行程式碼:

    {
      "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
    }
  6. 確認連線設定檔已修改。在提示中輸入下列指令:

    curl -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" https://datastream.googleapis.com/DATASTREAM_API_VERSION/PROJECT_PATH/connectionProfiles/DESTINATION_CONNECTION_PROFILE_ID
  7. 確認 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": {
        "bucketName": "BUCKET_NAME",
        "rootPath": "/root/tutorial"
      },
      "noConnectivity": {}
    }
  8. 使用 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
    2. 確認 Datastream 擷取資料庫的所有結構定義。

    3. 擷取資料庫中結構定義的資料表。在本教學課程中,您將使用 Discover 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 中目標值區的資料夾。在本教學課程中,這個資料夾是 /root/tutorial
    • 拒絕清單。這份清單會指定來源資料庫中的資料表和結構定義,Datastream 無法將這些項目轉移至 Cloud Storage 目的地值區中的資料夾。
  • 擷取串流相關資訊
  • 修改串流
  • 啟動串流,讓 Datastream 將來源資料庫中的資料、結構定義和資料表,移轉至目的地 Cloud Storage 值區的資料夾。
  • 使用 Fetch Errors API 偵測與串流相關的任何錯誤
  • 暫停直播。暫停串流後,Datastream 不會再從來源資料庫提取任何新資料到目標值區。
  • 繼續暫停的串流,讓 Datastream 繼續將資料移轉至目的地值區。

建立串流

在本程序中,您會從來源 Oracle 資料庫建立串流,並將資料串流至目的地 Cloud Storage bucket 中的資料夾。您建立的資料串流會包含允許清單和拒絕清單。

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

    在提示中輸入下列指令:

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

  3. 建立串流。在提示中輸入下列指令:

    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\":{}}}"
  4. 在提示中輸入 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 資料夾的結構定義 (包含資料表和資料)。在本教學課程中,{} 值表示系統不會阻止將來源資料庫中的資料表和資料移轉至目的地值區。
    file_rotation_mb含有資料的檔案大小 (以 MB 為單位),這些資料會從來源資料庫轉移到 Cloud Storage 目的地 bucket 的資料夾中。在本教學課程中,由於資料是從來源資料庫擷取,因此會寫入 5 MB 的檔案。如果任何資料超過這個大小,系統會將資料分割為多個 5 MB 的檔案。
    file_rotation_intervalDatastream 在 Cloud Storage 目的地值區的資料夾中關閉現有檔案,並開啟另一個檔案來存放從來源資料庫轉移的資料前,經過的秒數。在本教學課程中,檔案輪替間隔設為 15 秒。
    avro_file_format

    Datastream 從來源資料庫轉移到 Cloud Storage 目的地值區資料夾的檔案格式。在本教學課程中,檔案格式為 Avro。

    backfill_all

    這個參數與歷來回填相關。將這個參數設為空白字典 ({}),Datastream 就會回填:

    • 將來源資料庫中的歷來資料和持續變更的資料,複製到目的地。
    • 將來源的結構定義和資料表複製到目的地。
  5. 驗證串流,確保串流能順利執行,且所有驗證檢查都通過。在提示中輸入下列指令:

    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"
  6. 確認您看到 {} 程式碼行。這表示資料串已通過所有驗證檢查,且沒有與資料串相關的錯誤。

  7. 提交串流,系統就會建立串流。在提示中輸入下列指令:

    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
  8. 確認您看到下列幾行程式碼:

    {
      "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
    }
  9. 確認串流已建立。在提示中輸入下列指令:

    curl -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" https://datastream.googleapis.com/DATASTREAM_API_VERSION/PROJECT_PATH/streams
  10. 確認您是否收到所建立串流的回傳結果。

    {
      "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 目的地值區中的資料夾。包括:

  • 擷取串流相關資訊
  • 修改串流
  • 開始串流播放
  • 使用 Fetch Errors API 偵測與串流相關的任何錯誤
  • 暫停及繼續播放串流
  1. 擷取串流的相關資訊。在提示中輸入下列指令:

    curl -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" https://datastream.googleapis.com/DATASTREAM_API_VERSION/PROJECT_PATH/streams/STREAM_ID
  2. 確認畫面顯示這個串流的相關資訊。

    {
      "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": {}
      }
  3. 修改這個串流。如要這麼做,請先設定 UPDATE 變數。這個變數包含要變更的串流值。在本教學課程中,請變更檔案大小 (以 MB 為單位),這些檔案包含從來源資料庫移轉至 Cloud Storage 目的地 bucket 中資料夾的資料 (從 5 MB 變更為 100 MB)。系統從來源資料庫擷取資料時,會將資料寫入 100 MB 的檔案。如果任何資料超過這個大小,系統會將資料分割成多個 100 MB 的檔案。

    如要設定變數,請在提示中輸入下列指令:

    UPDATE="{\"destination_config\":{\"gcs_destination_config\":{\"file_rotation_mb\":100}}}"
  4. 在提示中輸入下列指令:

    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
  5. 確認您看到下列幾行程式碼:

    {
      "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
    }
  6. 確認串流已修改。在提示中輸入下列指令:

    curl -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" https://datastream.googleapis.com/DATASTREAM_API_VERSION/PROJECT_PATH/streams/STREAM_ID
  7. 確認 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": {}
      }
  8. 開始串流。方法如下:

    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
  9. 確認您看到下列程式碼行。

    {
      "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
    }
  10. 幾分鐘後,擷取串流的相關資訊,確認串流已啟動:

    curl -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" https://datastream.googleapis.com/DATASTREAM_API_VERSION/PROJECT_PATH/streams/STREAM_ID
  11. 確認串流的狀態已從 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": {}
    }
  12. 使用 Fetch Errors API 擷取與串流相關的任何錯誤。

    1. 在提示中輸入下列指令:

      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
    2. 確認您看到下列幾行程式碼:

        {
          "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
        }
        

    3. 在提示中輸入下列指令:

      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
    4. 確認您看到下列幾行程式碼:

        {
          "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"
          }
        }
        

  13. 暫停串流。方法如下:

    1. 變更 UPDATE 變數。在提示中輸入下列指令:

      UPDATE="{\"state\":\"PAUSED\"}"
    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
  14. 確認您看到下列程式碼行。

    {
      "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
    }
  15. 擷取串流的相關資訊,確認串流已暫停。

    curl -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" https://datastream.googleapis.com/DATASTREAM_API_VERSION/PROJECT_PATH/streams/STREAM_ID
  16. 確認串流的狀態已從 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": {}
    }
  17. 繼續播放暫停的串流。方法如下:

    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
  18. 確認您看到下列程式碼行。

    {
      "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
    }
  19. 幾秒後,擷取串流的相關資訊,確認串流已再次執行。

    curl -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" https://datastream.googleapis.com/DATASTREAM_API_VERSION/PROJECT_PATH/streams/STREAM_ID
  20. 確認串流的狀態已從 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 檔案格式。
  1. 前往 Cloud Storage 的「Storage browser」(儲存空間瀏覽器) 頁面。

    前往 Storage 瀏覽器頁面

  2. 按一下包含 bucket 的連結。

  3. 如果「OBJECTS」分頁未啟用,請點選該分頁。

  4. 依序點選「root」資料夾和「tutorial」資料夾。

  5. 確認您看到代表來源 Oracle 資料庫 ROOT 結構定義資料表的資料夾。

  6. 按一下其中一個資料表資料夾,然後逐步向下鑽研,直到看到與資料表相關聯的資料。

  7. 按一下代表資料的檔案,然後點選「下載」

  8. 在 Avro 工具 (例如 Avro Viewer) 中開啟這個檔案,確認內容可讀。這表示 Datastream 也將資料轉換為 Avro 檔案格式。

清除所用資源

完成本教學課程後,您可以清除在 Datastream 上建立的資源,這樣資源就不會占用配額,您日後也無須為其付費。下列各節將說明如何刪除或停用這些資源。

刪除專案

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

如要刪除專案:

  1. In the Google Cloud console, go to the Manage resources page.

    Go to Manage resources

  2. In the project list, select the project that you want to delete, and then click Delete.
  3. In the dialog, type the project ID, and then click Shut down to delete the project.

刪除 Cloud Storage 目標值區

  1. 在 Cloud Storage 的左側導覽匣中,按一下「瀏覽器」項目。

  2. 勾選值區左側的核取方塊,然後按一下「DELETE」(刪除)

  3. 在「Delete bucket?」(刪除 bucket 嗎?) 視窗中,於文字欄位輸入 bucket 名稱,然後按一下「CONFIRM」(確認)

刪除串流

  1. 確認 Cloud Shell 應用程式已啟用。

  2. 在提示中輸入下列指令:

    curl -X DELETE -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" https://datastream.googleapis.com/DATASTREAM_API_VERSION/PROJECT_PATH/streams/STREAM_ID
  3. 確認您看到下列幾行程式碼:

    {
      "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
    }
  4. 確認串流已刪除。在提示中輸入下列指令:

    curl -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" https://datastream.googleapis.com/DATASTREAM_API_VERSION/PROJECT_PATH/streams
  5. 確認系統傳回空值的 {} 值。這表示 Datastream 中已沒有任何串流,您建立的串流也已刪除。

刪除連線設定檔

  1. 刪除來源 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
  2. 確認您看到下列幾行程式碼:

    {
      "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
    }
  3. 刪除 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
  4. 確認您看到下列幾行程式碼:

    {
      "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
    }
  5. 確認兩個連線設定檔都已刪除。在提示中輸入下列指令:

    curl -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" https://datastream.googleapis.com/DATASTREAM_API_VERSION/PROJECT_PATH/connectionProfiles
  6. 確認系統傳回空值的 {} 值。這表示 Datastream 中已沒有任何連線設定檔,您建立的設定檔也已刪除。

後續步驟

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