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 を有効にします。
プロジェクトを選択します。
[Continue（続行）] を選択します。

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

cURL で Datastream API を使用する例については、Datastream のドキュメントの次のページをご覧ください。

ファイルから JSON データを提供する

API と cURL を併用する場合は、コマンドラインを使用してプロパティ値を指定します。パスワードやセキュリティキーなどの機密性の高い値を使用する場合、コマンドラインでこれらの値を指定すると、セキュリティリスクが発生します。セキュリティを強化するには、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）。