Membuat dan menggunakan pemindaian profil data

Knowledge Catalog (sebelumnya Dataplex Universal Catalog) memungkinkan Anda mengidentifikasi karakteristik statistik umum (nilai umum, distribusi data, jumlah nilai null) kolom di tabel BigQuery Anda. Informasi ini membantu Anda memahami dan menganalisis data secara lebih efektif.

Untuk mengetahui informasi selengkapnya tentang pemindaian profil data Knowledge Catalog, lihat Tentang pembuatan profil data.

Sebelum memulai

Mengaktifkan Dataplex API.

Mengaktifkan API

Peran dan izin yang diperlukan

Bagian ini menjelaskan peran dan izin IAM yang diperlukan untuk menggunakan pemindaian profil data Knowledge Catalog.

Peran dan izin pengguna

Untuk mendapatkan izin yang Anda perlukan untuk membuat dan mengelola pemindaian profil data, minta administrator untuk memberi Anda peran IAM berikut:

• Membuat, menjalankan, memperbarui, dan menghapus pemindaian profil data: Editor Dataplex DataScan (roles/dataplex.dataScanEditor) di project yang berisi pemindaian data
• Melihat hasil, tugas, dan histori pemindaian profil data: Dataplex DataScan Viewer (roles/dataplex.dataScanViewer) pada project yang berisi pemindaian data
• Publikasikan hasil pemindaian profil data ke Knowledge Catalog: Dataplex Catalog Editor (roles/dataplex.catalogEditor) di grup entri @bigquery
• Melihat hasil pemindaian profil data yang dipublikasikan di BigQuery pada tab Profil data: BigQuery Data Viewer (roles/bigquery.dataViewer) pada tabel

Untuk mengetahui informasi selengkapnya tentang pemberian peran, lihat Mengelola akses ke project, folder, dan organisasi.

Peran bawaan ini berisi izin yang diperlukan untuk membuat dan mengelola pemindaian profil data. Untuk melihat izin yang benar-benar diperlukan, perluas bagian Izin yang diperlukan:

Anda mungkin juga bisa mendapatkan izin ini dengan peran khusus atau peran bawaan lainnya.

Peran dan izin akun layanan Knowledge Catalog

Untuk memastikan akun layanan Knowledge Catalog memiliki izin yang diperlukan untuk menjalankan pemindaian profil data dan mengekspor hasil, minta administrator Anda untuk memberikan peran IAM berikut kepada akun layanan Knowledge Catalog:

• Jalankan pemindaian profil data terhadap data BigQuery:
  • Pengguna Tugas BigQuery (roles/bigquery.jobUser) di project yang menjalankan pemindaian
  • BigQuery Data Viewer (roles/bigquery.dataViewer) pada tabel yang dipindai
• Menjalankan pemindaian profil data untuk tabel eksternal BigQuery yang menggunakan data Cloud Storage:
  • Storage Object Viewer (roles/storage.objectViewer) di bucket Cloud Storage
  • Storage Legacy Bucket Reader (roles/storage.legacyBucketReader) di bucket Cloud Storage
• Jalankan pemindaian profil data untuk tabel Katalog REST Iceberg di Google Cloud Lakehouse: BigLake Viewer (roles/biglake.viewer) pada tabel Iceberg Rest Catalog yang dipindai
• Mengekspor hasil pemindaian profil data ke tabel BigQuery: BigQuery Data Editor (roles/bigquery.dataEditor) di tabel

Untuk mengetahui informasi selengkapnya tentang pemberian peran, lihat Mengelola akses ke project, folder, dan organisasi.

Peran bawaan ini berisi izin yang diperlukan untuk menjalankan pemindaian profil data dan mengekspor hasilnya. Untuk melihat izin yang benar-benar diperlukan, perluas bagian Izin yang diperlukan:

Administrator Anda mungkin juga dapat memberikan izin ini kepada akun layanan Knowledge Catalog dengan peran khusus atau peran bawaan lainnya.

Jika tabel menggunakan keamanan tingkat baris BigQuery, Knowledge Catalog hanya dapat memindai baris yang terlihat oleh akun layanan Knowledge Catalog. Untuk mengizinkan Knowledge Catalog memindai semua baris, tambahkan akun layanannya ke filter baris dengan predikat TRUE.

