GCP Dataform の REST API を使ってみた


GCP Dataform は CLI コマンドが存在しないため、REST API を使用して Dataform へアクセスし、SQLを実行してみました。

https://cloud.google.com/dataform/reference/rest

# 準備
事前準備として以下を完了させておく必要があります。

- [Dataform API 有効化](https://cloud.google.com/dataform/docs/quickstart-create-workflow?hl=ja#before-you-begin)
- [Dataform の IAM ロール付与](https://cloud.google.com/dataform/docs/quickstart-create-workflow?hl=ja#required-roles)
- [Dataform リポジトリ作成](https://cloud.google.com/dataform/docs/quickstart-create-workflow?hl=ja#create-repository)
- [Dataform ワークスペース初期化](https://cloud.google.com/dataform/docs/quickstart-create-workflow?hl=ja#create-workspace)

# やってみた

## リポジトリ一覧を取得
Dataform リポジトリ一覧を取得してみます。[エンドポイント](https://cloud.google.com/dataform/reference/rest/v1beta1/projects.locations.repositories/list)は下記となります。

```
https://dataform.googleapis.com/v1beta1/projects/<プロジェクトID>/locations/<リージョン>/repositories
```

curlでアクセスすると、Dataform リポジトリ一覧が取得できました。

```
% curl https://dataform.googleapis.com/v1beta1/projects/example-project/locations/asia-northeast1/repositories \
  --header "Authorization: Bearer $(gcloud auth print-access-token)"
{
  "repositories": [
    {
      "name": "projects/example-project/locations/asia-northeast1/repositories/dataform_sample_repository",
      "gitRemoteSettings": {
        "url": "https://github.com/my-repository/ddl_sample.git",
        "defaultBranch": "main",
        "authenticationTokenSecretVersion": "projects/xxxxxxxx/secrets/github-access-token/versions/latest"
      }
    }
  ]
}
```

## ワークスペース一覧を取得
Dataform リポジトリ配下のワークスペース一覧を取得してみます。[エンドポイント](https://cloud.google.com/dataform/reference/rest/v1beta1/projects.locations.repositories.workspaces/list)は下記となります。

```
https://dataform.googleapis.com/v1beta1/projects/<プロジェクトID>/locations/<リージョン>/repositories/<リポジトリ>/workspaces
```

curlでアクセスすると、ワークスペース一覧が取得できました。

```
% curl https://dataform.googleapis.com/v1beta1/projects/example-project/locations/asia-northeast1/repositories/dataform_sample_repository/workspaces \
   --header "Authorization: Bearer $(gcloud auth print-access-token)"
{
  "workspaces": [
    {
      "name": "projects/example-project/locations/asia-northeast1/repositories/dataform_sample_repository/workspaces/first_workspace"
    }
  ]
}

```

## Dataform コードのコンパイルを実行する

SQL ワークフローを実行するために、Dataform はコードを SQL にコンパイルして、コンパイル結果を作成します。
そのコンパイル結果を作成するための[エンドポイント](https://cloud.google.com/dataform/reference/rest/v1beta1/projects.locations.repositories.compilationResults/create)は下記となります。

```
https://dataform.googleapis.com/v1beta1/projects/<プロジェクトID>/locations/<リージョン>/repositories/<リポジトリ>/compilationResults
```

curlでアクセスすると、コンパイル結果が取得できました。
なお、下記の --data にある `codeCompilationConfig` は、コンパイル結果で使用するコンパイル変数で、これを使用して、条件付きでテーブルを実行できます。

```
% curl https://dataform.googleapis.com/v1beta1/projects/example-project/locations/asia-northeast1/repositories/dataform_sample_repository/compilationResults \
  --header "Authorization: Bearer $(gcloud auth print-access-token)" \
  --header "Content-Type: application/json" \
  --data '{"codeCompilationConfig":{"defaultDatabase":"example-project"},"git_commitish":"xxxxxxxxxxxxxxxxxxxxx"}'
{
  "name": "projects/example-project/locations/asia-northeast1/repositories/dataform_sample_repository/compilationResults/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
  "gitCommitish": "xxxxxxxxxxxxxxxxxxxxx",
  "codeCompilationConfig": {
    "defaultDatabase": "example-project",
    "defaultSchema": "dataform",
    "assertionSchema": "dataform_assertions",
    "defaultLocation": "asia-northeast1"
  },
  "dataformCoreVersion": "2.0.1",
  "resolvedGitCommitSha": "xxxxxxxxxxxxxxxxxxxxx"
}
```

## コンパイルした SQL を実行する

先ほどコンパイルした SQL を実行するための[エンドポイント](https://cloud.google.com/dataform/reference/rest/v1beta1/projects.locations.repositories.workflowInvocations/create)は下記となります。

```
https://dataform.googleapis.com/v1beta1/projects/<プロジェクトID>/locations/<リージョン>/repositories/<リポジトリ>/workflowInvocations
```

curlでアクセスすると、SQL 実行結果が取得できました。
なお、下記の --data にある `invocationConfig` で実行対象の SQL を指定できます。

```
% curl "https://dataform.googleapis.com/v1beta1/projects/example-project/locations/asia-northeast1/repositories/dataform_sample_repository/workflowInvocations" \
  --header "Authorization: Bearer $(gcloud auth print-access-token)" \
  --header 'Content-Type: application/json' \
  --data '{"compilationResult":"<コンパイル結果のname>","invocationConfig":{"includedTargets":[{"database":"example-project","schema":"dataform","name":"create_table_sample"}]}}'
{
  "name": "projects/example-project/locations/asia-northeast1/repositories/dataform_sample_repository/workflowInvocations/xxxxxxxxxx-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "compilationResult": "<コンパイル結果のname>",
  "invocationConfig": {
    "includedTargets": [
      {
        "database": "example-project",
        "schema": "dataform",
        "name": "create_table_sample"
      }
    ]
  },
  "state": "RUNNING",
  "invocationTiming": {
    "startTime": "2023-08-01T12:34:56.123456Z"
  }
}
```