メタデータのインポート

Dataplex Catalog メタデータ（エントリとそのアスペクト）をサードパーティのシステムから Dataplex にインポートできます。

メタデータをインポートする際の手順の概要は次のとおりです。

ジョブのスコープを決定します。

また、Dataplex がエントリとアスペクトに比較ロジックと同期モードを適用する方法についても説明します。
インポートするデータを定義するメタデータインポートファイルを 1 つ以上作成します。
メタデータのインポートファイルを Cloud Storage バケットに保存します。
メタデータのインポートジョブを実行します。

このページの手順は、エントリグループ、エントリタイプ、アスペクトタイプなど、Dataplex Catalog のコンセプトに精通していることを前提としています。詳細については、Dataplex Catalog の概要をご覧ください。

始める前に

メタデータをインポートする前に、このセクションのタスクを完了します。

必要なロール

Dataplex サービスアカウントに Cloud Storage バケットへのアクセスに必要な権限が付与されるようにするには、Dataplex サービスアカウントにバケットに対するストレージオブジェクト閲覧者（roles/storage.objectViewer）IAM ロールと storage.buckets.get 権限を付与するよう管理者に依頼してください。

メタデータジョブを管理するために必要な権限を取得するには、次の IAM ロールを付与するよう管理者に依頼してください。

エントリタイプまたはエントリタイプが定義されているプロジェクトに対する Dataplex エントリタイプユーザー（roles/dataplex.entryTypeUser）
アスペクトタイプまたはアスペクトタイプが定義されているプロジェクトに対する Dataplex アスペクトタイプユーザー（roles/dataplex.aspectTypeUser）
メタデータジョブを作成する:
- プロジェクトまたはリソースに対する Dataplex エントリグループインポータ（roles/dataplex.entryGroupImporter）
- プロジェクトまたはリソースに対する Dataplex エントリオーナー（roles/dataplex.entryOwner）
メタデータジョブを表示する: プロジェクトに対する Dataplex メタデータジョブ閲覧者（roles/dataplex.metadataJobViewer）
メタデータジョブを作成、表示、キャンセルする: プロジェクトに対する Dataplex メタデータジョブオーナー（roles/dataplex.metadataJobOwner）

ロールの付与の詳細については、アクセス権の管理をご覧ください。

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

Google Cloud リソースを作成する

次の Google Cloud リソースを準備します。

インポートするエントリのエントリグループを作成します。
インポートするアスペクトのアスペクトタイプを作成します。
インポートするエントリのエントリタイプを作成します。
メタデータインポートファイルを格納する Cloud Storage バケットを作成します。

メタデータジョブのコンポーネント

メタデータをインポートする際は、メタデータジョブの次のコンポーネントを考慮してください。

ジョブのスコープ: ジョブに設定するエントリグループ、エントリタイプ、アスペクトタイプ。
同期モード: ジョブ内のエントリとアスペクトに対して完全な更新と増分更新のどちらを行うか。
メタデータインポートファイル: ジョブ内のエントリとアスペクトに設定する値を定義するファイル。同じメタデータジョブで複数のメタデータインポートファイルを指定できます。ファイルを Cloud Storage に保存します。
比較ロジック: 変更するエントリとアスペクトを Dataplex が決定する方法。

ジョブのスコープ

ジョブスコープでは、エントリグループ、エントリタイプ、必要に応じてメタデータジョブに配置するアスペクトタイプを定義します。メタデータをインポートした際に、ジョブのスコープ内のリソースに属するエントリとアスペクトを変更します。

ジョブのスコープを定義するには、次のガイドラインに従ってください。

