Spanner に接続する

BigQuery 管理者は、接続を作成して Spanner データにアクセスできます。この接続により、データ アナリストは Spanner のデータにクエリを実行できるようになります。

始める前に

Spanner 接続を作成する

次のオプションのいずれかを選択します。

コンソール

  1. [BigQuery] ページに移動します。

    [BigQuery] に移動

  2. [データを追加] メニューで [Connection to external data source] を選択します。

  3. [外部データソース] ペインで、次の情報を入力します。

    • [接続タイプ] で [Spanner] を選択します。
    • [接続 ID] に、接続リソースの識別子を入力します。文字、数字、アンダースコアを使用できます。
    • [データのロケーション] で、外部データソースのリージョンと互換性のある BigQuery ロケーション（またはリージョン）を選択します。
    • （省略可）[わかりやすい名前] に、わかりやすい接続名を入力します（例: My connection resource）。後で修正が必要になった場合、わかりやすい名前だと接続リソースを簡単に識別できます。
    • （省略可）[説明] に、この接続リソースの説明を入力します。
    • [データベース名] に、Spanner データベースの名前を "projects/PROJECT_ID/instances/INSTANCE/databases/DATABASE" の形式で入力します。
    • 省略可: 同時読み取りを実行するには、[データを同時に読み込む] を選択します。Spanner は、特定のクエリをより小さな部分またはパーティションに分割し、パーティションを同時に取得します。詳細については、Spanner ドキュメントのデータを同時に読み込むをご覧ください。このオプションは、実行プランの最初の演算子が分散ユニオン演算子であるクエリに限定されます。その他のクエリではエラーが返されます。Spanner クエリのクエリ実行プランを表示するには、Spanner がクエリを実行する方法を理解するをご覧ください。
    • 省略可: [データベース ロール] に、Spanner データベース ロールの名前を入力します。空でない場合、この接続はデフォルトでこのデータベース ロールを使用して Spanner にクエリを実行します。この接続を介してクエリを送信するユーザーに Spanner のきめ細かいアクセス制御が設定されている場合、このロールへのアクセス権が管理者によってユーザーに付与されている必要があります。また、データベース ロールには、外部クエリで指定されているすべてのオブジェクト スキーマに対する SELECT 権限が必要です。きめ細かなアクセス制御については、きめ細かなアクセス制御についてをご覧ください。
    • 省略可: Data Boost を有効にするには、[Data Boost] を選択します。Data Boost を使用すると、プロビジョニングされた BigQuery インスタンスの既存のワークロードへの影響がほぼゼロの、分析クエリとデータ エクスポートを実行できます。Data Boost を有効にするには、[Data Boost] と [データを同時に読み込む] を選択します。

  4. [接続を作成] をクリックします。

bq

接続を作成するには、--connection フラグを指定して bq mk コマンドを使用します。

bq mk --connection \
    --connection_type=CLOUD_SPANNER \
    --properties='PROPERTIES' \
    --location=LOCATION \
    --display_name='FRIENDLY_NAME' \
    --description 'DESCRIPTION' \
    CONNECTION_ID

