ファイルセット エントリを使用して Cloud Storage からファイルを表示する

Data Catalog API を使用すると、Cloud Storage ファイルセット エントリ(このドキュメントの残りの部分では「ファイルセット」と呼びます)を作成および検索できます。

ファイルセット

Cloud Storage ファイルセットは、ユーザーが作成したエントリ グループ内のエントリです。詳細については、エントリとエントリ グループをご覧ください。

1 つ以上の一連の Cloud Storage ファイルを指定する 1 つ以上のファイル パターンによって定義されます。

ファイル パターンの要件:

  • ファイル パターンの先頭は gs://bucket_name/ にする必要があります。
  • バケット名は Cloud Storage バケット名の要件に従う必要があります。
  • ファイル パターンのフォルダとファイルの部分ではワイルドカードを使用できますが、バケット名ではワイルドカードを使用できません。例については、次をご覧ください。
  • ファイルセットには少なくとも 1 つのファイルセット パターン(最大 500 個)が必要です。

Dataflow SQL で Data Catalog ファイルセットをクエリできるのは、ファイルセットに定義済みのスキーマがあり、ヘッダー行を含まない CSV ファイルのみがある場合に限ります。

エントリ グループとファイルセットを作成する

ファイルセットは、ユーザーが作成したエントリ グループ内に配置する必要があります。エントリ グループを作成していない場合は、まずエントリ グループを作成してから、そのエントリ グループ内にファイルセットを作成します。エントリ グループに IAM ポリシーを設定すると、エントリ グループ内のファイルセットやその他のエントリにアクセスできるユーザーを定義できます。

コンソール

Console

  1. [Dataplex] > [エントリ グループ] ページに移動します。

    Dataplex エントリ グループに移動

  2. [エントリ グループを作成] をクリックします。

  3. [エントリ グループの作成] フォームに情報を入力し、[作成] をクリックします。

  4. [エントリ グループの詳細] ページが開きます。[エントリ] タブを選択した状態で、[作成] をクリックします。

  5. [ファイルセットの作成] フォームに情報を入力します。

    1. スキーマを添付するには、[スキーマを定義] をクリックして [スキーマ] フォームを開きます。[+ フィールドを追加] をクリックしてフィールドを個別に追加するか、フォームの右上にある [テキストとして編集] を切り替えて JSON 形式でフィールドを指定します。
    2. [保存] をクリックしてスキーマを保存します。
  6. [作成] をクリックしてファイルセットを作成します。

gcloud

gcloud

1. エントリ グループを作成する

gcloud data-catalog entry-groups create コマンドを使用して、スキーマと説明を添付したエントリ グループを作成します。

例:

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

2. エントリ グループ内にファイルセットを作成する

gcloud data-catalog entry create コマンドを使用して、エントリ グループ内にファイルセットを作成します。以下の gcloud コマンドの例では、ファイルセット データのスキーマを含むファイルセット エントリを作成します。

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 ..."

フラグに関する注:

  • --gcs-file-patterns: ファイル パターンの要件をご覧ください。
  • --schema-from-file: 次のサンプルは、--schema-from-file フラグで受け入れられるスキーマ テキスト ファイルの JSON 形式を示します。
    [
      {
        "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

このサンプルを試す前に、クライアント ライブラリを使用した Data Catalog のクイックスタートにある Java の設定手順を行ってください。 詳細については、Data Catalog Java API のリファレンス ドキュメントをご覧ください。

Data Catalog への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。

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

このサンプルを試す前に、クライアント ライブラリを使用した Data Catalog のクイックスタートにある Node.js の設定手順を行ってください。 詳細については、Data Catalog Node.js API のリファレンス ドキュメントをご覧ください。

Data Catalog への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。

// 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

このサンプルを試す前に、クライアント ライブラリを使用した Data Catalog のクイックスタートにある Python の設定手順を行ってください。 詳細については、Data Catalog Python API のリファレンス ドキュメントをご覧ください。

Data Catalog への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。

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

REST とコマンドライン

REST

ご使用の言語の Cloud クライアント ライブラリにアクセスしない場合、または REST リクエストを使用して API をテストする場合は、次の例を参照して、Data Catalog REST API entryGroups.create および entryGroups.entries.create のドキュメントをご覧ください。

1. エントリ グループを作成する

リクエストのデータを使用する前に、次のように置き換えます。

  • project-id: Google Cloud プロジェクト ID
  • entryGroupId: ID は、文字またはアンダースコアで始まり、英字、数字、アンダースコアのみを含み、64 文字以下である必要があります。
  • displayName: エントリ グループのテキスト名。

HTTP メソッドと URL:

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

JSON 本文のリクエスト:

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

リクエストを送信するには、次のいずれかのオプションを展開します。

次のような JSON レスポンスが返されます。

{
  "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. エントリ グループ内にファイルセットを作成する

リクエストのデータを使用する前に、次のように置き換えます。

  • project_id: Google Cloud プロジェクト ID
  • entryGroupId: 既存の entryGroup の ID。ファイルセットはこの entryGroup 内に作成されます。
  • entryId: 新しいファイルセットの EntryId。ID は、文字またはアンダースコアで始まり、英字、数字、アンダースコアのみを含み、64 文字以下である必要があります。
  • description: ファイルセットの説明。
  • displayName: ファイルセット エントリのテキスト名。
  • filePatterns: 「gs://bucket_name/」で始まる必要があります。ファイル パターンの要件をご覧ください。
  • schema: ファイルセットのスキーマ。

    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"
          }
        ]
      }
    ...
    }
    

