Menghubungkan ke Cloud SQL

Sebagai administrator BigQuery, Anda dapat membuat koneksi untuk mengakses data Cloud SQL. Koneksi ini memungkinkan analis data untuk membuat kueri data di Cloud SQL. Untuk terhubung ke Cloud SQL, Anda harus mengikuti langkah-langkah berikut:

1. Buat koneksi Cloud SQL
2. Berikan akses ke Agen Layanan Koneksi BigQuery.

Sebelum memulai

1. Pilih project yang berisi database Cloud SQL.
   

   Buka pemilih project

2. Aktifkan BigQuery Connection API.
   

   Aktifkan API

3. Pastikan instance Cloud SQL memiliki koneksi IP publik atau koneksi pribadi:
   

   • Untuk mengamankan instance Cloud SQL, Anda dapat menambahkan konektivitas IP publik tanpa alamat yang sah. Hal ini membuat instance tidak dapat diakses dari internet publik tetapi dapat diakses oleh kueri dari BigQuery.

   • Untuk mengizinkan BigQuery mengakses data Cloud SQL melalui koneksi pribadi, konfigurasikan konektivitas IP pribadi untuk instance Cloud SQL baru atau yang sudah ada, lalu pilih Jalur pribadi untuk layanan Google Cloud. Layanan ini menggunakan jalur langsung internal, bukan alamat IP pribadi di dalam Virtual Private Cloud.

4. Untuk mendapatkan izin yang diperlukan untuk membuat koneksi Cloud SQL, 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 ke project, folder, dan organisasi.

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

Membuat koneksi Cloud SQL

Sebagai praktik terbaik, gunakan koneksi untuk menangani kredensial database saat Anda terhubung ke Cloud SQL. Koneksi dienkripsi dan disimpan dengan aman di layanan koneksi BigQuery. Jika kredensial pengguna valid untuk data lain di sumber, Anda dapat menggunakan kembali koneksi. Misalnya, Anda mungkin dapat menggunakan satu koneksi untuk membuat kueri beberapa database yang berada dalam instance Cloud SQL yang sama.

Pilih salah satu opsi berikut untuk membuat koneksi Cloud SQL:

Konsol

1. Buka halaman BigQuery.

   Buka BigQuery

2. Di panel Penjelajah, klik Tambahkan data.

3. Pada dialog Tambahkan data, klik Koneksi ke sumber data eksternal:

4. Di dialog Sumber data eksternal, masukkan informasi berikut:

   • Untuk Jenis koneksi, pilih jenis sumber, misalnya MySQL atau Postgres.
   • Untuk ID Koneksi, masukkan ID untuk resource koneksi. Huruf, angka, dan garis bawah diperbolehkan. Contoh, bq_sql_connection.
   • Untuk Lokasi data, pilih lokasi (atau region) BigQuery yang kompatibel dengan region sumber data eksternal Anda.
   • Opsional: Untuk Nama yang cocok, 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.
   • Opsional: Enkripsi Jika Anda ingin menggunakan kunci enkripsi yang dikelola pelanggan (CMEK) untuk mengenkripsi kredensial, pilih Kunci enkripsi yang dikelola pelanggan (CMEK), lalu pilih kunci yang dikelola pelanggan. Jika tidak, kredensial Anda akan dilindungi oleh kunci default milik Google dan dikelola Google.
   • Jika Anda memilih Cloud SQL MySQL atau Postgres untuk jenis koneksi, untuknama koneksi Cloud SQL, masukkan nilai lengkap nama instance Cloud SQL, biasanya dalam format project-id:location-id:instance-id. Anda dapat menemukan ID instance di halaman detail instance Cloud SQL yang ingin dikueri.
   • Untuk Nama database, masukkan nama database.
   • Untuk Nama pengguna database, masukkan nama pengguna untuk database.

   • Untuk Sandi database, masukkan sandi untuk database.

     • Opsional: Untuk melihat sandi, klik Tampilkan sandi.
     Catatan: Jika kredensial pengguna yang sama valid untuk database lain di sumber data eksternal, pengguna tersebut dapat membuat kueri database tersebut melalui resource koneksi yang sama.

5. Klik Buat koneksi.

6. Klik Buka koneksi.

7. Di panel Info koneksi, salin ID akun layanan untuk digunakan pada langkah berikut.

bq

Masukkan perintah bq mk dan berikan flag koneksi: --connection. Flag berikut juga diperlukan:

• --connection_type
• --properties
• --connection_credential
• --project_id
• --location

Flag berikut bersifat opsional:

• --display_name Nama yang cocok untuk koneksi.
• --description Deskripsi koneksi.

connection_id adalah parameter opsional yang dapat ditambahkan sebagai argumen terakhir dari perintah yang digunakan untuk penyimpanan secara internal. Jika ID koneksi tidak diberikan, ID unik akan dibuat secara otomatis. connection_id dapat berisi huruf, angka, dan garis bawah.

    bq mk --connection --display_name='friendly name' --connection_type=TYPE \
      --properties=PROPERTIES --connection_credential=CREDENTIALS \
      --project_id=PROJECT_ID --location=LOCATION \
      CONNECTION_ID

Ganti kode berikut:

• TYPE: jenis sumber data eksternal.
• PROPERTIES: parameter untuk koneksi yang dibuat dalam format JSON. Untuk contoh: --properties='{"param":"param_value"}'. Untuk membuat resource koneksi, Anda harus menyediakan parameter instanceID, database, dan type.
• CREDENTIALS: parameter username dan password.
• PROJECT_ID: project ID Anda.
• LOCATION: region tempat instance Cloud SQL Anda berada.
• CONNECTION_ID: ID koneksi.

Misalnya, perintah berikut membuat resource koneksi baru bernama my_new_connection (nama yang cocok: "My new connection") dalam sebuah project dengan ID federation-test.

bq mk --connection --display_name='friendly name' --connection_type='CLOUD_SQL' \
  --properties='{"instanceId":"federation-test:us-central1:mytestsql","database":"mydatabase","type":"MYSQL"}' \
  --connection_credential='{"username":"myusername", "password":"mypassword"}' \
  --project_id=federation-test --location=us my_connection_id

API

Dalam BigQuery Connection API, Anda dapat memanggil CreateConnection dalam ConnectionService untuk membuat instance koneksi. Lihat halaman library klien untuk detail selengkapnya.

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 informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

import com.google.cloud.bigquery.connection.v1.CloudSqlCredential;
import com.google.cloud.bigquery.connection.v1.CloudSqlProperties;
import com.google.cloud.bigquery.connection.v1.Connection;
import com.google.cloud.bigquery.connection.v1.CreateConnectionRequest;
import com.google.cloud.bigquery.connection.v1.LocationName;
import com.google.cloud.bigqueryconnection.v1.ConnectionServiceClient;
import java.io.IOException;

// Sample to create a connection with cloud MySql database
public class CreateConnection {

  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";
    String database = "MY_DATABASE";
    String instance = "MY_INSTANCE";
    String instanceLocation = "MY_INSTANCE_LOCATION";
    String username = "MY_USERNAME";
    String password = "MY_PASSWORD";
    String instanceId = String.format("%s:%s:%s", projectId, instanceLocation, instance);
    CloudSqlCredential cloudSqlCredential =
        CloudSqlCredential.newBuilder().setUsername(username).setPassword(password).build();
    CloudSqlProperties cloudSqlProperties =
        CloudSqlProperties.newBuilder()
            .setType(CloudSqlProperties.DatabaseType.MYSQL)
            .setDatabase(database)
            .setInstanceId(instanceId)
            .setCredential(cloudSqlCredential)
            .build();
    Connection connection = Connection.newBuilder().setCloudSql(cloudSqlProperties).build();
    createConnection(projectId, location, connectionId, connection);
  }

  static void createConnection(
      String projectId, String location, String connectionId, Connection connection)
      throws IOException {
    try (ConnectionServiceClient client = ConnectionServiceClient.create()) {
      LocationName parent = LocationName.of(projectId, location);
      CreateConnectionRequest request =
          CreateConnectionRequest.newBuilder()
              .setParent(parent.toString())
              .setConnection(connection)
              .setConnectionId(connectionId)
              .build();
      Connection response = client.createConnection(request);
      System.out.println("Connection created successfully :" + response.getName());
    }
  }
}

Memberikan akses ke agen layanan

Agen layanan akan otomatis dibuat saat Anda membuat koneksi pertama ke Cloud SQL dalam project. Nama agen layanan adalah BigQuery Connection Service Agent. Untuk mendapatkan ID agen layanan, lihat detail koneksi Anda. ID agen layanan memiliki format berikut:

service-PROJECT_NUMBER@gcp-sa-bigqueryconnection..

Untuk terhubung ke Cloud SQL, Anda harus memberikan akses hanya baca kepada koneksi yang baru tersebut ke Cloud SQL sehingga BigQuery dapat mengakses file atas nama pengguna. Agen layanan harus memiliki izin berikut:

• cloudsql.instances.connect
• cloudsql.instances.get

Anda dapat memberikan peran IAM Klien Cloud SQL (roles/cloudsql.client) ke agen layanan yang terkait dengan koneksi, yang menetapkan izin ini. Anda dapat melewati langkah-langkah berikut jika agen layanan sudah memiliki izin yang diperlukan.

Konsol

1. Buka halaman IAM & Admin.

   Buka IAM & Admin

2. Klik Berikan Akses.

   Dialog Add principals akan terbuka.

3. Di kolom Tambahkan akun utama, masukkan nama agen layanan Agen Layanan Koneksi BigQuery atau ID agen layanan yang diambil dari informasi koneksi.

4. Pada kolom Pilih peran, pilih Cloud SQL, lalu pilih Cloud SQL Client.

5. Klik Simpan.

gcloud

Gunakan perintah gcloud projects add-iam-policy-binding:

gcloud projects add-iam-policy-binding PROJECT_ID --member=serviceAccount:SERVICE_AGENT_ID --role=roles/cloudsql.client

Berikan nilai berikut:

• PROJECT_ID: ID project Google Cloud Anda.
• SERVICE_AGENT_ID: ID agen layanan yang diambil dari informasi koneksi.

Catatan: Untuk informasi lebih lanjut tentang cara memberikan dan mencabut peran IAM, lihat Mengelola akses ke project, folder, dan organisasi.

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

1. Buka halaman BigQuery.

   Buka BigQuery

   Koneksi dicantumkan dalam project Anda, dalam grup yang disebut Koneksi eksternal.

2. Di panel Penjelajah, klik nama project Anda > Koneksi eksternal > koneksi.

3. 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 Simpan.

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 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:[e-mail]")
              .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 melakukan kueri data Cloud SQL.