Jika tabel menggunakan keamanan tingkat kolom BigQuery, maka Knowledge Catalog memerlukan akses untuk memindai kolom yang dilindungi. Untuk memberikan akses, berikan peran Data Catalog Fine-Grained Reader (roles/datacatalog.fineGrainedReader) kepada akun layanan Knowledge Catalog di semua tag kebijakan yang digunakan dalam tabel. Pengguna yang membuat atau memperbarui pemindaian data juga memerlukan izin pada kolom yang dilindungi.

Memberikan peran ke akun layanan Knowledge Catalog

Untuk menjalankan pemindaian profil data, Knowledge Catalog menggunakan akun layanan yang memerlukan izin untuk menjalankan tugas BigQuery dan membaca data tabel BigQuery. Untuk memberikan peran yang diperlukan, ikuti langkah-langkah berikut:

1. Dapatkan alamat email akun layanan Knowledge Catalog. Jika Anda belum membuat profil data atau pemindaian kualitas data di project ini sebelumnya, jalankan perintah gcloud berikut untuk membuat identitas layanan:

   gcloud beta services identity create --service=dataplex.googleapis.com
   

   Perintah ini menampilkan email akun layanan, yang memiliki format berikut: service-PROJECT_ID@gcp-sa-dataplex.iam.gserviceaccount.com.

   Jika akun layanan sudah ada, Anda dapat menemukan emailnya dengan melihat akun utama dengan nama Dataplex di halaman IAM di konsol Google Cloud .

2. Beri akun layanan peran BigQuery Job User (roles/bigquery.jobUser) di project Anda. Peran ini memungkinkan akun layanan menjalankan tugas BigQuery untuk pemindaian.

   gcloud projects add-iam-policy-binding PROJECT_ID \
       --member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com" \
       --role="roles/bigquery.jobUser"
   

   Ganti kode berikut:

   • PROJECT_ID: Google Cloud Project ID Anda.
   • service-PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com: email akun layanan Knowledge Catalog.

3. Beri akun layanan peran BigQuery Data Viewer (roles/bigquery.dataViewer) untuk setiap tabel yang ingin Anda buat profilnya. Peran ini memberikan akses hanya baca ke tabel.

   gcloud bigquery tables add-iam-policy-binding DATASET_ID.TABLE_ID \
       --member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com" \
       --role="roles/bigquery.dataViewer"
   

   Ganti kode berikut:

   • DATASET_ID: ID set data yang berisi tabel.
   • TABLE_ID: ID tabel yang akan dibuat profilnya.
   • service-PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com: email akun layanan Knowledge Catalog.

Mengonfigurasi identitas eksekusi

Secara default, pemindaian profil data dijalankan menggunakan Agen Layanan Knowledge Catalog. Anda dapat mengganti setelan ini untuk menggunakan akun layanan kustom atau Kredensial Pengguna Akhir (EUC) Anda sendiri.

Menggunakan identitas eksekusi kustom akan mengubah cara penagihan pemindaian. Saat Anda menentukan identitas eksekusi kustom, biaya komputasi dan penyimpanan yang terkait dengan pemindaian akan ditagih langsung ke project BigQuery Anda, tanpa melalui SKU Premium Knowledge Catalog standar.

Izin yang diperlukan untuk identitas eksekusi kustom

Untuk mengonfigurasi akun layanan kustom atau menggunakan kredensial pengguna akhir, Anda harus memiliki izin IAM tambahan berikut:

• Untuk menggunakan akun layanan kustom, Anda memerlukan izin berikut:
  • Izin iam.serviceAccounts.actAs yang diberikan untuk project yang berisi akun layanan (misalnya, roles/iam.serviceAccountUser).
  • Agen Layanan project Anda (service-PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com) memerlukan izin iam.serviceAccounts.getAccessToken pada akun layanan kustom (misalnya, dengan memiliki peran roles/iam.serviceAccountTokenCreator).
  • Akun layanan kustom memerlukan bigquery.tables.getData pada tabel untuk memindai, bigquery.jobs.insert di project pemindaian, dan bigquery.dataEditor pada set data ekspor (jika menggunakan ekspor).
