Menampilkan file dari Cloud Storage dengan entri kumpulan file

Anda dapat menggunakan Data Catalog API untuk membuat dan menelusuri entri kumpulan file Cloud Storage (disebut "filesets" di bagian lain dokumen ini).

Kumpulan File

Kumpulan file Cloud Storage adalah entri dalam grup entri yang dibuat pengguna. Untuk informasi selengkapnya, lihat Entri dan grup entri.

Batasan ditentukan oleh satu atau beberapa pola file yang menentukan kumpulan dari satu atau beberapa file Cloud Storage.

Persyaratan pola file:

  • Pola file harus diawali dengan gs://bucket_name/.
  • Nama bucket harus mengikuti persyaratan nama bucket Cloud Storage.
  • Karakter pengganti diizinkan dalam bagian folder dan file dari pola file, tetapi karakter pengganti tidak diizinkan dalam nama bucket. Untuk contoh, lihat:
  • Kumpulan file harus memiliki satu, dan tidak boleh memiliki lebih dari 500, pola kumpulan file.

Anda dapat membuat kueri kumpulan file Data Catalog dengan Dataflow SQL, tetapi hanya jika kumpulan file tersebut memiliki skema yang ditentukan dan hanya berisi file CSV tanpa baris header.

Membuat grup entri dan kumpulan file

Kumpulan file harus ditempatkan dalam grup entri yang dibuat pengguna. Jika Anda belum membuat grup entri, buat grup entri terlebih dahulu, lalu buat set file dalam grup entri. Anda dapat menetapkan kebijakan IAM pada grup entri untuk menentukan siapa yang memiliki akses ke kumpulan file dan entri lainnya dalam grup entri.

Konsol

Konsol

  1. Buka halaman Dataplex > Grup entri.

    Buka Grup entri Dataplex

  2. Klik Buat grup entri.

  3. Isi formulir Create Entry Group, lalu klik CREATE.

  4. Halaman Detail grup entri akan terbuka. Setelah memilih tab ENTRIES, klik CREATE.

  5. Isi formulir Create Fileset.

    1. Untuk melampirkan skema, klik Define Schema untuk membuka formulir Schema. Klik + TAMBAHKAN KOLOM untuk menambahkan kolom satu per satu atau aktifkan Edit sebagai teks di kanan atas formulir untuk menentukan kolom dalam format JSON.
    2. Klik Save untuk menyimpan skema.

  6. Klik Create untuk membuat kumpulan file.

gcloud

gcloud

1. Membuat grup entri

Gunakan perintah gcloud data-catalog entry-groups create untuk membuat grup entri dengan skema dan deskripsi terlampir.

Contoh:

gcloud data-catalog entry-groups create my_entrygroup \
    --location=us-central1

2. Membuat kumpulan file dalam grup entri

Gunakan perintah gcloud data-catalog entries create untuk membuat kumpulan file dalam grup entri. Contoh perintah gcloud di bawah ini, di bawah, akan membuat entri set file yang menyertakan skema data set file.

gcloud data-catalog entries create my_fileset_entry \  
    --location=us-central1 \  
    --entry-group=my_entrygroup \  
    --type=FILESET \  
    --gcs-file-patterns=gs://my-bucket/*.csv \  
    --schema-from-file=path_to_schema_file \  
    --description="Fileset description ..."

Tandai catatan:

  • --gcs-file-patterns: Lihat Persyaratan pola file.
  • --schema-from-file: Contoh berikut menunjukkan format JSON dari file teks skema yang diterima oleh flag --schema-from-file. 
    [
  {
    "column": "first_name",
    "description": "First name",
    "mode": "REQUIRED",
    "type": "STRING"
  },
  {
    "column": "last_name",
    "description": "Last name",
    "mode": "REQUIRED",
    "type": "STRING"
  },
  {
    "column": "address",
    "description": "Address",
    "mode": "REPEATED",
    "type": "STRING"
  }
]

Java

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Java di panduan memulai Katalog Data menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi API Data Catalog Java.

Untuk mengautentikasi ke Data Catalog, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal. 

