使用 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，請按照下列步驟操作：

控制台

  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 範例

您可以在 Datastream 說明文件的以下頁面中，查看使用 Datastream API 搭配 cURL 的範例：

提供檔案中的 JSON 資料

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

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

  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 API Discovery Service

Google API 探索服務可用來探索 Google API。舉例來說，當您使用 Google APIs Explorer 工具時，就會使用探索服務。

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