HTTP メソッドと URL:

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

JSON 本文のリクエスト:

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

リクエストを送信するには、次のいずれかのオプションを展開します。

次のような JSON レスポンスが返されます。

{
  "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"
}

IAM のロール、権限、ポリシー

Data Catalog は、ファイルセットなどの Data Catalog リソースの権限を管理しやすくするために、エントリと entryGroup のロールを定義します。

エントリのロール 説明
dataCatalog.entryOwner 特定のエントリまたはエントリ グループのオーナー。
  • 権限:
    • datacatalog.entries.(*)
    • datacatalog.entryGroups.get
  • 適用範囲:
    • 組織、プロジェクト、entryGroup。
dataCatalog.entryViewer エントリと entryGroup の詳細を表示できます。
  • 権限
    • datacatalog.entries.get
    • datacatalog.entryGroups.get
  • 適用範囲:
    • 組織、プロジェクト、entryGroup。
entryGroup のロール 説明
dataCatalog.entryGroupOwner 特定の entryGroup のオーナー。
  • 権限:
    • datacatalog.entryGroups.(*)
    • datacatalog entries.(*)
  • 適用範囲:
    • 組織、プロジェクト、entryGroup のレベル。
dataCatalog.entryGroupCreator プロジェクト内に entryGroup を作成できます。entryGroup の作成者には自動的に dataCatalog.entryGroupOwner ロールが付与されます。
  • 権限
    • datacatalog.entryGroups.(get | create)
  • 適用範囲:
    • 組織レベルとプロジェクト レベル。

IAM ポリシーの設定

datacatalog.<resource>.setIamPolicy 権限を持つユーザーは、Data Catalog エントリ グループやその他の Data Catalog リソースに IAM ポリシーを設定できます(Data Catalog のロールを参照)。

gcloud

  • エントリ グループの IAM ポリシーを設定するには、gcloud data-catalog entry-groups set-iam-policy を使用します:

    gcloud data-catalog entry-groups set-iam-policy my_entrygroup \  
        --location=us-central1 \  
        policy file
    

  • エントリ グループの IAM ポリシーを取得するには、gcloud data-catalog entry-groups get-iam-policy を使用します

    gcloud data-catalog entry-groups get-iam-policy my_entrygroup \  
        --location=us-central1
    

Console

Data Catalog UI の [エントリ グループの詳細] ページに移動し、右側にある IAM パネルを使用して権限を付与するか取り消します。

エントリ グループのロールの付与

例 1:

ファイルセットに関してさまざまなビジネス コンテキストを使用する会社は、order-files および user-files エントリ グループを個別に作成します。

order-files グループには、キャンセルされた注文ファイルと完了した注文ファイルを含むストレージ バケットがあり、user-files グループには、PII ファイルを含むストレージ バケットがあります。
図 1: 注文データとユーザーデータを異なるエントリ グループに格納する方法の例。

このような会社は、order-files に関する EntryGroup 閲覧者のロールをユーザーに付与します。つまり、ユーザーはそのエントリ グループに含まれるエントリのみを検索できます。検索結果には user-files エントリ グループのエントリは返されません。

例 2:

会社は、project_entry_group プロジェクトの 1 人のユーザーにのみ EntryGroup 閲覧者のロールを付与します。そのユーザーはそのプロジェクト内のエントリのみを表示できます。

ファイルセットの検索

ユーザーは、type ファセットを使用して、Data Catalog の検索範囲を制限できます。type=entry_group は検索クエリをエントリ グループに制限しますが、type=fileset はファイルセットのみを検索します。type ファセットは、projectid などの他のファセットと組み合わせて使用できます。

gcloud

  • プロジェクト内のエントリ グループを検索します。

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

  • アクセスできるすべてのエントリ グループを検索します。

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

  • プロジェクト内のファイルセットを検索します。

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

  • プロジェクト内のファイルセットを検索します - 簡略化された構文:

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