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] > [エントリ グループ] ページに移動します。
[エントリ グループを作成] をクリックします。
[エントリ グループの作成] フォームに情報を入力し、[作成] をクリックします。
[エントリ グループの詳細] ページが開きます。[エントリ] タブを選択した状態で、[作成] をクリックします。
[ファイルセットの作成] フォームに情報を入力します。
- スキーマを添付するには、[スキーマを定義] をクリックして [スキーマ] フォームを開きます。[+ フィールドを追加] をクリックしてフィールドを個別に追加するか、フォームの右上にある [テキストとして編集] を切り替えて JSON 形式でフィールドを指定します。
- [保存] をクリックしてスキーマを保存します。
[作成] をクリックしてファイルセットを作成します。
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 への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
Node.js
このサンプルを試す前に、クライアント ライブラリを使用した Data Catalog のクイックスタートにある Node.js の設定手順を行ってください。 詳細については、Data Catalog Node.js API のリファレンス ドキュメントをご覧ください。
Data Catalog への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
Python
このサンプルを試す前に、クライアント ライブラリを使用した Data Catalog のクイックスタートにある Python の設定手順を行ってください。 詳細については、Data Catalog Python API のリファレンス ドキュメントをご覧ください。
Data Catalog への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
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.entryViewer |
エントリと entryGroup の詳細を表示できます。
|
entryGroup のロール | 説明 |
---|---|
dataCatalog.entryGroupOwner |
特定の entryGroup のオーナー。
|
dataCatalog.entryGroupCreator |
プロジェクト内に entryGroup を作成できます。entryGroup の作成者には自動的に dataCatalog.entryGroupOwner ロールが付与されます。
|
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
に関する 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"