• Untuk menggunakan Kredensial Pengguna Akhir, Anda memerlukan:
  • bigquery.tables.getData di atas meja untuk dipindai.
  • bigquery.jobs.insert di project pemindaian.
  • bigquery.dataEditor pada set data ekspor (jika menggunakan ekspor).

Untuk mengonfigurasi identitas eksekusi, pilih salah satu opsi berikut:

"executionIdentity": {
  "serviceAccount": {
     "email": "YOUR_SERVICE_ACCOUNT_EMAIL"
  }
}
  

"executionIdentity": {
  "userCredential": {}
}
  

Membuat pemindaian profil data

gcloud dataplex datascans create data-profile DATASCAN \
--location=LOCATION \
--data-source-entity=DATA_SOURCE_ENTITY

gcloud dataplex datascans create data-profile DATASCAN \
--location=LOCATION \
--data-source-resource=DATA_SOURCE_RESOURCE

using Google.Api.Gax.ResourceNames;
using Google.Cloud.Dataplex.V1;
using Google.LongRunning;

public sealed partial class GeneratedDataScanServiceClientSnippets
{
    /// <summary>Snippet for CreateDataScan</summary>
    /// <remarks>
    /// This snippet has been automatically generated and should be regarded as a code template only.
    /// It will require modifications to work:
    /// - It may require correct/in-range values for request initialization.
    /// - It may require specifying regional endpoints when creating the service client as shown in
    ///   https://cloud.google.com/dotnet/docs/reference/help/client-configuration#endpoint.
    /// </remarks>
    public void CreateDataScanRequestObject()
    {
        // Create client
        DataScanServiceClient dataScanServiceClient = DataScanServiceClient.Create();
        // Initialize request argument(s)
        CreateDataScanRequest request = new CreateDataScanRequest
        {
            ParentAsLocationName = LocationName.FromProjectLocation("[PROJECT]", "[LOCATION]"),
            DataScan = new DataScan(),
            DataScanId = "",
            ValidateOnly = false,
        };
        // Make the request
        Operation<DataScan, OperationMetadata> response = dataScanServiceClient.CreateDataScan(request);

        // Poll until the returned long-running operation is complete
        Operation<DataScan, OperationMetadata> completedResponse = response.PollUntilCompleted();
        // Retrieve the operation result
        DataScan result = completedResponse.Result;

        // Or get the name of the operation
        string operationName = response.Name;
        // This name can be stored, then the long-running operation retrieved later by name
        Operation<DataScan, OperationMetadata> retrievedResponse = dataScanServiceClient.PollOnceCreateDataScan(operationName);
        // Check if the retrieved long-running operation has completed
        if (retrievedResponse.IsCompleted)
        {
            // If it has completed, then access the result
            DataScan retrievedResult = retrievedResponse.Result;
        }
    }
}

//go:build examples

package main

import (
	"context"

	dataplex "cloud.google.com/go/dataplex/apiv1"
	dataplexpb "cloud.google.com/go/dataplex/apiv1/dataplexpb"
)

func main() {
	ctx := context.Background()
	// This snippet has been automatically generated and should be regarded as a code template only.
	// It will require modifications to work:
	// - It may require correct/in-range values for request initialization.
	// - It may require specifying regional endpoints when creating the service client as shown in:
	//   https://pkg.go.dev/cloud.google.com/go#hdr-Client_Options
	c, err := dataplex.NewDataScanClient(ctx)
	if err != nil {
		// TODO: Handle error.
	}
	defer c.Close()

	req := &dataplexpb.CreateDataScanRequest{
		// TODO: Fill request struct fields.
		// See https://pkg.go.dev/cloud.google.com/go/dataplex/apiv1/dataplexpb#CreateDataScanRequest.
	}
	op, err := c.CreateDataScan(ctx, req)
	if err != nil {
		// TODO: Handle error.
	}

	resp, err := op.Wait(ctx)
	if err != nil {
		// TODO: Handle error.
	}
	// TODO: Use resp.
	_ = resp
}