次のように置き換えます。

  • PROPERTIES: 次のフィールドを持つ JSON オブジェクト

    • "database": 接続用の Spanner データベース

      "projects/PROJECT_ID/instances/INSTANCE/databases/DATABASE" の形式の文字列として指定します。

    • "use_parallelism": （省略可）true の場合、この接続は同時読み取りを実行します。

      デフォルト値は false です。Spanner は、特定のクエリをより小さな部分またはパーティションに分割し、パーティションを同時に取得します。詳細については、Spanner ドキュメントのデータを同時に読み込むをご覧ください。このオプションは、実行プランの最初の演算子が分散ユニオン演算子であるクエリに限定されます。その他のクエリではエラーが返されます。Spanner クエリのクエリ実行プランを表示するには、Spanner がクエリを実行する方法を理解するをご覧ください。

    • "database_role": （省略可）空でない場合、この接続は、デフォルトでこのデータベース ロールを使用して Spanner にクエリを実行します。この接続を介してクエリを送信するユーザーに Spanner のきめ細かいアクセス制御が設定されている場合、このロールへのアクセス権が管理者によってユーザーに付与されている必要があります。また、データベース ロールには、外部クエリで指定されているすべてのオブジェクト スキーマに対する SELECT 権限が必要です。

      指定されていない場合、接続は Spanner に対する IAM 事前定義ロールで認証されます。この接続でクエリを実行するプリンシパルには、roles/spanner.databaseReader IAM ロールが付与されている必要があります。

      きめ細かなアクセス制御については、きめ細かなアクセス制御についてをご覧ください。

    • "useDataBoost": （省略可）true の場合、この接続によりユーザーは Data Boost を使用できます。Data Boost を使用すると、ユーザーは、プロビジョニングされたインスタンスとは異なる独立したコンピューティング容量で連携クエリを実行し、既存のワークロードへの影響を回避できます。Data Boost を有効にするには、"useDataBoost" を true に、"use_parallelism" を true に設定します。

      Data Boost を使用するには、この接続でクエリを実行するプリンシパルに spanner.databases.useDataBoost 権限が付与されている必要があります。この権限は、デフォルトで roles/spanner.admin ロールと roles/spanner.databaseAdmin ロールに含まれています。

  • LOCATION: 外部データソースのリージョンと互換性がある BigQuery のロケーション。

  • CONNECTION_ID: 接続リソースの識別子

    接続 ID には、文字、数字、アンダースコアを使用できます。接続 ID を指定しない場合、BigQuery は自動的に一意の ID を生成します。

    次の例では、my_connection_id という名前の新しい接続リソースを作成します。

    bq mk --connection \
  --connection_type='CLOUD_SPANNER' \
  --properties='{"database":"projects/my_project/instances/my_instance/databases/database1"}' \
  --project_id=federation-test \
  --location=us \
  my_connection_id

API

ConnectionService サービス内で CreateConnection メソッドを呼び出します。

ユーザーと接続を共有する

次のロールを付与することで、ユーザーがデータをクエリして接続を管理できます。

  • roles/bigquery.connectionUser: ユーザーが接続を使用して外部データソースに接続し、クエリを実行できるようにします。

  • roles/bigquery.connectionAdmin: ユーザーが接続を管理できるようにします。

BigQuery での IAM のロールと権限について詳しくは、事前定義ロールと権限をご覧ください。

次のオプションのいずれかを選択します。

コンソール

  1. [BigQuery] ページに移動します。

    [BigQuery] に移動

    接続は、プロジェクトで外部接続というグループに一覧表示されます。

  2. [エクスプローラ] ペインで、[プロジェクト名] > [外部接続] > [接続] の順にクリックします。

  3. [詳細] ペインで、[共有] をクリックして接続を共有します。次に、以下の操作を行います。

    1. [接続の権限] ダイアログで、プリンシパルを追加または編集して、他のプリンシパルと接続を共有します。

    2. [保存] をクリックします。

bq

bq コマンドライン ツールを使用して接続を共有することはできません。接続を共有するには、Google Cloud コンソールまたは BigQuery Connections API メソッドを使用します。

API

BigQuery Connections REST API の projects.locations.connections.setIAM メソッドを使用して、policy リソースのインスタンスを指定します。

Java

このサンプルを試す前に、クライアント ライブラリを使用した BigQuery クイックスタートの Java の手順に沿って設定を行ってください。詳細については、BigQuery Java API のリファレンス ドキュメントをご覧ください。

BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証を設定するをご覧ください。

import com.google.api.resourcenames.ResourceName;
import com.google.cloud.bigquery.connection.v1.ConnectionName;
import com.google.cloud.bigqueryconnection.v1.ConnectionServiceClient;
import com.google.iam.v1.Binding;
import com.google.iam.v1.Policy;
import com.google.iam.v1.SetIamPolicyRequest;
import java.io.IOException;

// Sample to share connections
public class ShareConnection {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "MY_PROJECT_ID";
    String location = "MY_LOCATION";
    String connectionId = "MY_CONNECTION_ID";
    shareConnection(projectId, location, connectionId);
  }

  static void shareConnection(String projectId, String location, String connectionId)
      throws IOException {
    try (ConnectionServiceClient client = ConnectionServiceClient.create()) {
      ResourceName resource = ConnectionName.of(projectId, location, connectionId);
      Binding binding =
          Binding.newBuilder()
              .addMembers("group:example-analyst-group@google.com")
              .setRole("roles/bigquery.connectionUser")
              .build();
      Policy policy = Policy.newBuilder().addBindings(binding).build();
      SetIamPolicyRequest request =
          SetIamPolicyRequest.newBuilder()
              .setResource(resource.toString())
              .setPolicy(policy)
              .build();
      client.setIamPolicy(request);
      System.out.println("Connection shared successfully");
    }
  }
}

次のステップ