Kunci Cloud KMS yang dikelola pelanggan

Catatan: Fitur ini mungkin tidak tersedia saat menggunakan reservasi yang dibuat dengan edisi BigQuery tertentu. Untuk mengetahui informasi selengkapnya fitur mana saja yang diaktifkan di setiap edisi, lihat Pengantar edisi BigQuery.

Secara default, BigQuery mengenkripsi konten Anda yang disimpan dalam penyimpanan. BigQuery menangani dan mengelola enkripsi default ini untuk Anda tanpa tindakan tambahan dari Anda. Pertama, data dalam tabel BigQuery dienkripsi menggunakan kunci enkripsi data. Kemudian, kunci enkripsi data tersebut dienkripsi dengan kunci enkripsi kunci, yang dikenal sebagai enkripsi menyeluruh. Kunci enkripsi kunci tidak secara langsung mengenkripsi data Anda, tetapi digunakan untuk mengenkripsi kunci enkripsi data yang digunakan Google untuk mengenkripsi data Anda. Untuk informasi selengkapnya, lihat Cloud Key Management Service (KMS).

Jika ingin mengontrol enkripsi sendiri, Anda dapat menggunakan kunci enkripsi yang dikelola pelanggan (CMEK) untuk BigQuery. Alih-alih Google yang mengelola kunci enkripsi kunci yang melindungi data Anda, Andalah yang mengontrol dan mengelola kunci enkripsi kunci di Cloud KMS. Dokumen ini memberikan detail tentang teknik ini.

Pelajari lebih lanjut opsi enkripsi di Google Cloud. Untuk informasi spesifik tentang CMEK, termasuk keuntungan dan batasannya, lihat Kunci enkripsi yang dikelola pelanggan.

Sebelum memulai

• Semua aset data yang ada di penyimpanan terkelola BigQuery mendukung CMEK. Namun, jika Anda juga membuat kueri data yang disimpan di sumber data eksternal seperti Cloud Storage yang memiliki data yang dienkripsi CMEK, enkripsi data akan dikelola oleh Cloud Storage Misalnya, tabel BigLake mendukung data terenkripsi dengan CMEK di Cloud Storage.

  BigQuery dan tabel BigLake tidak mendukung Kunci Enkripsi yang Disediakan Pelanggan (CSEK).

• Tentukan apakah Anda akan menjalankan BigQuery dan Cloud KMS di project Google Cloud yang sama atau dalam project berbeda. Untuk tujuan contoh dokumentasi, konvensi berikut digunakan:

  • PROJECT_ID: project ID untuk project yang menjalankan BigQuery
  • PROJECT_NUMBER: nomor project untuk project yang menjalankan BigQuery
  • KMS_PROJECT_ID: project ID untuk project yang menjalankan Cloud KMS (meskipun project ini sama dengan yang menjalankan BigQuery)
  Untuk informasi tentang project ID dan nomor project Google Cloud, lihat Mengidentifikasi project.

• BigQuery secara otomatis diaktifkan dalam project baru. Jika Anda menggunakan project yang sudah ada untuk menjalankan BigQuery, aktifkan BigQuery API.

• Untuk project Google Cloud yang menjalankan Cloud KMS:

  1. Aktifkan Cloud Key Management Service API.
  2. Buat key ring dan kunci seperti yang dijelaskan dalam Membuat key ring dan kunci. Buat key ring di lokasi yang cocok dengan lokasi set data BigQuery Anda:
     • Setiap set data multi-regional harus menggunakan key ring multi-regional dari lokasi yang cocok. Misalnya, set data di region US harus dilindungi dengan key ring dari region us, dan set data di region EU harus dilindungi dengan key ring dari region europe.
     • Set data regional harus menggunakan kunci regional yang cocok. Misalnya, set data di region asia-northeast1 harus dilindungi dengan key ring dari region asia-northeast1.
     • Anda tidak dapat menggunakan region global saat mengonfigurasi CMEK untuk BigQuery di Konsol Google Cloud. Namun, Anda dapat menggunakan region global saat mengonfigurasi CMEK untuk BigQuery menggunakan alat command line bq atau GoogleSQL.
     Untuk mengetahui informasi lebih lanjut tentang lokasi yang didukung untuk BigQuery dan Cloud KMS, baca Lokasi Cloud.

Panggilan dekripsi dilakukan menggunakan Cloud KMS satu kali per kueri ke tabel yang dienkripsi CMEK. Untuk mengetahui informasi selengkapnya, lihat harga Cloud KMS.

Spesifikasi enkripsi

Kunci Cloud KMS yang digunakan untuk melindungi data Anda di BigQuery adalah kunci AES-256. Kunci ini digunakan sebagai kunci enkripsi kunci di BigQuery, karena kunci ini mengenkripsi kunci enkripsi data yang mengenkripsi data Anda.

Memberikan izin enkripsi dan dekripsi

Untuk melindungi data BigQuery dengan kunci CMEK, berikan izin kepada akun layanan BigQuery untuk mengenkripsi dan mendekripsi menggunakan kunci tersebut. Peran Pengenkripsi/Pendekripsi Cloud KMS dalam memberikan izin ini.

Pastikan akun layanan telah dibuat, lalu gunakan konsol Google Cloud untuk menentukan ID akun layanan BigQuery. Selanjutnya, berikan peran yang sesuai untuk akun layanan untuk mengenkripsi dan mendekripsi menggunakan Cloud KMS.

Memicu pembuatan akun layanan

Akun layanan BigQuery awalnya tidak dibuat saat Anda membuat project. Untuk memicu pembuatan akun layanan Anda, masukkan perintah yang menggunakannya, seperti perintah bq show --encryption_service_account, atau panggil project.getServiceAccount API. Contoh:

bq show --encryption_service_account --project_id=PROJECT_ID

Menentukan ID akun layanan

ID akun layanan BigQuery memiliki format:

[e-mail]

Teknik berikut menunjukkan cara menentukan ID akun layanan BigQuery untuk project Anda.

Konsol

1. Buka halaman Dasbor di konsol Google Cloud.

   Buka halaman Dasbor

2. Klik menu drop-down Pilih dari di bagian atas halaman. Di jendela Pilih Dari yang muncul, pilih project Anda.

3. Baik project ID maupun nomor project ditampilkan di kartu Info project pada Dasbor project:

   

4. Pada string berikut, ganti PROJECT_NUMBER dengan nomor project Anda. String baru mengidentifikasi ID akun layanan BigQuery Anda.

   [e-mail]
   

bq

Gunakan perintah bq show dengan flag --encryption_service_account untuk menentukan ID akun layanan:

bq show --encryption_service_account

Perintah ini akan menampilkan ID akun layanan:

                  ServiceAccountID
-------------------------------------------------------------
[e-mail]

Menetapkan peran Pengenkripsi/Pendekripsi

Tetapkan peran Pengenkripsi/Pendekripsi Cloud KMS ke akun layanan sistem BigQuery yang telah disalin ke papan klip. Akun ini berbentuk:

[e-mail]

Konsol

1. Buka halaman Kunci Kriptografis di konsol Google Cloud.

   Buka halaman Kunci Kriptografis

2. Klik nama key ring yang berisi kunci tersebut.

3. Klik kotak centang untuk kunci enkripsi yang ingin Anda tambahi peran. Tab Izin akan terbuka.

4. Klik Tambahkan anggota.

5. Masukkan alamat email akun layanan. [e-mail].

   • Jika akun layanan sudah ada di daftar anggota, akun tersebut memiliki peran yang sudah ada. Klik menu drop-down peran saat ini untuk akun layanan [e-mail].

6. Klik menu drop-down untuk Pilih peran, klik Cloud KMS, lalu klik peran Pengenkripsi/Pendekripsi CryptoKey Cloud KMS.

7. Klik Simpan untuk menerapkan peran ke akun layanan [e-mail].

gcloud

Anda dapat menggunakan Google Cloud CLI untuk menetapkan peran:

gcloud kms keys add-iam-policy-binding \
--project=KMS_PROJECT_ID \
--member serviceAccount:[e-mail] \
--role roles/cloudkms.cryptoKeyEncrypterDecrypter \
--location=KMS_KEY_LOCATION \
--keyring=KMS_KEY_RING \
KMS_KEY

Ganti kode berikut:

• KMS_PROJECT_ID: ID project Google Cloud Anda yang menjalankan Cloud KMS
• PROJECT_NUMBER: nomor project (bukan ID project) dari project Google Cloud Anda yang menjalankan BigQuery
• KMS_KEY_LOCATION: nama lokasi kunci Cloud KMS Anda
• KMS_KEY_RING: nama key ring untuk kunci Cloud KMS Anda
• KMS_KEY: nama kunci untuk kunci Cloud KMS Anda

ID resource kunci

ID resource untuk kunci Cloud KMS diperlukan untuk penggunaan CMEK, seperti yang ditunjukkan dalam contoh. Kunci ini peka huruf besar/kecil dan dalam bentuk:

projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY

Catatan: Anda tidak dapat menentukan ID resource kunci yang menyertakan token /cryptoKeyVersions/. BigQuery selalu menggunakan versi kunci yang ditandai sebagai primary untuk melindungi tabel saat dibuat.

Mengambil ID resource kunci

1. Buka halaman Kunci Kriptografis di konsol Google Cloud.

   Buka halaman Kunci Kriptografis

2. Klik nama key ring yang berisi kunci tersebut.

3. Untuk kunci yang ID resource-nya Anda ambil, klik Selengkapnya .

4. Klik Salin Nama Resource. ID resource untuk kunci disalin ke papan klip Anda. ID resource juga disebut sebagai nama resource.

Membuat tabel yang dilindungi oleh Cloud KMS

Untuk membuat tabel yang dilindungi oleh Cloud KMS:

Konsol

1. Buka halaman BigQuery di konsol Google Cloud.

   Buka halaman BigQuery

2. Di panel Penjelajah, luaskan project Anda dan pilih set data.

3. Luaskan opsi Actions dan klik Open.

4. Di panel detail, klik Buat tabel .

5. Di halaman Buat tabel, isi informasi yang diperlukan untuk membuat tabel kosong dengan definisi skema. Sebelum mengklik Buat Tabel, tetapkan jenis enkripsi dan tentukan kunci Cloud KMS yang akan digunakan dengan tabel:

   1. Klik Advanced options.
   2. Klik Kunci yang dikelola pelanggan.
   3. Pilih kunci. Jika kunci yang ingin Anda gunakan tidak tercantum, masukkan ID resource untuk kunci tersebut.

6. Klik Buat tabel.

SQL

Gunakan pernyataan CREATE TABLE dengan opsi kms_key_name:

1. Di konsol Google Cloud, buka halaman BigQuery.

   Buka BigQuery

2. Di editor kueri, masukkan pernyataan berikut:

   CREATE TABLE DATASET_ID.TABLE_ID (
     name STRING, value INT64
   ) OPTIONS (
       kms_key_name
         = 'projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY');
   

3. Klik Run.

Untuk informasi selengkapnya tentang cara menjalankan kueri, lihat Menjalankan kueri interaktif.

bq

Anda dapat menggunakan alat command line bq dengan flag --destination_kms_key untuk membuat tabel. Flag --destination_kms_key menentukan ID resource kunci yang akan digunakan dengan tabel.

Untuk membuat tabel kosong dengan skema:

bq mk --schema name:string,value:integer -t \
--destination_kms_key projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY \
DATASET_ID.TABLE_ID

Untuk membuat tabel dari kueri:

bq query --destination_table=DATASET_ID.TABLE_ID \
--destination_kms_key projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY \
"SELECT name,count FROM DATASET_ID.TABLE_ID WHERE gender = 'M' ORDER BY count DESC LIMIT 6"

Untuk mengetahui informasi selengkapnya tentang alat command line bq, baca Menggunakan alat command line bq.

Terraform

Gunakan resource google_bigquery_table.

Contoh berikut membuat tabel bernamamytable, dan juga menggunakan resource google_kms_crypto_key dan google_kms_key_ring untuk menentukan Kunci Cloud Key Management Service untuk tabel.

Untuk menjalankan contoh ini, Anda harus mengaktifkan Cloud Resource Manager API dan Cloud Key Management Service API.

resource "google_bigquery_dataset" "default" {
  dataset_id                      = "mydataset"
  default_partition_expiration_ms = 2592000000  # 30 days
  default_table_expiration_ms     = 31536000000 # 365 days
  description                     = "dataset description"
  location                        = "US"
  max_time_travel_hours           = 96 # 4 days

  labels = {
    billing_group = "accounting",
    pii           = "sensitive"
  }
}

resource "google_bigquery_table" "default" {
  dataset_id          = google_bigquery_dataset.default.dataset_id
  table_id            = "mytable"
  deletion_protection = false # set to "true" in production

  schema = <<EOF
[
  {
    "name": "ID",
    "type": "INT64",
    "mode": "NULLABLE",
    "description": "Item ID"
  },
  {
    "name": "Item",
    "type": "STRING",
    "mode": "NULLABLE"
  }
]
EOF

  encryption_configuration {
    kms_key_name = google_kms_crypto_key.crypto_key.id
  }

  depends_on = [google_project_iam_member.service_account_access]
}

resource "google_kms_crypto_key" "crypto_key" {
  name     = "example-key"
  key_ring = google_kms_key_ring.key_ring.id
}

resource "random_id" "default" {
  byte_length = 8
}

resource "google_kms_key_ring" "key_ring" {
  name     = "${random_id.default.hex}-example-keyring"
  location = "us"
}

# Enable the BigQuery service account to encrypt/decrypt Cloud KMS keys
data "google_project" "project" {
}

resource "google_project_iam_member" "service_account_access" {
  project = data.google_project.project.project_id
  role    = "roles/cloudkms.cryptoKeyEncrypterDecrypter"
  member  = "serviceAccount:bq-${data.google_project.project.number}@bigquery-encryption.iam.gserviceaccount.com"
}

Untuk menerapkan konfigurasi Terraform di project Google Cloud, selesaikan langkah-langkah di bagian berikut.

Menyiapkan Cloud Shell

1. Luncurkan Cloud Shell.

2. Tetapkan project Google Cloud default tempat Anda ingin menerapkan konfigurasi Terraform.

   Anda hanya perlu menjalankan perintah ini sekali per project, dan dapat dijalankan di direktori mana pun.

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   Variabel lingkungan akan diganti jika Anda menetapkan nilai eksplisit dalam file konfigurasi Terraform.

Menyiapkan direktori

Setiap file konfigurasi Terraform harus memiliki direktorinya sendiri (juga disebut modul root).

1. Di Cloud Shell, buat direktori dan file baru di dalam direktori tersebut. Nama file harus memiliki ekstensi .tf—misalnya main.tf. Dalam tutorial ini, file ini disebut sebagai main.tf.

   mkdir DIRECTORY && cd DIRECTORY && touch main.tf

2. Jika mengikuti tutorial, Anda dapat menyalin kode contoh di setiap bagian atau langkah.

   Salin kode contoh ke dalam main.tf yang baru dibuat.

   Atau, salin kode dari GitHub. Tindakan ini direkomendasikan jika cuplikan Terraform adalah bagian dari solusi menyeluruh.

3. Tinjau dan ubah contoh parameter untuk diterapkan pada lingkungan Anda.
4. Simpan perubahan Anda.
5. Lakukan inisialisasi Terraform. Anda hanya perlu melakukan ini sekali per direktori.

   terraform init

   Secara opsional, untuk menggunakan versi penyedia Google terbaru, sertakan opsi -upgrade:

   terraform init -upgrade

Menerapkan perubahan

1. Tinjau konfigurasi dan pastikan resource yang akan dibuat atau diupdate oleh Terraform sesuai yang Anda inginkan:

   terraform plan

   Koreksi konfigurasi jika diperlukan.

2. Terapkan konfigurasi Terraform dengan menjalankan perintah berikut dan memasukkan yes pada prompt:

   terraform apply

   Tunggu hingga Terraform menampilkan pesan "Apply complete!".

3. Buka project Google Cloud Anda untuk melihat hasilnya. Di Konsol Google Cloud, buka resource Anda di UI untuk memastikan bahwa Terraform telah membuat atau mengupdatenya.

Catatan: Contoh Terraform biasanya mengasumsikan bahwa API yang diperlukan diaktifkan di project Google Cloud Anda.

Go

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

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

import (
	"context"
	"fmt"

	"cloud.google.com/go/bigquery"
)

// createTableWithCMEK demonstrates creating a table protected with a customer managed encryption key.
func createTableWithCMEK(projectID, datasetID, tableID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydatasetid"
	// tableID := "mytableid"
	ctx := context.Background()

	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	tableRef := client.Dataset(datasetID).Table(tableID)
	meta := &bigquery.TableMetadata{
		EncryptionConfig: &bigquery.EncryptionConfig{
			// TODO: Replace this key with a key you have created in Cloud KMS.
			KMSKeyName: "projects/cloud-samples-tests/locations/us/keyRings/test/cryptoKeys/test",
		},
	}
	if err := tableRef.Create(ctx, meta); err != nil {
		return err
	}
	return nil
}

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.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.EncryptionConfiguration;
import com.google.cloud.bigquery.Field;
import com.google.cloud.bigquery.Schema;
import com.google.cloud.bigquery.StandardSQLTypeName;
import com.google.cloud.bigquery.StandardTableDefinition;
import com.google.cloud.bigquery.TableDefinition;
import com.google.cloud.bigquery.TableId;
import com.google.cloud.bigquery.TableInfo;

// Sample to create a cmek table
public class CreateTableCMEK {

  public static void runCreateTableCMEK() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    String kmsKeyName = "MY_KEY_NAME";
    Schema schema =
        Schema.of(
            Field.of("stringField", StandardSQLTypeName.STRING),
            Field.of("booleanField", StandardSQLTypeName.BOOL));
    // i.e. projects/{project}/locations/{location}/keyRings/{key_ring}/cryptoKeys/{cryptoKey}
    EncryptionConfiguration encryption =
        EncryptionConfiguration.newBuilder().setKmsKeyName(kmsKeyName).build();
    createTableCMEK(datasetName, tableName, schema, encryption);
  }

  public static void createTableCMEK(
      String datasetName, String tableName, Schema schema, EncryptionConfiguration configuration) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      TableId tableId = TableId.of(datasetName, tableName);
      TableDefinition tableDefinition = StandardTableDefinition.of(schema);
      TableInfo tableInfo =
          TableInfo.newBuilder(tableId, tableDefinition)
              .setEncryptionConfiguration(configuration)
              .build();

      bigquery.create(tableInfo);
      System.out.println("Table cmek created successfully");
    } catch (BigQueryException e) {
      System.out.println("Table cmek was not created. \n" + e.toString());
    }
  }
}

Python

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

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

Lindungi tabel baru dengan kunci enkripsi yang dikelola pelanggan dengan menetapkan properti Table.encryption_configuration ke objek EncryptionConfiguration sebelum membuat tabel.

from google.cloud import bigquery

client = bigquery.Client()

# TODO(dev): Change table_id to the full name of the table you want to create.
table_id = "your-project.your_dataset.your_table_name"

# Set the encryption key to use for the table.
# TODO: Replace this key with a key you have created in Cloud KMS.
kms_key_name = "projects/your-project/locations/us/keyRings/test/cryptoKeys/test"

table = bigquery.Table(table_id)
table.encryption_configuration = bigquery.EncryptionConfiguration(
    kms_key_name=kms_key_name
)
table = client.create_table(table)  # API request

print(f"Created {table_id}.")
print(f"Key: {table.encryption_configuration.kms_key_name}.")

Mengkueri tabel yang dilindungi oleh kunci Cloud KMS

Tidak ada pengaturan khusus yang diperlukan untuk membuat kueri tabel yang dilindungi oleh Cloud KMS. BigQuery menyimpan nama kunci yang digunakan untuk mengenkripsi isi tabel dan menggunakan kunci tersebut ketika tabel yang dilindungi oleh Cloud KMS dikueri.

Semua alat yang ada, konsol BigQuery, dan alat command line bq berjalan dengan cara yang sama seperti tabel terenkripsi default, selama BigQuery memiliki akses ke kunci Cloud KMS yang digunakan untuk mengenkripsi isi tabel.

Melindungi hasil kueri dengan kunci Cloud KMS

Secara default, hasil kueri disimpan dalam tabel sementara yang dienkripsi dengan kunci yang dikelola Google. Untuk menggunakan kunci Cloud KMS guna mengenkripsi hasil kueri Anda, pilih salah satu opsi berikut:

Konsol

1. Buka halaman BigQuery di konsol Google Cloud.

   Buka halaman BigQuery

2. Klik Tulis Kueri Baru.

3. Masukkan kueri GoogleSQL yang valid di area teks kueri.

4. Klik Selengkapnya, klik Setelan kueri, lalu klik Opsi lanjutan.

5. Pilih Enkripsi yang dikelola pelanggan.

6. Pilih kunci. Jika kunci yang ingin Anda gunakan tidak tercantum, masukkan ID resource untuk kunci tersebut.

7. Klik Save.

8. Klik Run.

bq

Tentukan flag --destination_kms_key untuk melindungi tabel tujuan atau hasil kueri (jika menggunakan tabel sementara) dengan kunci Cloud KMS Anda. Flag --destination_kms_key menentukan ID resource kunci yang akan digunakan dengan tabel tujuan atau hasil.

Secara opsional, gunakan flag --destination_table untuk menentukan tujuan hasil kueri. Jika --destination_table tidak digunakan, hasil kueri akan ditulis ke tabel sementara.

Untuk mengkueri tabel:

bq query \
--destination_table=DATASET_ID.TABLE_ID \
--destination_kms_key projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY \
"SELECT name,count FROM DATASET_ID.TABLE_ID WHERE gender = 'M' ORDER BY count DESC LIMIT 6"

Untuk mengetahui informasi selengkapnya tentang alat command line bq, baca Menggunakan alat command line bq.

Go

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/bigquery"
	"google.golang.org/api/iterator"
)

// queryWithDestinationCMEK demonstrates saving query results to a destination table and protecting those results
// by specifying a customer managed encryption key.
func queryWithDestinationCMEK(w io.Writer, projectID, dstDatasetID, dstTableID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	// tableID := "mytable"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	q := client.Query("SELECT 17 as my_col")
	q.Location = "US" // Location must match the dataset(s) referenced in query.
	q.QueryConfig.Dst = client.Dataset(dstDatasetID).Table(dstTableID)
	q.DestinationEncryptionConfig = &bigquery.EncryptionConfig{
		// TODO: Replace this key with a key you have created in Cloud KMS.
		KMSKeyName: "projects/cloud-samples-tests/locations/us-central1/keyRings/test/cryptoKeys/test",
	}
	// Run the query and print results when the query job is completed.
	job, err := q.Run(ctx)
	if err != nil {
		return err
	}
	status, err := job.Wait(ctx)
	if err != nil {
		return err
	}
	if err := status.Err(); err != nil {
		return err
	}
	it, err := job.Read(ctx)
	for {
		var row []bigquery.Value
		err := it.Next(&row)
		if err == iterator.Done {
			break
		}
		if err != nil {
			return err
		}
		fmt.Fprintln(w, row)
	}
	return nil
}

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.

Lindungi tabel baru dengan kunci enkripsi yang dikelola pelanggan dengan menetapkan properti Table.encryption_configuration ke objek EncryptionConfiguration sebelum membuat tabel.

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.EncryptionConfiguration;
import com.google.cloud.bigquery.QueryJobConfiguration;
import com.google.cloud.bigquery.TableResult;

// Sample to query on destination table with encryption key
public class QueryDestinationTableCMEK {

  public static void runQueryDestinationTableCMEK() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    String kmsKeyName = "MY_KMS_KEY_NAME";
    String query =
        String.format("SELECT stringField, booleanField FROM %s.%s", datasetName, tableName);
    EncryptionConfiguration encryption =
        EncryptionConfiguration.newBuilder().setKmsKeyName(kmsKeyName).build();
    queryDestinationTableCMEK(query, encryption);
  }

  public static void queryDestinationTableCMEK(String query, EncryptionConfiguration encryption) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      QueryJobConfiguration config =
          QueryJobConfiguration.newBuilder(query)
              // Set the encryption key to use for the destination.
              .setDestinationEncryptionConfiguration(encryption)
              .build();

      TableResult results = bigquery.query(config);

      results
          .iterateAll()
          .forEach(row -> row.forEach(val -> System.out.printf("%s,", val.toString())));
      System.out.println("Query performed successfully with encryption key.");
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Query not performed \n" + e.toString());
    }
  }
}

Python

from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

# TODO(developer): Set table_id to the ID of the destination table.
# table_id = "your-project.your_dataset.your_table_name"