import com.google.cloud.datacatalog.v1.ColumnSchema;
import com.google.cloud.datacatalog.v1.CreateEntryRequest;
import com.google.cloud.datacatalog.v1.DataCatalogClient;
import com.google.cloud.datacatalog.v1.Entry;
import com.google.cloud.datacatalog.v1.EntryGroupName;
import com.google.cloud.datacatalog.v1.EntryType;
import com.google.cloud.datacatalog.v1.GcsFilesetSpec;
import com.google.cloud.datacatalog.v1.Schema;
import java.io.IOException;

// Sample to create file set entry
public class CreateFilesetEntry {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "my-project-id";
    String entryGroupId = "fileset_entry_group";
    String entryId = "fileset_entry_id";
    createFilesetEntry(projectId, entryGroupId, entryId);
  }

  // Create Fileset Entry.
  public static void createFilesetEntry(String projectId, String entryGroupId, String entryId)
      throws IOException {
    // Currently, Data Catalog stores metadata in the us-central1 region.
    String location = "us-central1";

    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the "close" method on the client to safely clean up any remaining background resources.
    try (DataCatalogClient dataCatalogClient = DataCatalogClient.create()) {
      // Construct the Entry for the Entry request.
      Entry entry =
          Entry.newBuilder()
              .setDisplayName("My Fileset")
              .setDescription("This fileset consists of ....")
              .setGcsFilesetSpec(
                  GcsFilesetSpec.newBuilder().addFilePatterns("gs://cloud-samples-data/*").build())
              .setSchema(
                  Schema.newBuilder()
                      .addColumns(
                          ColumnSchema.newBuilder()
                              .setColumn("first_name")
                              .setDescription("First name")
                              .setMode("REQUIRED")
                              .setType("STRING")
                              .build())
                      .addColumns(
                          ColumnSchema.newBuilder()
                              .setColumn("last_name")
                              .setDescription("Last name")
                              .setMode("REQUIRED")
                              .setType("STRING")
                              .build())
                      .addColumns(
                          ColumnSchema.newBuilder()
                              .setColumn("addresses")
                              .setDescription("Addresses")
                              .setMode("REPEATED")
                              .setType("RECORD")
                              .addSubcolumns(
                                  ColumnSchema.newBuilder()
                                      .setColumn("city")
                                      .setDescription("City")
                                      .setMode("NULLABLE")
                                      .setType("STRING")
                                      .build())
                              .addSubcolumns(
                                  ColumnSchema.newBuilder()
                                      .setColumn("state")
                                      .setDescription("State")
                                      .setMode("NULLABLE")
                                      .setType("STRING")
                                      .build())
                              .build())
                      .build())
              .setType(EntryType.FILESET)
              .build();

      // Construct the Entry request to be sent by the client.
      CreateEntryRequest entryRequest =
          CreateEntryRequest.newBuilder()
              .setParent(EntryGroupName.of(projectId, location, entryGroupId).toString())
              .setEntryId(entryId)
              .setEntry(entry)
              .build();

      // Use the client to send the API request.
      Entry entryCreated = dataCatalogClient.createEntry(entryRequest);
      System.out.printf("Entry created with name: %s", entryCreated.getName());
    }
  }
}

Node.js

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Node.js di panduan memulai Katalog Data menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi API Data Catalog Node.js.

Untuk mengautentikasi ke Data Catalog, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal. 

// Import the Google Cloud client library.
const {DataCatalogClient} = require('@google-cloud/datacatalog').v1;
const datacatalog = new DataCatalogClient();

