Datastream API を使用する

概要

Datastream には、プライベート接続構成、接続プロファイル、ストリームをプログラムで管理するための REST API が用意されています。REST API は、プライベート接続構成、接続プロファイル、ストリームの作成と管理に関連するリソースによって定義されます。すべてのリソースとそのメソッドの詳細については、Datastream API リファレンスをご覧ください。

Datastream REST API に直接リクエストを送信する場合、正しい形式のリクエストを作成して、認証済みユーザーとしてリクエストを承認し、返されたレスポンスを処理する必要があります。このドキュメントのタスクの多くで、cURL を使用した API の例が紹介されています。

API の使用例については、Datastream API リファレンスでリクエストのページをご覧ください。各ページには、複数のプログラミング言語で API を呼び出す例、正しい形式のリクエストの内容と、レスポンスで返されることが予想される内容を理解するのに役立つ、リクエスト固有の Explorer が含まれています。

次のいずれかの方法でインスタンスを管理する場合も、Datastream API を間接的に使用しています。

Google Cloud CLI: インスタンスの操作に使用できるコマンドラインインターフェース（CLI）。
Google Cloud Console: グラフィカルなウェブインターフェース。

これらの方法、特に Google Cloud Console を使用するメリットは、プライベート接続構成、接続プロファイル、ストリームを（ユースケースに応じて）非常に簡単に管理できることです。Datastream をこれから使い始める場合は、REST API を直接操作する前に、まずはこれらのツールのいずれかから始めることをおすすめします。

API を有効にする

Datastream API を使用するには、以下の手順で有効にする必要があります。

Console

Datastream API を有効にします。
プロジェクトを選択します。
[続行] を選択します。

gcloud

次のコマンドを入力して、Google Cloud プロジェクトのプロジェクト ID を表示します。
```
gcloud projects list
```
デフォルトプロジェクトを設定します。
```
gcloud config set project YOUR_PROJECT_ID
```

Datastream API を有効にします。

gcloud services enable datastream.googleapis.com

権限

Datastream API を使用するには、必要な権限が必要です。これらの権限には次のものがあります。

Datastream 管理者: この権限を持つユーザーは、プライベート接続構成、接続プロファイル、ストリームの管理に使用される Datastream のすべてのリソースにアクセスできます。
Datastream 閲覧者: この権限があれば、ユーザーは Datastream のプライベート接続構成、接続プロファイル、ストリームに読み取り専用でアクセスできます。

Google Cloud には Identity and Access Management（IAM）機能があり、特定の Google Cloud リソースに対するアクセス権を詳細に設定できるため、他のリソースへの不要なアクセスを防ぐことができます。Google Cloud Console、API の IAM メソッド、Google Cloud SDK を使用して Datastream の権限を取得、設定できます。詳細については、リソースへのアクセス権の付与、変更、取り消しをご覧ください。

API の例

Datastream API と cURL をあわせて使用する例は、Datastream ドキュメントの次のページで確認できます。

ファイルから JSON データを指定する

cURL で API を使用する場合は、コマンドラインを使用してプロパティ値を指定します。パスワードやセキュリティキーなどの機密性の高い値を扱う場合は、コマンドラインで指定するとセキュリティ上のリスクが生じます。セキュリティを強化するには、API 呼び出しの JSON データを含むファイルを作成し、コマンドラインでファイルのパスを指定します。

ファイルから JSON データを cURL API 呼び出しに指定するには、次を行います。

--data フィールドの単一引用符で囲まれたすべてを含むファイルを作成します。

中かっこは含めますが、単一引用符は含めません。

コマンドラインで、@ 文字が前に付いたファイルへのパスを --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 Discovery Service は、Google API を見つけるために使用できるサービスです。たとえば、Google APIs Explore ツールを使うときに Discovery Service を使用しています。

Discovery Service では、Datastream は「datastream」として表されます（例: https://datastream.googleapis.com/$discovery/rest?version=v1）。