# Set the encryption key to use for the destination.
# TODO(developer): Replace this key with a key you have created in KMS.
# kms_key_name = "projects/{}/locations/{}/keyRings/{}/cryptoKeys/{}".format(
#     your-project, location, your-ring, your-key
# )

job_config = bigquery.QueryJobConfig(
    destination=table_id,
    destination_encryption_configuration=bigquery.EncryptionConfiguration(
        kms_key_name=kms_key_name
    ),
)

# Start the query, passing in the extra configuration.
query_job = client.query(
    "SELECT 17 AS my_col;", job_config=job_config
)  # Make an API request.
query_job.result()  # Wait for the job to complete.

table = client.get_table(table_id)  # Make an API request.
if table.encryption_configuration.kms_key_name == kms_key_name:
    print("The destination table is written using the encryption configuration")

Memuat tabel yang dilindungi oleh Cloud KMS

Untuk memuat file data ke tabel yang dilindungi oleh Cloud KMS:

Konsol

Lindungi tabel tujuan tugas pemuatan dengan kunci enkripsi yang dikelola pelanggan dengan menentukan kunci saat Anda memuat tabel.

1. Buka halaman BigQuery di Konsol Google Cloud.

   Buka halaman BigQuery

2. Di panel Penjelajah, luaskan project Anda dan pilih set data.

3. Di panel detail, klik Buat tabel.

4. Masukkan opsi yang ingin Anda gunakan untuk memuat tabel, tetapi sebelum Anda mengklik Buat tabel, klik Opsi lanjutan.

5. Di bagian Enkripsi, pilih Kunci yang dikelola pelanggan.

6. Klik menu drop-down Pilih kunci yang dikelola pelanggan, lalu pilih kunci untuk digunakan. Jika Anda tidak melihat kunci yang tersedia, masukkan ID resource kunci.

   

7. Klik Buat tabel.

bq

Lindungi tabel tujuan tugas pemuatan dengan kunci enkripsi yang dikelola pelanggan dengan menetapkan flag --destination_kms_key.

bq --location=LOCATION load \
--autodetect \
--source_format=FORMAT \
--destination_kms_key projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY \
DATASET.TABLE \
path_to_source

Contoh:

bq load \
--autodetect \
--source_format=NEWLINE_DELIMITED_JSON \
--destination_kms_key projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY \
test2.table4 \
gs://cloud-samples-data/bigquery/us-states/us-states.json

Go

import (
	"context"
	"fmt"

	"cloud.google.com/go/bigquery"
)

// importJSONWithCMEK demonstrates loading newline-delimited JSON from Cloud Storage,
// and protecting the data with a customer-managed encryption key.
func importJSONWithCMEK(projectID, datasetID, tableID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	// tableID := "mytable"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	gcsRef := bigquery.NewGCSReference("gs://cloud-samples-data/bigquery/us-states/us-states.json")
	gcsRef.SourceFormat = bigquery.JSON
	gcsRef.AutoDetect = true
	loader := client.Dataset(datasetID).Table(tableID).LoaderFrom(gcsRef)
	loader.WriteDisposition = bigquery.WriteEmpty
	loader.DestinationEncryptionConfig = &bigquery.EncryptionConfig{
		// TODO: Replace this key with a key you have created in KMS.
		KMSKeyName: "projects/cloud-samples-tests/locations/us-central1/keyRings/test/cryptoKeys/test",
	}

	job, err := loader.Run(ctx)
	if err != nil {
		return err
	}
	status, err := job.Wait(ctx)
	if err != nil {
		return err
	}

	if status.Err() != nil {
		return fmt.Errorf("job completed with error: %v", status.Err())
	}

	return nil
}

Java

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.EncryptionConfiguration;
import com.google.cloud.bigquery.FormatOptions;
import com.google.cloud.bigquery.Job;
import com.google.cloud.bigquery.JobInfo;
import com.google.cloud.bigquery.LoadJobConfiguration;
import com.google.cloud.bigquery.TableId;

// Sample to load JSON data with configuration key from Cloud Storage into a new BigQuery table
public class LoadJsonFromGCSCMEK {

  public static void runLoadJsonFromGCSCMEK() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    String kmsKeyName = "MY_KMS_KEY_NAME";
    String sourceUri = "gs://cloud-samples-data/bigquery/us-states/us-states.json";
    // i.e. projects/{project}/locations/{location}/keyRings/{key_ring}/cryptoKeys/{cryptoKey}
    EncryptionConfiguration encryption =
        EncryptionConfiguration.newBuilder().setKmsKeyName(kmsKeyName).build();
    loadJsonFromGCSCMEK(datasetName, tableName, sourceUri, encryption);
  }

  public static void loadJsonFromGCSCMEK(
      String datasetName, String tableName, String sourceUri, EncryptionConfiguration encryption) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      TableId tableId = TableId.of(datasetName, tableName);
      LoadJobConfiguration loadConfig =
          LoadJobConfiguration.newBuilder(tableId, sourceUri)
              // Set the encryption key to use for the destination.
              .setDestinationEncryptionConfiguration(encryption)
              .setFormatOptions(FormatOptions.json())
              .setAutodetect(true)
              .build();

      // Load data from a GCS JSON file into the table
      Job job = bigquery.create(JobInfo.of(loadConfig));
      // Blocks until this load table job completes its execution, either failing or succeeding.
      job = job.waitFor();
      if (job.isDone()) {
        System.out.println("Table loaded succesfully from GCS with configuration key");
      } else {
        System.out.println(
            "BigQuery was unable to load into the table due to an error:"
                + job.getStatus().getError());
      }
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Column not added during load append \n" + e.toString());
    }
  }
}

Python

Lindungi tabel tujuan tugas pemuatan dengan kunci enkripsi yang dikelola pelanggan dengan menetapkan properti LoadJobConfig.destination_encryption_configuration ke EncryptionConfiguration dan memuat tabel.

from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

# TODO(developer): Set table_id to the ID of the table to create.
# table_id = "your-project.your_dataset.your_table_name

# Set the encryption key to use for the destination.
# TODO: Replace this key with a key you have created in KMS.
# kms_key_name = "projects/{}/locations/{}/keyRings/{}/cryptoKeys/{}".format(
#     "cloud-samples-tests", "us", "test", "test"
# )

job_config = bigquery.LoadJobConfig(
    autodetect=True,
    source_format=bigquery.SourceFormat.NEWLINE_DELIMITED_JSON,
    destination_encryption_configuration=bigquery.EncryptionConfiguration(
        kms_key_name=kms_key_name
    ),
)

uri = "gs://cloud-samples-data/bigquery/us-states/us-states.json"

load_job = client.load_table_from_uri(
    uri,
    table_id,
    location="US",  # Must match the destination dataset location.
    job_config=job_config,
)  # Make an API request.

assert load_job.job_type == "load"

load_job.result()  # Waits for the job to complete.

assert load_job.state == "DONE"
table = client.get_table(table_id)

if table.encryption_configuration.kms_key_name == kms_key_name:
    print("A table loaded with encryption configuration key")

Streaming ke tabel yang dilindungi oleh Cloud KMS

Anda dapat melakukan streaming data ke tabel BigQuery yang dilindungi CMEK tanpa menentukan parameter tambahan. Perlu diperhatikan bahwa data ini dienkripsi menggunakan kunci Cloud KMS Anda di buffer serta di lokasi akhir. Sebelum menggunakan streaming dengan tabel CMEK, tinjau persyaratan tentang ketersediaan dan aksesibilitas utama.

Pelajari lebih lanjut streaming dengan membaca Streaming data ke BigQuery.

Mengubah tabel dari enkripsi default ke perlindungan Cloud KMS

bq

Anda dapat menggunakan perintah bq cp dengan flag --destination_kms_key untuk menyalin tabel yang dilindungi oleh enkripsi default ke dalam tabel baru, atau ke dalam tabel asli yang dilindungi oleh Cloud KMS. Flag --destination_kms_key menentukan ID resource kunci yang akan digunakan dengan tabel tujuan.

Untuk menyalin tabel yang memiliki enkripsi default ke tabel baru yang memiliki perlindungan Cloud KMS:

bq cp \
--destination_kms_key projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY \
SOURCE_DATASET_ID.SOURCE_TABLE_ID DESTINATION_DATASET_ID.DESTINATION_TABLE_ID

Anda dapat menyalin tabel yang memiliki enkripsi default ke tabel yang sama dengan perlindungan Cloud KMS:

bq cp -f \
--destination_kms_key projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY \
DATASET_ID.TABLE_ID DATASET_ID.TABLE_ID

Jika ingin mengubah tabel dari perlindungan Cloud KMS ke enkripsi default, salin file ke enkripsi tersebut sendiri dengan menjalankan bq cp tanpa menggunakan flag --destination_kms_key.

Untuk mengetahui informasi selengkapnya tentang alat command line bq, baca Menggunakan alat command line bq.

Go

import (
	"context"
	"fmt"

	"cloud.google.com/go/bigquery"
)

// copyTableWithCMEK demonstrates creating a copy of a table and ensuring the copied data is
// protected with a customer managed encryption key.
func copyTableWithCMEK(projectID, datasetID, tableID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	// tableID := "mytable"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	srcTable := client.DatasetInProject("bigquery-public-data", "samples").Table("shakespeare")
	copier := client.Dataset(datasetID).Table(tableID).CopierFrom(srcTable)
	copier.DestinationEncryptionConfig = &bigquery.EncryptionConfig{
		// TODO: Replace this key with a key you have created in Cloud KMS.
		KMSKeyName: "projects/cloud-samples-tests/locations/us-central1/keyRings/test/cryptoKeys/test",
	}
	job, err := copier.Run(ctx)
	if err != nil {
		return err
	}
	status, err := job.Wait(ctx)
	if err != nil {
		return err
	}
	if err := status.Err(); err != nil {
		return err
	}
	return nil
}

Java

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.CopyJobConfiguration;
import com.google.cloud.bigquery.EncryptionConfiguration;
import com.google.cloud.bigquery.Job;
import com.google.cloud.bigquery.JobInfo;
import com.google.cloud.bigquery.TableId;

// Sample to copy a cmek table
public class CopyTableCMEK {

  public static void runCopyTableCMEK() {
    // TODO(developer): Replace these variables before running the sample.
    String destinationDatasetName = "MY_DESTINATION_DATASET_NAME";
    String destinationTableId = "MY_DESTINATION_TABLE_NAME";
    String sourceDatasetName = "MY_SOURCE_DATASET_NAME";
    String sourceTableId = "MY_SOURCE_TABLE_NAME";
    String kmsKeyName = "MY_KMS_KEY_NAME";
    EncryptionConfiguration encryption =
        EncryptionConfiguration.newBuilder().setKmsKeyName(kmsKeyName).build();
    copyTableCMEK(
        sourceDatasetName, sourceTableId, destinationDatasetName, destinationTableId, encryption);
  }

  public static void copyTableCMEK(
      String sourceDatasetName,
      String sourceTableId,
      String destinationDatasetName,
      String destinationTableId,
      EncryptionConfiguration encryption) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      TableId sourceTable = TableId.of(sourceDatasetName, sourceTableId);
      TableId destinationTable = TableId.of(destinationDatasetName, destinationTableId);

      // For more information on CopyJobConfiguration see:
      // https://googleapis.dev/java/google-cloud-clients/latest/com/google/cloud/bigquery/JobConfiguration.html
      CopyJobConfiguration configuration =
          CopyJobConfiguration.newBuilder(destinationTable, sourceTable)
              .setDestinationEncryptionConfiguration(encryption)
              .build();

      // For more information on Job see:
      // https://googleapis.dev/java/google-cloud-clients/latest/index.html?com/google/cloud/bigquery/package-summary.html
      Job job = bigquery.create(JobInfo.of(configuration));

      // Blocks until this job completes its execution, either failing or succeeding.
      Job completedJob = job.waitFor();
      if (completedJob == null) {
        System.out.println("Job not executed since it no longer exists.");
        return;
      } else if (completedJob.getStatus().getError() != null) {
        System.out.println(
            "BigQuery was unable to copy table due to an error: \n" + job.getStatus().getError());
        return;
      }
      System.out.println("Table cmek copied successfully.");
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Table cmek copying job was interrupted. \n" + e.toString());
    }
  }
}

Python

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

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

Lindungi tujuan salinan tabel dengan kunci enkripsi yang dikelola pelanggan dengan menetapkan properti QueryJobConfig.destination_encryption_configuration ke EncryptionConfiguration dan salin tabel.

from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

# TODO(developer): Set dest_table_id to the ID of the destination table.
# dest_table_id = "your-project.your_dataset.your_table_name"

# TODO(developer): Set orig_table_id to the ID of the original table.
# orig_table_id = "your-project.your_dataset.your_table_name"

# Set the encryption key to use for the destination.
# TODO(developer): Replace this key with a key you have created in KMS.
# kms_key_name = "projects/{}/locations/{}/keyRings/{}/cryptoKeys/{}".format(
#     your-project, location, your-ring, your-key
# )

job_config = bigquery.CopyJobConfig(
    destination_encryption_configuration=bigquery.EncryptionConfiguration(
        kms_key_name=kms_key_name
    )
)
job = client.copy_table(orig_table_id, dest_table_id, job_config=job_config)
job.result()  # Wait for the job to complete.

dest_table = client.get_table(dest_table_id)  # Make an API request.
if dest_table.encryption_configuration.kms_key_name == kms_key_name:
    print("A copy of the table created")

Menentukan apakah tabel dilindungi oleh Cloud KMS

1. Di konsol Google Cloud, klik panah biru di sebelah kiri set data Anda untuk meluaskannya, atau klik dua kali nama set data. Tindakan ini menampilkan tabel dan tampilan dalam set data.

2. Klik nama tabel.

3. Klik Details. Halaman Detail Tabel menampilkan deskripsi tabel dan informasi tabel.

4. Jika tabel dilindungi oleh Cloud KMS, kolom Kunci Enkripsi yang Dikelola Pelanggan akan menampilkan ID resource kunci.

   

Mengubah kunci Cloud KMS untuk tabel BigQuery

Untuk mengubah kunci Cloud KMS dari tabel yang dilindungi CMEK yang ada, Anda dapat menjalankan kueri ALTER TABLE, menggunakan API, atau menggunakan alat command line bq. Ada dua cara untuk mengubah kunci Cloud KMS menggunakan API dan alat command line bq: update atau cp.

Jika menggunakan update, Anda dapat mengubah kunci Cloud KMS yang digunakan untuk tabel yang dilindungi CMEK.

Jika menggunakan cp, Anda dapat mengubah kunci Cloud KMS yang digunakan untuk tabel yang dilindungi CMEK, mengubah tabel dari enkripsi default ke perlindungan CMEK, atau mengubah tabel dari perlindungan CMEK menjadi default enkripsi.

Keuntungan dari update adalah lebih cepat daripada cp dan memungkinkan Anda menggunakan dekorator tabel.

SQL

Gunakan pernyataan ALTER TABLE SET OPTIONS untuk memperbarui kolom kms_key_name untuk tabel:

1. Di Konsol Google Cloud, buka halaman BigQuery.

   Buka BigQuery

2. Di editor kueri, masukkan pernyataan berikut:

   ALTER TABLE DATASET_ID.mytable
   SET OPTIONS (
     kms_key_name
       = 'projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY');
   

3. Klik Run.

Untuk informasi selengkapnya tentang cara menjalankan kueri, lihat Menjalankan kueri interaktif.

bq

Anda dapat menggunakan perintah bq cp dengan flag --destination_kms_key untuk mengubah kunci tabel yang dilindungi oleh Cloud KMS. Flag --destination_kms_key menentukan ID resource kunci yang akan digunakan dengan tabel.

bq update \
--destination_kms_key projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY \
-t DATASET_ID.TABLE_ID

Go

import (
	"context"
	"fmt"

	"cloud.google.com/go/bigquery"
)

// updateTableChangeCMEK demonstrates how to change the customer managed encryption key that protects a table.
func updateTableChangeCMEK(projectID, datasetID, tableID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydatasetid"
	// tableID := "mytableid"
	ctx := context.Background()

	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	tableRef := client.Dataset(datasetID).Table(tableID)
	meta, err := tableRef.Metadata(ctx)
	if err != nil {
		return err
	}
	update := bigquery.TableMetadataToUpdate{
		EncryptionConfig: &bigquery.EncryptionConfig{
			// TODO: Replace this key with a key you have created in Cloud KMS.
			KMSKeyName: "projects/cloud-samples-tests/locations/us-central1/keyRings/test/cryptoKeys/otherkey",
		},
	}
	if _, err := tableRef.Update(ctx, update, meta.ETag); err != nil {
		return err
	}
	return nil
}