async function createFileset() {
  // Create a fileset within an entry group.

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const projectId = 'my_project';
  // const entryGroupId = 'my_entry_group';
  // const entryId = 'my_entry';

  // Currently, Data Catalog stores metadata in the us-central1 region.
  const location = 'us-central1';

  // Delete any pre-existing Entry with the same name that will be used
  // when creating the new Entry.
  try {
    const formattedName = datacatalog.entryPath(
      projectId,
      location,
      entryGroupId,
      entryId
    );
    await datacatalog.deleteEntry({name: formattedName});
  } catch (err) {
    console.log('Entry does not exist.');
  }

  // Delete any pre-existing Entry Group with the same name
  // that will be used to create the new Entry Group.
  try {
    const formattedName = datacatalog.entryGroupPath(
      projectId,
      location,
      entryGroupId
    );
    await datacatalog.deleteEntryGroup({name: formattedName});
  } catch (err) {
    console.log('Entry Group does not exist.');
  }

  // Construct the Entry Group for the Entry Group request.
  const entryGroup = {
    displayName: 'My Fileset Entry Group',
    description: 'This Entry Group consists of ....',
  };

  // Construct the Entry Group request to be sent by the client.
  const entryGroupRequest = {
    parent: datacatalog.locationPath(projectId, location),
    entryGroupId: entryGroupId,
    entryGroup: entryGroup,
  };

  // Use the client to send the API request.
  await datacatalog.createEntryGroup(entryGroupRequest);

  // Construct the Entry for the Entry request.
  const FILESET_TYPE = 4;

  const entry = {
    displayName: 'My Fileset',
    description: 'This fileset consists of ....',
    gcsFilesetSpec: {filePatterns: ['gs://my_bucket/*']},
    schema: {
      columns: [
        {
          column: 'city',
          description: 'City',
          mode: 'NULLABLE',
          type: 'STRING',
        },
        {
          column: 'state',
          description: 'State',
          mode: 'NULLABLE',
          type: 'STRING',
        },
        {
          column: 'addresses',
          description: 'Addresses',
          mode: 'REPEATED',
          subcolumns: [
            {
              column: 'city',
              description: 'City',
              mode: 'NULLABLE',
              type: 'STRING',
            },
            {
              column: 'state',
              description: 'State',
              mode: 'NULLABLE',
              type: 'STRING',
            },
          ],
          type: 'RECORD',
        },
      ],
    },
    type: FILESET_TYPE,
  };

  // Construct the Entry request to be sent by the client.
  const request = {
    parent: datacatalog.entryGroupPath(projectId, location, entryGroupId),
    entryId: entryId,
    entry: entry,
  };

  // Use the client to send the API request.
  const [response] = await datacatalog.createEntry(request);

  console.log(`Name: ${response.name}`);
  console.log(`Display name: ${response.displayName}`);
  console.log(`Type: ${response.type}`);
}
createFileset();

Python

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Python di panduan memulai Katalog Data menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi API Data Catalog Python.

Untuk mengautentikasi ke Data Catalog, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal. 

# Import required modules.
from google.cloud import datacatalog_v1

# TODO: Set these values before running the sample.
project_id = "project_id"
fileset_entry_group_id = "entry_group_id"
fileset_entry_id = "entry_id"

# For all regions available, see:
# https://cloud.google.com/data-catalog/docs/concepts/regions
location = "us-central1"

datacatalog = datacatalog_v1.DataCatalogClient()

# Create an Entry Group.
entry_group_obj = datacatalog_v1.types.EntryGroup()
entry_group_obj.display_name = "My Fileset Entry Group"
entry_group_obj.description = "This Entry Group consists of ...."

entry_group = datacatalog.create_entry_group(
    parent=datacatalog_v1.DataCatalogClient.common_location_path(
        project_id, location
    ),
    entry_group_id=fileset_entry_group_id,
    entry_group=entry_group_obj,
)
print(f"Created entry group: {entry_group.name}")

# Create a Fileset Entry.
entry = datacatalog_v1.types.Entry()
entry.display_name = "My Fileset"
entry.description = "This fileset consists of ...."
entry.gcs_fileset_spec.file_patterns.append("gs://my_bucket/*.csv")
entry.type_ = datacatalog_v1.EntryType.FILESET

# Create the Schema, for example when you have a csv file.
entry.schema.columns.append(
    datacatalog_v1.types.ColumnSchema(
        column="first_name",
        description="First name",
        mode="REQUIRED",
        type_="STRING",
    )
)

entry.schema.columns.append(
    datacatalog_v1.types.ColumnSchema(
        column="last_name", description="Last name", mode="REQUIRED", type_="STRING"
    )
)

# Create the addresses parent column
addresses_column = datacatalog_v1.types.ColumnSchema(
    column="addresses", description="Addresses", mode="REPEATED", type_="RECORD"
)

# Create sub columns for the addresses parent column
addresses_column.subcolumns.append(
    datacatalog_v1.types.ColumnSchema(
        column="city", description="City", mode="NULLABLE", type_="STRING"
    )
)

addresses_column.subcolumns.append(
    datacatalog_v1.types.ColumnSchema(
        column="state", description="State", mode="NULLABLE", type_="STRING"
    )
)