import com.google.cloud.dataplex.v1.CreateDataScanRequest;
import com.google.cloud.dataplex.v1.DataScan;
import com.google.cloud.dataplex.v1.DataScanServiceClient;
import com.google.cloud.dataplex.v1.LocationName;

public class SyncCreateDataScan {

  public static void main(String[] args) throws Exception {
    syncCreateDataScan();
  }

  public static void syncCreateDataScan() throws Exception {
    // This snippet has been automatically generated and should be regarded as a code template only.
    // It will require modifications to work:
    // - It may require correct/in-range values for request initialization.
    // - It may require specifying regional endpoints when creating the service client as shown in
    // https://cloud.google.com/java/docs/setup#configure_endpoints_for_the_client_library
    try (DataScanServiceClient dataScanServiceClient = DataScanServiceClient.create()) {
      CreateDataScanRequest request =
          CreateDataScanRequest.newBuilder()
              .setParent(LocationName.of("[PROJECT]", "[LOCATION]").toString())
              .setDataScan(DataScan.newBuilder().build())
              .setDataScanId("dataScanId1260787906")
              .setValidateOnly(true)
              .build();
      DataScan response = dataScanServiceClient.createDataScanAsync(request).get();
    }
  }
}

# Copyright 2026 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#      http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

import google.api_core.exceptions
from google.cloud import dataplex_v1


def create_data_profile_scan_global(
    project_id: str,
    dataset_id: str,
    table_id: str,
    location: str,
) -> None:
    """Creates a Dataplex Data Profile Scan using global API endpoint routing.

    Args:
        project_id (str): Google Cloud project ID where the scan is created.
        dataset_id (str): Target BigQuery dataset ID.
        table_id (str): Target BigQuery table ID to scan.
        location (str): Google Cloud region where serverless compute runs.
    """
    client = dataplex_v1.DataScanServiceClient()

    parent = client.common_location_path(project=project_id, location=location)

    bigquery_table = (
        f"//bigquery.googleapis.com/projects/{project_id}"
        f"/datasets/{dataset_id}/tables/{table_id}"
    )

    data_profile_spec = dataplex_v1.DataProfileSpec(sampling_percent=100.0)

    data_scan = dataplex_v1.DataScan(
        display_name="Global Data Profile Scan",
        description="Regional data profile scan generating automated table statistics.",
        data=dataplex_v1.DataSource(resource=bigquery_table),
        data_profile_spec=data_profile_spec,
    )

    request = dataplex_v1.CreateDataScanRequest(
        parent=parent,
        data_scan=data_scan,
    )

    try:
        operation = client.create_data_scan(request=request)
        print(operation.result())

    except google.api_core.exceptions.AlreadyExists:
        print("A scan with this ID already exists.")
    except google.api_core.exceptions.InvalidArgument as e:
        print(f"Your scan configuration is invalid: {e}")
    except google.api_core.exceptions.GoogleAPIError as e:
        print(f"Unexpected exception: {e}")

require "google/cloud/dataplex/v1"

##
# Snippet for the create_data_scan call in the DataScanService service
#
# This snippet has been automatically generated and should be regarded as a code
# template only. It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
# client as shown in https://cloud.google.com/ruby/docs/reference.
#
# This is an auto-generated example demonstrating basic usage of
# Google::Cloud::Dataplex::V1::DataScanService::Client#create_data_scan.
#
def create_data_scan
  # Create a client object. The client can be reused for multiple calls.
  client = Google::Cloud::Dataplex::V1::DataScanService::Client.new

  # Create a request. To set request fields, pass in keyword arguments.
  request = Google::Cloud::Dataplex::V1::CreateDataScanRequest.new

  # Call the create_data_scan method.
  result = client.create_data_scan request

  # The returned object is of type Gapic::Operation. You can use it to
  # check the status of an operation, cancel it, or wait for results.
  # Here is how to wait for a response.
  result.wait_until_done! timeout: 60
  if result.response?
    p result.response
  else
    puts "No response received."
  end
end

Mengekspor skema tabel

Jika Anda ingin mengekspor hasil pemindaian profil data ke tabel BigQuery yang ada, pastikan tabel tersebut kompatibel dengan skema tabel berikut: