Menghubungkan ke Spanner

Sebagai administrator BigQuery, Anda dapat membuat koneksi untuk mengakses data Spanner. Koneksi ini memungkinkan analisis data untuk mengkueri data di Spanner.

Sebelum memulai

Aktifkan BigQuery Connection API.

Mengaktifkan API
Untuk mendapatkan izin yang diperlukan untuk terhubung ke Spanner, minta administrator untuk memberi Anda peran IAM BigQuery Connection Admin (roles/bigquery.connectionAdmin) pada project. Untuk mengetahui informasi selengkapnya tentang cara memberikan peran, lihat Mengelola akses.

Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.

Membuat koneksi Spanner

Pilih salah satu opsi berikut:

Konsol

Buka halaman BigQuery.

Buka BigQuery
Di menu Add data , pilih Connection to external data source.
Di panel External data source, masukkan informasi berikut:
- Untuk Connection type, pilih Spanner.
- Untuk Connection ID, masukkan ID untuk resource koneksi. Huruf, angka, dan garis bawah diperbolehkan.
- Untuk Data location, pilih lokasi (atau region) BigQuery yang kompatibel dengan region sumber data eksternal Anda.
- Opsional: Untuk Friendly name, masukkan nama yang mudah digunakan untuk koneksi, seperti My connection resource. Nama yang cocok dapat berupa nilai apa pun yang membantu Anda mengidentifikasi resource koneksi jika perlu mengubahnya nanti.
- Opsional: Untuk Description, masukkan deskripsi untuk resource koneksi ini.
- Untuk Database name, masukkan nama database Spanner dalam format berikut: "projects/PROJECT_ID/instances/INSTANCE/databases/DATABASE"
- Opsional: Untuk melakukan operasi baca paralel, pilih Read data in parallel. Spanner dapat membagi kueri tertentu menjadi bagian-bagian yang lebih kecil, atau partisi, dan mengambil partisi secara paralel. Untuk informasi selengkapnya, lihat Membaca data secara paralel dalam dokumentasi Spanner. Opsi ini terbatas untuk kueri yang operator pertamanya dalam rencana eksekusi adalah operator union terdistribusi. Kueri lainnya menampilkan error. Untuk melihat rencana eksekusi kueri untuk kueri Spanner, lihat Memahami cara Spanner menjalankan kueri.
- Opsional: Untuk Peran database, masukkan nama peran database Spanner. Jika tidak kosong, koneksi ini mengkueri Spanner menggunakan peran database ini secara default. Pengguna kontrol akses terperinci Spanner yang mengirimkan kueri melalui koneksi ini harus telah diberi akses ke peran ini oleh administrator mereka, dan peran database harus memiliki SELECT hak istimewa pada semua objek skema yang ditentukan dalam kueri eksternal. Untuk informasi tentang kontrol akses yang lebih mendetail, lihat Tentang kontrol akses terperinci.
- Opsional: Untuk mengaktifkan Data Boost, pilih Data Boost. Dengan Data Boost, Anda dapat menjalankan kueri analisis dan ekspor data dengan dampak yang nyaris nol terhadap workload yang ada di instance BigQuery yang disediakan. Untuk mengaktifkan Data Boost, pilih Data Boost dan Read data in paralel.
Klik Create connection.

bq

Untuk membuat koneksi, gunakan perintah bq mk dengan flag --connection.

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

Ganti kode berikut:

PROPERTIES: objek JSON dengan kolom berikut:
- "database": database Spanner untuk koneksi
  
  Tentukan sebagai string dengan format berikut:"projects/PROJECT_ID/instances/INSTANCE/databases/DATABASE".
- "use_parallelism": (Opsional) jika true, koneksi ini akan melakukan operasi baca paralel
  
  Nilai defaultnya adalah false. Spanner dapat membagi kueri tertentu menjadi bagian-bagian yang lebih kecil, atau partisi, dan mengambil partisi secara paralel. Untuk informasi selengkapnya, lihat Membaca data secara paralel dalam dokumentasi Spanner. Opsi ini terbatas untuk kueri yang operator pertamanya dalam rencana eksekusi adalah operator union terdistribusi. Kueri lainnya menampilkan error. Untuk melihat rencana eksekusi kueri untuk kueri Spanner, lihat Memahami cara Spanner menjalankan kueri.