entry.schema.columns.append(addresses_column)

entry = datacatalog.create_entry(
    parent=entry_group.name, entry_id=fileset_entry_id, entry=entry
)
print(f"Created fileset entry: {entry.name}")

BARIS REST & CMD

REST

Jika Anda tidak memiliki akses ke library Klien Cloud untuk bahasa Anda atau ingin menguji API menggunakan permintaan REST, lihat contoh berikut dan lihat dokumentasi entryGroups.create dan entryGroups.entries.create REST API Data Catalog.

1. Membuat grup entri

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • project-id: ID Project Google Cloud Anda
  • entryGroupId: ID harus diawali dengan huruf atau garis bawah, hanya berisi huruf, angka, dan garis bawah dalam bahasa Inggris, dan berisi maksimal 64 karakter.
  • displayName: Nama tekstual untuk grup entri.

Metode HTTP dan URL: 

POST https://datacatalog.googleapis.com/v1/projects/project-id/locations/region/entryGroups?entryGroupId=entryGroupId

Meminta isi JSON: 

{
  "displayName": "Entry Group display name"
}

Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

Anda akan melihat respons JSON seperti berikut:

{
  "name": "projects/my_projectid/locations/us-central1/entryGroups/my_entry_group",
  "displayName": "Entry Group display name",
  "dataCatalogTimestamps": {
    "createTime": "2019-10-19T16:35:50.135Z",
    "updateTime": "2019-10-19T16:35:50.135Z"
  }
}

2. Membuat kumpulan file dalam grup entri

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • project_id: ID Project Google Cloud Anda
  • entryGroupId: ID entryGroup yang ada. Kumpulan file akan dibuat di sntryGroup ini.
  • entryId: EntryId kumpulan file baru. ID harus diawali dengan huruf atau garis bawah, hanya berisi huruf, angka, dan garis bawah dalam bahasa Inggris, dan berisi maksimal 64 karakter.
  • description: Deskripsi kumpulan file.
  • displayName: Nama tekstual untuk entri kumpulan file.
  • filePatterns: Harus diawali dengan "gs://bucket_name/". Lihat Persyaratan pola file.
  • schema: Skema kumpulan file.

    Contoh skema JSON: 
    { ...
  "schema": {
    "columns": [
      {
        "column": "first_name",
        "description": "First name",
        "mode": "REQUIRED",
        "type": "STRING"
      },
      {
        "column": "last_name",
        "description": "Last name",
        "mode": "REQUIRED",
        "type": "STRING"
      },
      {
        "column": "address",
        "description": "Address",
        "mode": "REPEATED",
        "subcolumns": [
          {
            "column": "city",
            "description": "City",
            "mode": "NULLABLE",
            "type": "STRING"
          },
          {
            "column": "state",
            "description": "State",
            "mode": "NULLABLE",
            "type": "STRING"
          }
        ],
        "type": "RECORD"
      }
    ]
  }
...
}

Metode HTTP dan URL: 

POST https://datacatalog.googleapis.com/v1/projects/project_id/locations/region/entryGroups/entryGroupId/entries?entryId=entryId

Meminta isi JSON: 

{
  "description": "Fileset description.",
  "displayName": "Display name",
  "gcsFilesetSpec": {
    "filePatterns": [
      "gs://bucket_name/file_pattern"
    ]
  },
  "type": "FILESET",
  "schema": { schema }
}

Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

Anda akan melihat respons JSON seperti berikut:

{
  "name": "projects/my_project_id/locations/us-central1/entryGroups/my_entryGroup_id/entries/my_entry_id",
  "type": "FILESET",
  "displayName": "My Fileset",
  "description": "My Fileset description.",
  "schema": {
    "columns": [
      {
        "type": "STRING",
        "description": "First name",
        "mode": "REQUIRED",
        "column": "first_name"
      },
      {
        "type": "STRING",
        "description": "Last name",
        "mode": "REQUIRED",
        "column": "last_name"
      },
      {
        "type": "RECORD",
        "description": "Address",
        "mode": "REPEATED",
        "column": "address",
        "subcolumns": [
          {
            "type": "STRING",
            "description": "City",
            "mode": "NULLABLE",
            "column": "city"
          },
          {
            "type": "STRING",
            "description": "State",
            "mode": "NULLABLE",
            "column": "state"
          }
        ]
      }
    ]
  },
  "gcsFilesetSpec": {
    "filePatterns": [
      "gs://my_bucket_name/chicago_taxi_trips/csv/shard-*.csv"
    ]
  },
  "sourceSystemTimestamps": {
    "createTime": "2019-10-23T23:11:26.326Z",
    "updateTime": "2019-10-23T23:11:26.326Z"
  },
"linkedResource": "//datacatalog.googleapis.com/projects/my_project_id/locations/us-central1/entryGroups/my_entryGroup_id/entries/my_entry_id"
}

