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

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

ファイルセット

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

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

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

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

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

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

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

Console

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

Dataplex のエントリグループに移動
[エントリグループを作成] をクリックします。
[エントリグループの作成] フォームに情報を入力し、[作成] をクリックします。
[エントリグループの詳細] ページが開きます。[エントリ] タブを選択した状態で、[作成] をクリックします。
[ファイルセットの作成] フォームに情報を入力します。
1. スキーマを添付するには、[スキーマを定義] をクリックして [スキーマ] フォームを開きます。[+ フィールドを追加] をクリックしてフィールドを個別に追加するか、フォームの右上にある [テキストとして編集] を切り替えて JSON 形式でフィールドを指定します。
2. [保存] をクリックしてスキーマを保存します。
[作成] をクリックしてファイルセットを作成します。

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 のリファレンスドキュメントをご覧ください。

// 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 のリファレンスドキュメントをご覧ください。

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

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

curl（Linux、macOS、Cloud Shell）

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ユーザーアカウントで gcloud CLI にログインしているか、Cloud Shell を使用して自動的に gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project: project-id" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://datacatalog.googleapis.com/v1/projects/project-id/locations/region/entryGroups?entryGroupId=entryGroupId"

PowerShell（Windows）

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ユーザーアカウントで gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "project-id" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://datacatalog.googleapis.com/v1/projects/project-id/locations/region/entryGroups?entryGroupId=entryGroupId" | Select-Object -Expand Content

次のような 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 }
}

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

curl（Linux、macOS、Cloud Shell）

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project: project_id" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://datacatalog.googleapis.com/v1/projects/project_id/locations/region/entryGroups/entryGroupId/entries?entryId=entryId"

PowerShell（Windows）

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "project_id" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://datacatalog.googleapis.com/v1/projects/project_id/locations/region/entryGroups/entryGroupId/entries?entryId=entryId" | Select-Object -Expand Content

次のような 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 エントリグループを個別に作成します。

注文ファイルグループには、キャンセル済みおよび完了した注文ファイルを含むストレージバケットがありますが、ユーザーファイルグループには 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"

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