- "database_role": (Opsional) Jika tidak kosong, koneksi ini mengkueri Spanner menggunakan peran database ini secara default. Pengguna kontrol akses terperinci Spanner yang mengirimkan kueri melalui koneksi ini harus telah diberi akses ke peran ini oleh administrator mereka, dan peran database harus memiliki SELECT hak istimewa pada semua objek skema yang ditentukan dalam kueri eksternal.
  
  Jika tidak ditentukan, koneksi akan melakukan autentikasi dengan peran IAM yang telah ditetapkan untuk Spanner, dan kueri utama yang menjalankan koneksi ini harus telah diberi peran IAM roles/spanner.databaseReader.
  
  Untuk informasi tentang kontrol akses yang lebih mendetail, lihat Tentang kontrol akses terperinci.
- "useDataBoost": (Opsional) Jika true, koneksi ini memungkinkan pengguna menggunakan Data Boost. Data Boost memungkinkan pengguna menjalankan kueri gabungan dalam kapasitas komputasi yang terpisah, independen, dan berbeda dari instance yang disediakan agar tidak memengaruhi beban kerja yang ada. Untuk mengaktifkan Data Boost, tetapkan "useDataBoost" ke true dan "use_parallelism" ke true.
  
  Untuk menggunakan Data Boost, kueri utama yang menjalankan dengan koneksi ini harus sudah diberi izin spanner.databases.useDataBoost. Izin ini disertakan secara default dalam peran roles/spanner.admin dan roles/spanner.databaseAdmin.
LOCATION: lokasi BigQuery yang kompatibel dengan region sumber data eksternal Anda.
CONNECTION_ID: ID untuk resource koneksi

ID koneksi dapat berisi huruf, angka, dan garis bawah. Jika Anda tidak memberikan ID koneksi, BigQuery akan otomatis menghasilkan ID unik.

Contoh berikut membuat resource koneksi baru bernama 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

Panggil metode CreateConnection dalam layanan ConnectionService.

Berbagi koneksi dengan pengguna

Anda dapat memberikan peran berikut untuk mengizinkan pengguna membuat kueri data dan mengelola koneksi:

roles/bigquery.connectionUser: memungkinkan pengguna menggunakan koneksi untuk terhubung dengan sumber data eksternal dan menjalankan kueri pada sumber data tersebut.
roles/bigquery.connectionAdmin: memungkinkan pengguna mengelola koneksi.

Untuk informasi selengkapnya tentang peran dan izin IAM di BigQuery, baca Peran dan izin bawaan.

Pilih salah satu opsi berikut:

Konsol

Buka halaman BigQuery.

Buka BigQuery

Koneksi dicantumkan dalam project Anda, dalam grup yang disebut Koneksi eksternal.
Di panel Penjelajah, klik nama project Anda > Koneksi eksternal > koneksi.
Di panel Detail, klik Bagikan untuk membagikan koneksi. Kemudian, lakukan hal berikut:
1. Dalam dialog Izin koneksi, bagikan koneksi dengan akun utama lain dengan menambahkan atau mengedit akun utama.
2. Klik Save.

bq

Anda tidak dapat berbagi koneksi dengan alat command line bq. Untuk berbagi koneksi, gunakan konsol Google Cloud atau metode BigQuery Connections API untuk melakukannya.

API

Gunakan metode projects.locations.connections.setIAM di bagian referensi REST API Koneksi BigQuery, dan berikan instance resource policy.

Java

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Java di Panduan memulai BigQuery menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi BigQuery Java API.

Untuk melakukan autentikasi ke BigQuery, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

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");
    }
  }
}

Langkah selanjutnya

Pelajari berbagai jenis koneksi.
Pelajari cara mengelola koneksi.
Pelajari kueri gabungan.
Pelajari cara membuat kueri data Spanner.