Peran, Izin, dan Kebijakan IAM

Data Catalog menentukan peran entri dan entryGroup untuk memfasilitasi pengelolaan izin kumpulan file dan resource Data Catalog lainnya.

Peran entri Deskripsi
dataCatalog.entryOwner Pemilik entri atau grup entri tertentu.
  • Izin:
    • datacatalog.entries.(*)
    • datacatalog.entryGroups.get
  • Keberlakuan:
    • Organization, project, dan entryGroup.
dataCatalog.entryViewer Dapat melihat detail entri & entryGroup.
  • Izin
    • datacatalog.entries.get
    • datacatalog.entryGroups.get
  • Keberlakuan:
    • Organization, project, dan entryGroup.
peran entryGroup Deskripsi
dataCatalog.entryGroupOwner Pemilik entryGroup tertentu.
  • Izin:
    • datacatalog.entryGroups.(*)
    • entri datacatalog.(*)
  • Keberlakuan:
    • Tingkat organisasi, project, dan entryGroups.
dataCatalog.entryGroupCreator Dapat membuat entryGroups dalam project. Pembuat entryGroup secara otomatis diberi peran dataCatalog.entryGroupOwner.
  • Izin
    • datacatalog.entryGroups.(dapatkan | buat)
  • Keberlakuan:
    • Tingkat organisasi dan project.

Menetapkan kebijakan IAM

Pengguna dengan izin datacatalog.<resource>.setIamPolicy dapat menetapkan kebijakan IAM pada grup entri Data Catalog dan resource Data Catalog lainnya (lihat peran Data Catalog).

gcloud

Konsol

Buka halaman Detail grup entri di UI Data Catalog, lalu gunakan panel IAM yang terletak di sisi kanan untuk memberikan atau mencabut izin.

Memberikan peran Grup Entri

Contoh 1:

Perusahaan dengan konteks bisnis yang berbeda untuk kumpulan filenya membuat grup entri order-files dan user-files yang terpisah:

Grup file pesanan memiliki bucket penyimpanan dengan file urutan yang dibatalkan dan selesai, sedangkan grup file pengguna memiliki bucket penyimpanan dengan file PII.
Gambar 1. Contoh cara menyimpan data pesanan dan data pengguna di berbagai grup entri.

Perusahaan memberi pengguna peran EntryGroup Viewer untuk order-files, yang berarti mereka hanya dapat menelusuri entri yang ada dalam grup entri tersebut. Hasil penelusurannya tidak menampilkan entri dalam grup entri user-files.

Contoh 2:

Perusahaan memberikan peran EntryGroup Viewer kepada pengguna hanya dalam project project_entry_group. Pengguna hanya dapat melihat entri dalam project tersebut.

Menelusuri kumpulan file

Pengguna dapat membatasi cakupan penelusuran di Data Catalog menggunakan faset type. type=entry_group membatasi kueri penelusuran untuk grup entri, sedangkan type=fileset hanya menelusuri kumpulan file. Faset type dapat digunakan bersama dengan faset lain, seperti projectid.

gcloud

  • Menelusuri grup entri dalam sebuah project: 

    gcloud data-catalog search \  
    --include-project-ids=my-project
    "projectid=my-project type=entry_group"

  • Telusuri semua grup entri yang dapat Anda akses: 

    gcloud data-catalog search \  
    --include-project-ids=my-project
    "type=entry_group"

  • Menelusuri kumpulan file dalam sebuah project: 

    gcloud data-catalog search \  
    --include-project-ids=my-project
    "type=entry.fileset"

  • Telusuri kumpulan file dalam project - sintaksis yang disederhanakan: 

    gcloud data-catalog search \  
    --include-project-ids=my-project
    "type=fileset"