使用 Datastream API

Datastream 提供 REST API，可透過程式輔助方式管理私人連線設定、連線設定檔和串流。REST API 是由與建立及管理私人連線設定、連線設定檔和串流相關的資源所定義。如要進一步瞭解所有資源及其方法，請參閱 Datastream API 參考資料。

直接向 Datastream REST API 發出要求時，您必須建立正確格式的要求、以已驗證使用者的身分授權要求，並處理傳回的所有回應。本說明文件中的許多工作都提供使用 cURL 的 API 範例。

如需更多 API 使用範例，請參閱「Datastream API 參考資料」中的要求頁面。每個頁面都有以多種程式設計語言呼叫 API 的範例，以及要求專屬的 Explorer，可協助您瞭解格式正確的要求內容，以及回應的預期結果。

如果您使用下列任何一種方式管理執行個體，也間接使用了 Datastream API：

使用這些方法 (尤其是Google Cloud 控制台) 的優點是，可以大幅簡化私人連線設定、連線設定檔和串流的管理作業 (視您的用途而定)。如果您剛開始使用 Datastream，建議先使用其中一種工具，再直接使用 REST API。

啟用 API

如要使用 Datastream API，請啟用該 API：

控制台

  1. 啟用 Datastream API。
  2. 選取專案。
  3. 選取 [繼續]。

gcloud

  1. 輸入下列指令，顯示 Google Cloud專案的專案 ID：
    gcloud projects list
  2. 設定預設專案： 
    gcloud config set project YOUR_PROJECT_ID
  3. 啟用 Datastream API： 
    gcloud services enable datastream.googleapis.com

權限

您必須具備必要權限，才能使用 Datastream API。這些權限包括：

  • Datastream 管理員：具備這項權限的使用者可以存取 Datastream 的所有資源，用來管理私人連線設定、連線設定檔和串流。
  • Datastream 檢視者：具備這項權限的使用者，可以唯讀存取 Datastream 中的私人連線設定、連線設定檔和串流。

Google Cloud 提供「身分與存取權管理」(IAM) 功能，可讓您以更精細的方式授予特定 Google Cloud 資源的存取權，避免其他資源遭到未經授權者擅自存取。您可以使用 Google Cloud 控制台、API 的 IAM 方法或 Google Cloud SDK，取得及設定 Datastream 的權限。詳情請參閱「授予、變更及撤銷資源的存取權」。

API 範例

如要查看使用 cURL 呼叫 Datastream API 的範例，請參閱 Datastream 說明文件的下列頁面：

從檔案提供 JSON 資料

使用 cURL 搭配 API 時，您會透過指令列提供屬性值。如果您要處理密碼或安全金鑰等機密值，在指令列中提供這些值會造成安全風險。為提高安全性，您可以建立包含 API 呼叫 JSON 資料的檔案，並在指令列中提供該檔案的路徑。

如要從檔案提供 JSON 資料給 cURL API 呼叫，請按照下列步驟操作：

  1. 建立檔案，內含 --data 欄位中以單引號括住的所有內容。

    請加入大括號，但不要加入單引號。

  2. 在指令列中，提供檔案路徑，並在路徑前加上 @ 字元，做為 --data 參數：

    --data @<path-to-file>/<filename>

    舉例來說，如要為 MySQL 來源建立連線設定檔，可以建立名為 request.json 的檔案，並加入下列內容：

    {
  "displayName": "my MySQL connection profile",
  "mysql": {
    "host": "10.11.12.13",
    "port": 3306,
    "username": "myusername",
    "password": "mypassword"
  }
}

    接著，您會在指令列使用下列 cURL 指令：

    curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
     --header 'Content-Type: application/json' \
     --data @./request.json \
     -X POST \
     https://datastream.googleapis.com/v1/projects/myProject/locations/myLocation/connectionProfiles?connectionProfileId=myMySQLconnectionprofile

處理長時間執行的 API 呼叫

部分 API 呼叫 (例如建立物件) 可能需要一段時間才能完成。由於 API 是非同步，即使作業仍在進行中，呼叫也會立即傳回。如果後續的 API 呼叫使用新建立的物件，您必須等待第一個作業完成，才能繼續操作。

您可以使用 Datastream API 管理作業。包括：

Datastream 和 Google APIs Discovery Service

Google API 探索服務可協助您探索 Google API。舉例來說，您使用 Google APIs Explorer 工具時，就是在使用 Discovery Service。

在 Discovery Service 中，Datastream 會以「datastream」表示 (例如：https://datastream.googleapis.com/$discovery/rest?version=v1)。