Java

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.EncryptionConfiguration;
import com.google.cloud.bigquery.Table;
import com.google.cloud.bigquery.TableId;

// Sample to update a cmek table
public class UpdateTableCMEK {

  public static void runUpdateTableCMEK() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    String kmsKeyName = "MY_KEY_NAME";
    // Set a new encryption key to use for the destination.
    // i.e. projects/{project}/locations/{location}/keyRings/{key_ring}/cryptoKeys/{cryptoKey}
    EncryptionConfiguration encryption =
        EncryptionConfiguration.newBuilder().setKmsKeyName(kmsKeyName).build();
    updateTableCMEK(datasetName, tableName, encryption);
  }

  public static void updateTableCMEK(
      String datasetName, String tableName, EncryptionConfiguration encryption) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      Table table = bigquery.getTable(TableId.of(datasetName, tableName));
      bigquery.update(table.toBuilder().setEncryptionConfiguration(encryption).build());
      System.out.println("Table cmek updated successfully");
    } catch (BigQueryException e) {
      System.out.println("Table cmek was not updated. \n" + e.toString());
    }
  }
}

Python

Ubah kunci enkripsi yang dikelola pelanggan untuk tabel dengan mengubah properti Table.encryption_configuration menjadi objek EncryptionConfiguration baru dan perbarui tabel.

# from google.cloud import bigquery
# client = bigquery.Client()

assert table.encryption_configuration.kms_key_name == original_kms_key_name

# Set a new encryption key to use for the destination.
# TODO: Replace this key with a key you have created in KMS.
updated_kms_key_name = (
    "projects/cloud-samples-tests/locations/us/keyRings/test/cryptoKeys/otherkey"
)
table.encryption_configuration = bigquery.EncryptionConfiguration(
    kms_key_name=updated_kms_key_name
)

table = client.update_table(table, ["encryption_configuration"])  # API request

assert table.encryption_configuration.kms_key_name == updated_kms_key_name
assert original_kms_key_name != updated_kms_key_name

Menetapkan kunci default set data

Anda dapat menetapkan kunci Cloud KMS default berskala set data yang berlaku untuk semua tabel yang baru dibuat dalam set data, kecuali jika kunci Cloud KMS yang berbeda ditentukan saat Anda membuat tabel. Kunci default tidak berlaku untuk tabel yang ada. Mengubah kunci default tidak akan mengubah tabel yang ada dan hanya berlaku untuk tabel baru yang dibuat setelah perubahan.

Anda dapat menerapkan, mengubah, atau menghapus kunci set data default dengan

• menentukan kunci default di kolom EncryptionConfiguration.kmsKeyName saat Anda memanggil metode datasets.insert atau datasets.patch

• menentukan kunci default dalam flag --default_kms_key saat menjalankan perintah bq mk --dataset.

  bq mk \
  --default_kms_key projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY \
  --dataset DATASET_ID
  

  bq update \
  --default_kms_key projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY \
  --dataset DATASET_ID
  

Catatan: Dalam set data yang menerapkan kunci Cloud KMS default, tabel baru tidak dapat dienkripsi dengan kunci selain kunci enkripsi yang dikelola pelanggan. Artinya, jika set data memiliki kunci Cloud KMS default, Anda tidak dapat menggunakan kunci enkripsi yang tidak dikelola pelanggan untuk mengenkripsi tabel baru dalam set data.

Menetapkan kunci default project

Anda dapat menetapkan kunci Cloud KMS default berskala project yang berlaku untuk semua hasil kueri dan tabel yang baru dibuat dalam project, kecuali jika Anda menentukan kunci Cloud KMS lain. Kunci default tidak berlaku untuk tabel yang sudah ada. Mengubah kunci default tidak akan mengubah tabel yang ada dan hanya berlaku untuk tabel baru yang dibuat setelah perubahan.

SQL

Gunakan pernyataan ALTER PROJECT SET OPTIONS untuk memperbarui kolom default_kms_key_name untuk sebuah project. Anda dapat menemukan nama resource untuk kunci tersebut di halaman Cloud KMS.

1. Di Konsol Google Cloud, buka halaman BigQuery.

   Buka BigQuery

2. Di editor kueri, masukkan pernyataan berikut:

   ALTER PROJECT PROJECT_ID
   SET OPTIONS (
     region-us.default_kms_key_name
       = 'projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY');
   

3. Klik Run.

Untuk informasi selengkapnya tentang cara menjalankan kueri, lihat Menjalankan kueri interaktif.

bq

Anda dapat menggunakan perintah bq untuk menjalankan pernyataan ALTER PROJECT SET OPTIONS guna memperbarui kolom default_kms_key_name untuk sebuah project:

bq query --nouse_legacy_sql \
  'ALTER PROJECT PROJECT_ID
  SET OPTIONS (
  `region-us.default_kms_key_name`
    ="projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY");'

Menggunakan CMEK untuk melindungi model BigQuery ML

BigQuery ML mendukung CMEK. Selain enkripsi default yang disediakan oleh BigQuery, Anda dapat menggunakan kunci Cloud Key Management Service Anda sendiri untuk mengenkripsi model machine learning, termasuk model TensorFlow yang diimpor.

Membuat model terenkripsi dengan kunci Cloud KMS

Untuk membuat model terenkripsi, gunakan pernyataan CREATE MODEL dan tentukan KMS_KEY_NAME dalam opsi pelatihan:

    CREATE MODEL my_dataset.my_model
    OPTIONS(
      model_type='linear_reg',
      input_label_cols=['your_label'],
      kms_key_name='projects/my_project/locations/my_location/keyRings/my_ring/cryptoKeys/my_key')
    AS SELECT * FROM my_dataset.my_data

Sintaksis yang sama juga berlaku untuk model TensorFlow yang diimpor:

    CREATE MODEL my_dataset.my_model
    OPTIONS(
      model_type='tensorflow',
      path='gs://bucket/path/to/saved_model/*',
      kms_key_name='projects/my_project/locations/my_location/keyRings/my_ring/cryptoKeys/my_key')
    AS SELECT * FROM my_dataset.my_data

Batasan

Kunci enkripsi yang dikelola pelanggan memiliki batasan berikut saat mengenkripsi model machine learning:

• Kunci CMEK region Global tidak didukung untuk jenis model berikut:

  • DNN
  • Wide-and-Deep
  • Autoencoder
  • Hierarki yang ditingkatkan

• Kunci CMEK region Global dan kunci CMEK multi-region, misalnya EU atau US, tidak didukung saat membuat model AutoML Tables.

Mengubah model dari enkripsi default ke perlindungan Cloud KMS

Anda dapat menggunakan perintah bq cp dengan flag --destination_kms_key untuk menyalin model yang dilindungi oleh enkripsi default ke model baru yang dilindungi oleh Cloud KMS. Atau, Anda dapat menggunakan perintah bq cp dengan flag -f untuk menimpa model yang dilindungi oleh enkripsi default dan memperbaruinya untuk menggunakan perlindungan Cloud KMS. Flag --destination_kms_key menentukan ID resource kunci yang akan digunakan dengan model tujuan.

Untuk menyalin model yang memiliki enkripsi default ke model baru yang memiliki perlindungan Cloud KMS:

bq cp \
--destination_kms_key projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY \
SOURCE_DATASET_ID.SOURCE_MODEL_ID DESTINATION_DATASET_ID.DESTINATION_MODEL_ID

Untuk menimpa model yang memiliki enkripsi default ke model yang sama dengan perlindungan Cloud KMS:

bq cp -f \
--destination_kms_key projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY \
DATASET_ID.MODEL_ID DATASET_ID.MODEL_ID

Untuk mengubah model dari perlindungan Cloud KMS ke enkripsi default:

bq cp -f \
DATASET_ID.MODEL_ID DATASET_ID.MODEL_ID

Untuk mengetahui informasi selengkapnya tentang alat command line bq, baca Menggunakan alat command line bq.

Menentukan apakah model dilindungi oleh Cloud KMS

Gunakan perintah bq show untuk melihat apakah model dilindungi oleh kunci Cloud KMS. Kunci enkripsi ada di kolom kmsKeyName.

bq show -m my_dataset.my_model

Anda juga dapat menggunakan konsol Google Cloud untuk menemukan kunci Cloud KMS untuk model terenkripsi. Informasi CMEK ada di kolom Kunci yang dikelola pelanggan di bagian Detail Model pada panel Detail model.

Mengubah kunci Cloud KMS untuk model terenkripsi

Gunakan perintah bq update dengan flag --destination_kms_key guna mengubah kunci untuk model yang dilindungi oleh Cloud KMS:

bq update --destination_kms_key \
projects/my_project/locations/my_location/keyRings/my_ring/cryptoKeys/my_key \
-t my_dataset.my_model

Menggunakan kunci set data atau project default

Jika Anda memiliki kunci Cloud KMS default yang ditetapkan pada level project atau set data, BigQuery ML akan otomatis menggunakan kunci ini saat membuat model. Gunakan pernyataan CREATE MODEL untuk menentukan kunci lain untuk mengenkripsi model jika Anda tidak ingin menggunakan kunci default.

Menggunakan fungsi BigQuery ML dengan model terenkripsi

Anda dapat menggunakan semua fungsi BigQuery ML dengan model terenkripsi tanpa menentukan kunci enkripsi.

Menggunakan CMEK untuk melindungi BigQuery Connection API

Untuk koneksi Cloud SQL, Anda dapat melindungi kredensial BigQuery Connection API menggunakan CMEK.

Untuk mengetahui informasi selengkapnya tentang cara membuat koneksi yang dilindungi CMEK, lihat Membuat koneksi Cloud SQL.

Menghapus akses BigQuery ke kunci Cloud KMS

Anda dapat menghapus akses BigQuery ke kunci Cloud KMS kapan saja, dengan mencabut izin Identity and Access Management (IAM) untuk kunci tersebut.

Catatan: Jika Anda menghapus akses BigQuery ke suatu kunci, perubahan ini tidak akan langsung diterapkan, tetapi terjadi dalam satu jam selagi perubahan izin IAM diterapkan. Jika Anda menjalankan kueri saat itu, kueri tersebut tetap selesai, tetapi hasilnya mungkin tidak dapat dilihat.

Jika BigQuery kehilangan akses ke kunci Cloud KMS, pengalaman pengguna dapat mengalami penurunan yang signifikan dan kehilangan data dapat terjadi:

• Data dalam tabel yang dilindungi CMEK ini tidak dapat lagi diakses: query, cp, extract, dan tabledata.list semuanya akan gagal.

• Tidak ada data baru yang dapat ditambahkan ke tabel yang dilindungi CMEK ini.

• Setelah akses diberikan kembali, performa kueri ke tabel ini dapat menurun selama beberapa hari.

Mengontrol penggunaan CMEK dengan kebijakan organisasi

BigQuery terintegrasi dengan batasan kebijakan organisasi CMEK agar Anda dapat menentukan persyaratan kepatuhan enkripsi untuk resource BigQuery di organisasi Anda.

Integrasi ini memungkinkan Anda melakukan hal berikut:

• Mewajibkan CMEK untuk semua resource BigQuery dalam sebuah project.

• Membatasi kunci Cloud KMS mana yang dapat digunakan untuk melindungi resource dalam suatu project.

Mewajibkan CMEK untuk semua resource

Kebijakan umumnya adalah mewajibkan CMEK digunakan untuk melindungi semua resource dalam kumpulan project tertentu. Anda dapat menggunakan batasan constraints/gcp.restrictNonCmekServices untuk menerapkan kebijakan ini di BigQuery.

Jika ditetapkan, kebijakan organisasi ini akan menyebabkan semua permintaan pembuatan resource tanpa kunci Cloud KMS yang ditentukan akan gagal.

Setelah ditetapkan, kebijakan ini hanya berlaku untuk resource baru dalam project. Setiap resource yang ada tanpa kunci Cloud KMS akan tetap ada dan dapat diakses tanpa masalah.

Catatan: Batasan ini hanya berlaku untuk resource yang berisi data. Resource yang hanya menggunakan kunci Cloud KMS yang ditentukan sebagai default untuk resource baru (misalnya, set data dan konfigurasi project) masih dapat dibuat atau diperbarui tanpa kunci Cloud KMS.

Konsol

1. Buka halaman Kebijakan organisasi.

   Buka Organization policies

2. Di kolom Filter, masukkan constraints/gcp.restrictNonCmekServices, lalu klik Batasi layanan mana yang dapat membuat resource tanpa CMEK.

3. Klik Edit.

4. Pilih Customize, pilih Replace, lalu klik Add Rule.

5. Pilih Kustom, lalu klik Tolak.

6. Di kolom Nilai Kustom, masukkan is:bigquery.googleapis.com.

7. Klik Selesai, lalu klik Simpan.

gcloud

  gcloud resource-manager org-policies --project=PROJECT_ID \
    deny gcp.restrictNonCmekServices is:bigquery.googleapis.com

Untuk memverifikasi bahwa kebijakan berhasil diterapkan, Anda dapat mencoba membuat tabel dalam project. Proses ini akan gagal kecuali jika Anda menentukan kunci Cloud KMS.

Kebijakan ini juga berlaku untuk tabel hasil kueri dalam project. Anda dapat menentukan kunci default project agar pengguna tidak perlu menentukan kunci secara manual setiap kali menjalankan kueri dalam project.

Membatasi kunci Cloud KMS untuk project BigQuery

Anda dapat menggunakan batasan constraints/gcp.restrictCmekCryptoKeyProjects untuk membatasi kunci Cloud KMS yang dapat digunakan untuk melindungi resource dalam project BigQuery.

Anda dapat menentukan aturan - misalnya, "Untuk semua resource BigQuery dalam projects/my-company-data-project, kunci Cloud KMS yang digunakan dalam project ini harus berasal dari projects/my-company-central-keys ATAU projects/team-specific-keys."

Konsol

1. Buka halaman Kebijakan organisasi.

   Buka Organization policies

2. Di kolom Filter, masukkan constraints/gcp.restrictCmekCryptoKeyProjects, lalu klik Batasi project mana yang dapat menyediakan CryptoKey KMS untuk CMEK.

3. Klik Edit.

4. Pilih Customize, pilih Replace, lalu klik Add Rule.

5. Pilih Kustom, lalu klik Izinkan.

6. Di kolom Nilai Kustom, masukkan under:projects/<var>KMS_PROJECT_ID</var>.

7. Klik Selesai, lalu klik Simpan.

gcloud

  gcloud resource-manager org-policies --project=PROJECT_ID \
    allow gcp.restrictCmekCryptoKeyProjects under:projects/KMS_PROJECT_ID

Untuk memverifikasi bahwa kebijakan berhasil diterapkan, Anda dapat mencoba membuat tabel menggunakan kunci Cloud KMS dari project lain. Proses tersebut akan gagal.

Batasan kebijakan organisasi

Ada batasan terkait penetapan kebijakan organisasi.

Keterlambatan penerapan

Setelah Anda menetapkan atau memperbarui kebijakan organisasi, perlu waktu hingga 15 menit agar kebijakan baru dapat diterapkan. BigQuery menyimpan kebijakan dalam cache agar tidak berdampak negatif terhadap latensi pembuatan kueri dan tabel.

Izin yang diperlukan untuk menetapkan kebijakan organisasi

Izin untuk menetapkan atau memperbarui kebijakan organisasi mungkin sulit diperoleh untuk tujuan pengujian. Anda harus diberi peran Administrator Kebijakan Organisasi, yang hanya dapat diberikan di tingkat organisasi (bukan di tingkat project atau folder).

Meskipun peran ini harus diberikan di tingkat organisasi, Anda tetap dapat menentukan kebijakan yang hanya berlaku untuk project atau folder tertentu.

Dampak rotasi kunci Cloud KMS

BigQuery tidak secara otomatis merotasi kunci enkripsi tabel saatkunci Cloud KMS yang terkait dengan tabel dirotasi. Semua data dalam tabel yang ada akan tetap dilindungi oleh versi kunci yang digunakan untuk membuat tabel tersebut.

Setiap tabel yang baru dibuat akan menggunakan versi kunci utama pada saat pembuatannya.

Untuk memperbarui tabel agar menggunakan versi kunci terbaru, ubah tabel ke kunci Cloud KMS yang berbeda, lalu kembalikan tabel ke versi aslinya.

Dampak pada penagihan Cloud KMS