エントリグループ: ジョブに配置する単一のエントリグループを指定します。ジョブは、このエントリグループに属するエントリのみを変更します。エントリグループとジョブは同じリージョンに存在する必要があります。
エントリタイプ: ジョブに設定する 1 つ以上のエントリタイプを指定します。ジョブは、これらのエントリタイプに属するエントリのみを変更します。エントリタイプのロケーションは、ジョブのロケーションと一致しているか、エントリタイプがグローバルであることが必要です。
アスペクトタイプ: 省略可。ジョブに設定するアスペクトタイプを 1 つ以上指定します。アスペクトタイプのスコープを指定すると、ジョブはそれらのアスペクトタイプに属するアスペクトのみを変更します。アスペクトタイプのロケーションは、ジョブのロケーションと一致しているか、アスペクトタイプがグローバルであることが必要です。

ジョブスコープは、メタデータジョブを作成するときに指定します。

同期モード

同期モードでは、メタデータジョブ内のエントリとアスペクトに対して完全な更新と増分更新のどちらを実行するかを指定します。

FULL: エントリに対してサポートされます。ジョブのスコープ内のすべてのエントリが変更されます。

Dataplex にエントリが存在しても、メタデータインポートファイルに含まれていない場合は、メタデータジョブの実行時にエントリが削除されます。

アスペクトに対する完全同期はサポートされていません。
INCREMENTAL: アスペクトでサポートされます。アスペクトが変更されるのは、メタデータインポートファイルの updateMask フィールドと aspectKeys フィールドにアスペクトへの参照が含まれている場合のみです。メタデータインポートファイルのこれらのフィールドの詳細については、このドキュメントのインポートアイテムの構造セクションをご覧ください。

エントリの増分同期はサポートされていません。

同期モードは、メタデータジョブの作成時に指定します。

メタデータのインポートファイル

メタデータインポートファイルは、変更するエントリとアスペクトのコレクションです。これらのエントリとアスペクトに属するすべてのフィールドに設定する値を定義します。メタデータジョブを実行する前にファイルを準備します。

同じメタデータジョブで複数のメタデータインポートファイルを指定できます。

ファイルで指定したエントリは、ジョブのスコープ内にあるリソースの既存のエントリをすべて完全に置き換えます。つまり、追加または更新する値だけでなく、ジョブ内のすべてのエントリの値を配置する必要があります。開始点として使用するプロジェクト内の現在のエントリのリストを取得するには、entries.list API メソッドを使用します。

ファイルに配置するエントリとアスペクトはすべて、ジョブのスコープで定義したエントリグループ、エントリタイプ、アスペクトタイプに属している必要があります。

次のセクションのガイドラインに従って、メタデータインポートファイルを作成します。

ファイルの構造

メタデータのインポートファイルの各行には、1 つのインポートアイテムに対応する JSON オブジェクトが含まれています。インポートアイテムは、エントリとそれに関連付けられたアスペクトの変更値を記述するオブジェクトです。

1 つのメタデータインポートファイルに複数のインポートアイテムを指定できます。ただし、メタデータジョブで同じインポートアイテムを複数回指定しないでください。各インポートアイテムは改行文字（0x0a）で区切ります。

各インポートアイテムを改行文字で区切ったメタデータインポートファイルは、次の例のようになります。

{ "entry": { "name": "entry 1", #Information about entry 1 }
{ "entry": { "name": "entry 2", #Information about entry 2 }

インポートアイテムの構造

メタデータインポートファイルの各インポートアイテムには、次のフィールドが含まれています。次の例では、読みやすくするため改行されていますが、ファイルを保存する際は、各インポート項目の後にのみ改行文字を追加してください。1 つのインポート項目のフィールド間に改行を挿入しないでください。

{
  "entry": {
    "name": "ENTRY_NAME",
    "entryType": "ENTRY_TYPE",
    "entrySource": {
      "resource": "RESOURCE",
      "system": "SYSTEM",
      "platform": "PLATFORM",
      "displayName": "DISPLAY_NAME",
      "description": "DESCRIPTION",
      "createTime": "ENTRY_CREATE_TIMESTAMP",
      "updateTime": "ENTRY_UPDATE_TIMESTAMP"
    }
    "aspects": {
      "ASPECT": {
        "data": {
          "KEY": "VALUE"
        },
        "aspectSource": {
          "createTime": "ASPECT_CREATE_TIMESTAMP"
          "updateTime": "ASPECT_UPDATE_TIMESTAMP"
        }
      },
      # Additional aspect maps
    },
    "parentEntry": "PARENT_ENTRY",
    "fullyQualifiedName": "FULLY_QUALIFIED_NAME"
  },
  "updateMask": "UPDATE_MASK_FIELDS",
  "aspectKeys": [
    "ASPECT_KEY",
    # Additional aspect keys
  ],
}

次のように置き換えます。

ENTRY_NAME: エントリの相対的なリソース名（projects/PROJECT_ID_OR_NUMBER/locations/LOCATION_ID/entryGroups/ENTRY_GROUP_ID/entries/ENTRY_ID の形式）。
ENTRY_TYPE: このエントリの作成に使用されたエントリタイプの相対的なリソース名（projects/PROJECT_ID_OR_NUMBER/locations/LOCATION_ID/entryTypes/ENTRY_TYPE_ID 形式）。
entrySource: エントリによって表されるデータリソースに関するソースシステムの情報。
- RESOURCE: ソースシステムのリソースの名前。
- SYSTEM: ソースシステムの名前。
- PLATFORM: ソースシステムを含むプラットフォーム。
- DISPLAY_NAME: ユーザーフレンドリーな表示名。
- DESCRIPTION: エントリの説明。
- ENTRY_CREATE_TIMESTAMP: ソースシステムでエントリが作成された時刻。
- ENTRY_UPDATE_TIMESTAMP: ソースシステムでエントリが更新された時刻。
aspects: エントリにアタッチされているアスペクト。aspect オブジェクトとそのデータは、アスペクトマップと呼ばれます。
- ASPECT: エントリにアタッチされているアスペクト。アスペクトがエントリにどのようにアタッチされているかに応じて、次のいずれかの形式を使用します。
  - アスペクトがエントリに直接アタッチされている場合は、そのアスペクトタイプの相対的なリソース名を PROJECT_ID_OR_NUMBER.LOCATION_ID.ASPECT_TYPE_ID の形式で指定します。
  - アスペクトがエントリのパスにアタッチされている場合は、アスペクトタイプのパスを PROJECT_ID_OR_NUMBER.LOCATION_ID.ASPECT_TYPE_ID@PATH 形式で指定します。
- KEY と VALUE: アスペクトタイプスキーマに基づくアスペクトのコンテンツ。コンテンツは UTF-8 としてエンコードする必要があります。フィールドの最大サイズは 120 KB です。
- ASPECT_CREATE_TIMESTAMP: ソースシステムでアスペクトが作成された時刻。
- ASPECT_UPDATE_TIMESTAMP: ソースシステムでアスペクトが更新された時刻。
- PARENT_ENTRY: 親エントリのリソース名。
- FULLY_QUALIFIED_NAME: 外部システムから参照できるエントリの名前。
UPDATE_MASK_FIELDS: 更新するフィールド。Entry リソースを基準とするパスで指定します。各フィールドはカンマで区切ります。

FULL エントリの同期モードでは、Dataplex には、変更可能なエントリのすべてのフィールドのパス（アスペクトを含む）が含まれます。

update_mask フィールドは、エントリを作成または再作成するときに無視されます。
ASPECT_KEY: 変更するアスペクト。次の構文をサポートします。
- ASPECT_TYPE_REFERENCE: エントリに直接アタッチされているアスペクトのアスペクトタイプと一致します。
- ASPECT_TYPE_REFERENCE@PATH: アスペクトタイプと指定されたパスに一致します。
- ASPECT_TYPE_REFERENCE@*: すべてのパスのアスペクトタイプと一致します。
ASPECT_TYPE_REFERENCE は、アスペクトタイプへの参照（PROJECT_ID_OR_NUMBER.LOCATION_ID.ASPECT_TYPE_ID 形式）に置き換えます。

このフィールドを空のままにすると、指定されたエントリ内に存在するアスペクトを正確に指定したものとして扱われます。

FULL エントリの同期モードでは、Dataplex がエントリに必要なすべてのアスペクトのキーを暗黙的に追加します。

ファイルの要件

メタデータのインポートファイルには、次の要件があります。

このファイルは、改行区切りの JSON ファイルである JSON Lines ファイルとしてフォーマットする必要があります。各インポートアイテムは改行文字（0x0a）で区切ります。
ファイルには UTF-8 文字エンコードを使用する必要があります。
サポートされているファイル拡張子は .jsonl と .json です。
ファイルサイズは 1 GiB 未満である必要があります。
ファイルで指定するエントリとアスペクトは、インポートジョブのスコープに含まれる必要があります。
ファイルは Cloud Storage バケットにアップロードする必要があります。CLOUD_STORAGE_URI/deletions/ という名前のフォルダにファイルを保存しないでください。

比較ロジック

Dataplex は、メタデータインポートファイルで指定された値とタイムスタンプを、プロジェクトに存在する値とタイムスタンプと比較して、変更するエントリとアスペクトを決定します。

大まかに説明すると、メタデータインポートファイルで提案された変更が 1 つ以上、ジョブの実行時にプロジェクトの状態を変更する場合、Dataplex は古いデータを導入することなくプロジェクトの値を更新します。提案された変更は、メタデータインポートファイルの更新マスクフィールドまたはアスペクトキーフィールドで参照する必要があります。

ジョブのスコープに含まれるエントリごとに、Dataplex は次のいずれかの処理を行います。

エントリとアタッチされたアスペクトを作成します。メタデータインポートファイルに、プロジェクトに存在しないエントリが含まれている場合、Dataplex はエントリとアタッチされたアスペクトを作成します。
エントリとアタッチされたアスペクトを削除します。エントリがプロジェクトに存在するものの、メタデータインポートファイルにエントリが含まれていない場合、Dataplex はエントリとエントリにアタッチされたアスペクトをプロジェクトから削除します。
エントリとアタッチされたアスペクトを更新します。メタデータインポートファイルとプロジェクトの両方にエントリが存在する場合、Dataplex はエントリのソースタイムスタンプとエントリに関連付けられているアスペクトソースタイムスタンプを評価して、変更する値を決定します。次に、Dataplex は次の 1 つ以上の処理を行います。
- エントリを再作成します。メタデータインポートファイル内のエントリソースの作成タイムスタンプが、プロジェクト内の対応するタイムスタンプよりも新しい場合、Dataplex は、プロジェクトにエントリを再作成します。
- エントリを更新します。メタデータインポートファイルのエントリソースの更新タイムスタンプが、プロジェクト内の対応するタイムスタンプよりも新しい場合、Dataplex はプロジェクト内のエントリを更新します。
- アスペクトを作成します。メタデータのインポートファイルのエントリオブジェクトにアスペクトが含まれていても、更新マスクフィールドに含まれていない場合、Dataplex はアスペクトを作成します。
- アスペクトを削除します。メタデータインポートファイルのエントリオブジェクトに含まれていないアスペクトが更新マスクフィールドに含まれている場合、Dataplex はアスペクトを削除します。
- アスペクトを更新します。メタデータインポートファイルのアスペクトソースの更新タイムスタンプがプロジェクト内の対応するタイムスタンプよりも新しい場合、Dataplex はプロジェクトのアスペクトを更新します。Dataplex は、アタッチされたエントリにエントリソースの更新タイムスタンプがない場合、またはメタデータインポートファイルのエントリソースのタイムスタンプがプロジェクトの対応するタイムスタンプよりも新しい場合にも、アスペクトを更新します。
  
  ただし、メタデータインポートファイルの少なくとも 1 つのアスペクトにプロジェクト内の対応するタイムスタンプよりも古いタイムスタンプがある場合、Dataplex はアタッチされたエントリを更新しません。

メタデータのインポートファイルを作成する

メタデータをインポートする前に、ジョブのメタデータインポートファイルを作成します。手順は次のとおりです。

このドキュメントで前述したガイドラインに沿って、メタデータインポートファイルを準備します。
ファイルを Cloud Storage バケットにアップロードします。

同じメタデータジョブで複数のメタデータインポートファイルを指定できます。複数のファイルを指定するには、同じ Cloud Storage バケットにファイルを保存します。ジョブを実行するときに、特定のファイルではなくバケットを指定します。Dataplex は、バケットに保存されているすべてのファイル（サブフォルダ内のファイルを含む）からメタデータを取り込みます。

メタデータのインポートジョブを実行する

メタデータのインポートファイルを作成したら、API を使用してメタデータのインポートジョブを実行します。

REST

メタデータをインポートするには、metadataJobs.create メソッドを使用します。

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

PROJECT_NUMBER: Google Cloud プロジェクト番号またはプロジェクト ID。
LOCATION_ID: Google Cloud のロケーション（us-central1 など）。
METADATA_JOB_ID: 省略可。メタデータジョブ ID。
CLOUD_STORAGE_URI: メタデータのインポートファイルを含む Cloud Storage バケットまたはフォルダの URI。ファイルの要件の詳細については、メタデータのインポートファイルをご覧ください。
ENTRY_GROUP: ジョブのスコープ内にあるエントリグループの相対的なリソース名。形式は projects/PROJECT_ID_OR_NUMBER/locations/LOCATION_ID/entryGroups/ENTRY_GROUP_ID です。エントリグループを 1 つのみ指定します。詳細については、ジョブのスコープをご覧ください。
ENTRY_TYPE: ジョブのスコープ内にあるエントリタイプの相対的なリソース名。形式は projects/PROJECT_ID_OR_NUMBER/locations/LOCATION_ID/entryTypes/ENTRY_TYPE_ID です。詳細については、ジョブのスコープをご覧ください。
ASPECT_TYPE: 省略可。ジョブのスコープ内にあるアスペクトタイプの相対的なリソース名（projects/PROJECT_ID_OR_NUMBER/locations/LOCATION_ID/aspectTypes/ASPECT_TYPE_ID 形式）。詳細については、ジョブのスコープをご覧ください。
LOG_LEVEL: 取得するログのレベル（INFO、DEBUG など）。詳細については、ジョブのログを表示してトラブルシューティングを行うをご覧ください。

HTTP メソッドと URL:

POST https://dataplex.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/metadataJobs?metadataJobId=METADATA_JOB_ID

JSON 本文のリクエスト:

{
  "type": IMPORT,
  "import_spec": {
    "source_storage_uri": gs://CLOUD_STORAGE_URI/,
    "scope": {
      "entryGroups": [
        ENTRY_GROUP
      ],
      "entry_types": [
        ENTRY_TYPE
      ],
      "aspect_types": [
        ASPECT_TYPE
      ]
    },
    "entry_sync_mode": FULL,
    "aspect_sync_mode": INCREMENTAL,
    "log_level": LOG_LEVEL
  }
}

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

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 "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://dataplex.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/metadataJobs?metadataJobId=METADATA_JOB_ID"

PowerShell（Windows）

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

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

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://dataplex.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/metadataJobs?metadataJobId=METADATA_JOB_ID" | Select-Object -Expand Content

レスポンスで長時間実行オペレーションを識別できます。

メタデータジョブの詳細情報を取得する

メタデータジョブに関する情報（ジョブのステータス、変更されたエントリの数など）を取得する手順は次のとおりです。失敗したジョブのトラブルシューティング方法の詳細については、このドキュメントのジョブのログを表示してトラブルシューティングを行うセクションをご覧ください。

REST

メタデータジョブに関する情報を取得するには、metadataJobs.get メソッドを使用します。

メタデータジョブのリストを取得する

最新のメタデータジョブのリストを取得できます。終了状態に達した古いジョブは、定期的にシステムから削除されます。

REST

最新のメタデータジョブのリストを取得するには、metadataJobs.list メソッドを使用します。

メタデータジョブをキャンセルする

実行する必要がないメタデータジョブはキャンセルできます。

REST

メタデータジョブをキャンセルするには、metadataJobs.cancel メソッドを使用します。

ジョブのログを表示してトラブルシューティングを行う

Cloud Logging を使用して、メタデータジョブのログを表示します。詳細については、Dataplex ログをモニタリングするをご覧ください。

ログレベルは、メタデータジョブを作成するときに構成します。利用可能なログレベルは次のとおりです。

INFO: ジョブ全体のレベルでログを提供します。インポートアイテムに関する集計ログが含まれますが、エラーのあるインポートアイテムは指定されません。
DEBUG: 各インポート項目の詳細なログが表示されます。デバッグレベルのロギングを使用して、特定のインポートアイテムに関する問題のトラブルシューティングを行います。たとえば、デバッグレベルのロギングを使用して、ジョブスコープにないリソース、関連するエントリタイプまたはアスペクトタイプに準拠していないエントリまたはアスペクト、メタデータインポートファイルのその他の構成ミスを特定します。

注: メタデータジョブのサイズと生成されるログの数によっては、デバッグレベルのロギングで追加費用が発生する場合があります。詳細については、Google Cloud Observability の料金をご覧ください。

検証エラー

Dataplex は、プロジェクト内の現在のメタデータに対してメタデータインポートファイルを検証します。検証の問題がある場合、ジョブのステータスは次のいずれかの状態を返す可能性があります。

FAILED: メタデータインポートファイルにエラーがある場合に発生する。Dataplex がメタデータをインポートせず、ジョブが失敗します。メタデータインポートファイルのエラーの例を以下に示します。
- ファイル内の項目を有効なインポート項目に解析できない。
- ファイル内のエントリまたはアスペクトが、ジョブのスコープに含まれないエントリグループ、エントリタイプ、またはアスペクトタイプに属している。
- ジョブで同じエントリ名が複数回指定されている。
- アスペクトマップまたはアスペクトキーで指定されたアスペクトタイプが、PROJECT_ID_OR_NUMBER.LOCATION_ID.ASPECT_TYPE_ID@OPTIONAL_PATH の形式を使用していない。
SUCCEEDED_WITH_ERRORS: メタデータインポートファイルは正常に解析できるものの、ファイル内のアイテムをインポートすると、プロジェクト内のエントリが不整合状態になる場合に発生する。Dataplex はこのようなエントリを無視しますが、残りのメタデータをファイルからインポートします。

ジョブのログを使用してエラーのトラブルシューティングを行います。

メタデータのインポート

始める前に

必要なロール

Google Cloud リソースを作成する

メタデータ ジョブのコンポーネント

ジョブのスコープ

同期モード

メタデータのインポート ファイル

ファイルの構造

インポート アイテムの構造

ファイルの要件

比較ロジック

メタデータのインポート ファイルを作成する

メタデータのインポート ジョブを実行する

REST

curl（Linux、macOS、Cloud Shell）

PowerShell（Windows）

メタデータ ジョブの詳細情報を取得する

REST

メタデータ ジョブのリストを取得する

REST

メタデータ ジョブをキャンセルする

REST

ジョブのログを表示してトラブルシューティングを行う

検証エラー

次のステップ

メタデータジョブのコンポーネント

メタデータのインポートファイル

インポートアイテムの構造

メタデータのインポートファイルを作成する

メタデータのインポートジョブを実行する

メタデータジョブの詳細情報を取得する

メタデータジョブのリストを取得する

メタデータジョブをキャンセルする