使用 Datastream API

概览

Datastream 提供了一个 REST API，用于以编程方式管理您的专用连接配置、连接配置文件和数据流。REST API 由与创建和管理专用连接配置、连接配置文件和数据流关联的资源定义。如需详细了解所有资源及其方法，请查看 Datastream API 参考文档。

当直接向 Datastream REST API 发送请求时，必须创建正确的请求形式，以经过身份验证的用户的身份授权请求，并处理返回的所有响应。本文档中的许多任务提供了使用 cURL 的 API 示例。

如需查看使用 API 的更多示例，请查看 Datastream API 参考文档中的请求页面。每个页面都有用几种编程语言调用 API 的示例以及特定于请求的浏览器，以帮助您了解格式良好的请求中包含哪些内容以及响应中应该包含哪些内容。

如果使用以下任意一种方法管理实例，您也在间接使用 Datastream API：

Google Cloud CLI：可用于处理实例的命令行界面 (CLI)。
Google Cloud 控制台：图形网页界面。

使用这些方法（尤其是 Google Cloud 控制台）的优势在于，它们可以大大简化专用连接配置、连接配置文件和数据流的管理（具体取决于您的使用场景）。如果刚开始使用 Datastream，我们建议您先使用这些工具之一，然后再直接使用 REST API。

启用 API

要使用 Datastream API，您需要启用它：

控制台

启用 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 Admin：拥有此权限，用户可以获取用于管理专用连接配置、连接配置文件和数据流的所有 Datastream 资源。
Datastream Viewer：利用此权限，用户对 Datastream 中的专用连接配置、连接配置文件和数据流拥有只读权限。

Google Cloud 提供 Identity and Access Management (IAM)，可让您授予对特定 Google Cloud 资源的更细化访问权限，并防止对其他资源进行不必要的访问。您可以使用 Google Cloud Console、API 的 IAM 方法或 Google Cloud SDK 来获取和设置 Datastream 的权限。如需了解详情，请参阅授予、更改和撤消对资源的访问权限。

API 示例

您可以在 Datastream 文档的以下页面中查看将 Datastream API 与 cURL 搭配使用的示例：

通过文件提供 JSON 数据

使用 API 与 cURL 时，可以使用命令行提供属性值。如果使用的是敏感值（如密码或安全密钥），则在命令行中提供这些值会带来安全风险。为了提高安全性，您可以创建包含用于 API 调用的 JSON 数据的文件，并在命令行中提供该文件的路径。

如需通过文件向您的 cURL API 调用提供 JSON 数据，请执行以下操作：

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

然后，在命令行中使用以下 cRUL 命令：

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 APIs Discovery Service 是一项可用于发现 Google API 的服务。例如，当使用 Google APIs Explorer 工具时，您使用的是 Discovery Service。

在 Discovery Service 中，Datastream 表示为“datastream”（例如：https://datadata.googleapis.com/$discovery/rest?version=v1）。datastream