Saat Anda membuat atau memotong tabel yang dilindungi CMEK, BigQuery akan menghasilkan kunci enkripsi kunci perantara yang kemudian dienkripsi dengan kunci Cloud KMS yang ditentukan.

Untuk tujuan penagihan, ini berarti panggilan Anda ke Cloud KMS maupun biaya terkait tidak akan diskalakan sesuai ukuran tabel. Untuk tabel yang dilindungi CMEK, Anda dapat menerima satu panggilan ke Cloud KMS cryptoKeys.encrypt untuk setiap pembuatan atau pemotongan tabel dan satu panggilan ke Cloud KMS cryptoKeys.decrypt untuk setiap tabel yang terlibat dalam kueri. Kedua metode ini termasuk dalam kategori Operasi kunci: Kriptografis yang tercantum dalam Harga Cloud KMS.

Membaca dari atau menulis ke tabel yang dilindungi CMEK yang ada akan memanggil cryptoKeys.decrypt Cloud KMS karena kunci perantara harus didekripsi.

Batasan

Akses BigQuery ke kunci Cloud KMS

Kunci Cloud KMS dianggap tersedia dan dapat diakses oleh BigQuery dalam kondisi berikut:

• Kunci diaktifkan
• Akun layanan BigQuery telah mengenkripsi dan mendekripsi izin pada kunci

Bagian berikut menjelaskan dampak terhadap streaming insert dan data jangka panjang yang tidak dapat diakses saat kunci tidak dapat diakses.

Dampak pada streaming insert

Kunci Cloud KMS harus tersedia dan dapat diakses setidaknya selama 24 jam berturut-turut dalam periode 48 jam setelah permintaan streaming insert. Jika kunci tidak tersedia dan dapat diakses, data yang di-streaming mungkin tidak sepenuhnya dipertahankan dan dapat hilang. Untuk informasi selengkapnya tentang streaming insert, lihat Streaming data ke BigQuery.

Dampak pada data jangka panjang yang tidak dapat diakses

Karena BigQuery menyediakan penyimpanan terkelola, data jangka panjang yang tidak dapat diakses tidak kompatibel dengan arsitektur BigQuery. Jika kunci Cloud KMS tabel BigQuery tertentu tidak tersedia dan tidak dapat diakses selama 60 hari berturut-turut, BigQuery dapat memilih untuk menghapus tabel tersebut dan data terkait. Setidaknya 7 hari sebelum data dihapus, BigQuery akan mengirimkan email ke alamat email yang terkait dengan akun penagihan.

Menggunakan sumber data eksternal

Jika Anda mengkueri data yang disimpan di sumber data eksternal seperti Cloud Storage yang memiliki data yang dienkripsi CMEK, enkripsi data akan dikelola oleh Cloud Storage. Misalnya, tabel BigLake mendukung data terenkripsi dengan CMEK di Cloud Storage.

BigQuery dan tabel BigLake tidak mendukung Kunci Enkripsi yang Disediakan Pelanggan (CSEK).

Beralih antara enkripsi yang dilindungi CMEK dan default

Anda tidak dapat mengganti tabel antara enkripsi default dan enkripsi CMEK. Untuk beralih enkripsi, salin tabel dengan kumpulan informasi enkripsi tujuan atau gunakan kueri SELECT * untuk memilih tabel itu sendiri dengan disposisi WRITE_TRUNCATE.

Menggunakan dekorator tabel

Jika Anda melindungi tabel dengan Cloud KMS lalu mengganti data dalam tabel menggunakan nilai WRITE_TRUNCATE untuk operasi load, cp, atau query, maka dekorator rentang tidak berfungsi di seluruh batas perubahan enkripsi. Anda masih dapat menggunakan dekorator tabel, termasuk dekorator rentang, untuk mengkueri data sebelum atau setelah batas, atau mengkueri snapshot pada waktu tertentu.

Kueri tabel karakter pengganti

Tabel yang dilindungi CMEK tidak dapat dikueri dengan akhiran karakter pengganti.

Dukungan edisi

Dukungan CMEK untuk BigQuery hanya tersedia untuk BigQuery Enterprise Plus dan BigQuery On-Demand. Pelanggan BigQuery yang menggunakan reservasi tarif tetap lama sebelum 5 Juli 2023, akan tetap mendapatkan semua dukungan yang ada untuk CMEK di tingkat Enterprise.

Dukungan BigQuery Studio

Aset kode BigQuery Studio, termasuk kueri tersimpan dan notebooks, tidak mendukung CMEK.

Pertanyaan umum (FAQ)

Siapa yang memerlukan izin ke kunci Cloud KMS?

Dengan kunci enkripsi yang dikelola pelanggan, Anda tidak perlu menentukan izin secara berulang. Selama akun layanan BigQuery memiliki izin untuk menggunakan kunci Cloud KMS untuk mengenkripsi dan mendekripsi, siapa pun yang memiliki izin ke tabel BigQuery dapat mengakses data, meskipun mereka tidak memiliki akses langsung ke kunci Cloud KMS.

Akun layanan mana yang digunakan?

Akun layanan BigQuery yang terkait dengan project Google Cloud pada tabel digunakan untuk mendekripsi data tabel tersebut. Akun layanan BigQuery bersifat unik untuk setiap project. Untuk tugas yang menulis data ke tabel anonim yang dilindungi Cloud KMS, akun layanan project tugas tersebut digunakan.

Sebagai contoh, pertimbangkan tiga tabel yang dilindungi CMEK: table1, table2, dan table3. Untuk mengkueri data dari {project1.table1, project2.table2} dengan tabel tujuan {project3.table3}:

• Gunakan akun layanan project1 untuk project1.table1
• Gunakan akun layanan project2 untuk project2.table2
• Gunakan akun layanan project3 untuk project3.table3

Dengan cara apa BigQuery dapat menggunakan kunci Cloud KMS saya?

BigQuery menggunakan kunci Cloud KMS untuk mendekripsi data sebagai respons terhadap kueri pengguna, misalnya, tabledata.list atau jobs.insert.

BigQuery juga dapat menggunakan kunci untuk tugas pengoptimalan penyimpanan dan pemeliharaan data, seperti konversi data ke format yang dioptimalkan untuk baca.

Library kriptografi apa yang digunakan?

BigQuery mengandalkan Cloud KMS untuk fungsi CMEK. Cloud KMS menggunakan Tink untuk enkripsi.

Bagaimana cara mendapatkan bantuan lebih lanjut?

Jika ada pertanyaan yang belum terjawab di sini, lihat dukungan BigQuery.

Pemecahan masalah terkait error

Berikut penjelasan tentang error umum dan mitigasi yang direkomendasikan.

Error	Rekomendasi
Berikan peran Pengenkripsi/Pendekripsi CryptoKey Cloud KMS	Akun layanan BigQuery yang terkait dengan project Anda tidak memiliki izin IAM yang memadai untuk beroperasi pada kunci Cloud KMS yang ditentukan. Ikuti petunjuk dalam kesalahan atau dalam dokumentasi ini untuk memberikan izin IAM yang tepat.
Setelan enkripsi tabel yang ada tidak cocok dengan setelan enkripsi yang ditentukan dalam permintaan	Hal ini dapat terjadi dalam skenario saat tabel tujuan memiliki setelan enkripsi yang tidak cocok dengan setelan enkripsi dalam permintaan Anda. Sebagai mitigasi, gunakan disposisi tulis TRUNCATE untuk mengganti tabel, atau tentukan tabel tujuan yang berbeda.
Region ini tidak didukung	Region kunci Cloud KMS tidak cocok dengan region set data BigQuery dari tabel tujuan. Sebagai mitigasi, pilih kunci di region yang cocok dengan set data Anda, atau muat ke set data yang cocok dengan region kunci.
Administrator mewajibkan Anda menentukan kunci enkripsi untuk kueri di project PROJECT_ID.	Kebijakan organisasi mencegah resource dibuat atau kueri dijalankan. Untuk mempelajari kebijakan ini lebih lanjut, lihat Mewajibkan CMEK untuk semua resource di project BigQuery.
Administrator Anda mencegah penggunaan kunci KMS dari project KMS_PROJECT_ID untuk melindungi resource dalam project PROJECT_ID.	Kebijakan organisasi mencegah resource dibuat atau kueri dijalankan. Untuk mempelajari kebijakan ini lebih lanjut, lihat Membatasi kunci Cloud KMS untuk project BigQuery.