カスタム パイプラインを使用してメタデータをインポートする

このドキュメントでは、メタデータをインポートする API メソッドと独自のパイプラインを使用して、サードパーティ システムから Dataplex Universal Catalog にメタデータをインポートする方法について説明します。Dataplex Universal Catalog メタデータは、エントリとそのアスペクトで構成されます。

Google Cloud管理のオーケストレーション パイプラインを使用してメタデータを抽出してインポートする場合は、マネージド接続パイプラインを使用することをおすすめします。マネージド接続パイプラインでは、メタデータを抽出し、メタデータ インポート API メソッド（メタデータ インポート ファイル）で入力として使用できる形式で出力を生成する独自のコネクタを用意します。次に、Workflows を使用してパイプライン タスクをオーケストレートします。

実行できるメタデータのインポート ジョブの種類は次のとおりです。

• エントリの完全同期と、そのアスペクトの増分インポート。カスタム エントリでサポートされています。
• アスペクトのみの増分インポート。カスタム エントリとシステム エントリに属するアスペクトでサポートされています。カスタム エントリの場合、オプションのアスペクトと必須のアスペクトの両方を変更できます。システム エントリの場合、オプションのアスペクトを変更できます。

手順の概要

メタデータ インポート API を使用してメタデータをインポートするには、以下のおおまかな手順を行います。

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

   また、Dataplex Universal Catalog がエントリとアスペクトに比較ロジックと同期モードを適用する方法についても説明します。

2. インポートするデータを定義するメタデータのインポート ファイルを 1 つ以上作成します。

3. メタデータのインポート ファイルを Cloud Storage バケットに保存します。

4. メタデータのインポート ジョブを実行します。

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

始める前に

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

必要なロール

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

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

• エントリとそのアスペクトを完全なエントリ同期メタデータ ジョブで変更する:
  • エントリタイプまたはエントリタイプが定義されているプロジェクトに対する Dataplex エントリタイプ ユーザー（roles/dataplex.entryTypeUser）
  • アスペクト タイプまたはアスペクト タイプが定義されているプロジェクトに対する Dataplex アスペクト タイプ ユーザー（roles/dataplex.aspectTypeUser）
• アスペクトのみのメタデータ ジョブで必要なアスペクトを変更する:
  • エントリタイプまたはエントリタイプが定義されているプロジェクトに対する Dataplex エントリタイプ ユーザー（roles/dataplex.entryTypeUser）
  • アスペクト タイプまたはアスペクト タイプが定義されているプロジェクトに対する Dataplex アスペクト タイプ ユーザー（roles/dataplex.aspectTypeUser）
• アスペクトのみのメタデータ ジョブでオプションのアスペクトを変更する: アスペクト タイプまたはアスペクト タイプが定義されているプロジェクトに対する Dataplex アスペクト タイプ ユーザー（roles/dataplex.aspectTypeUser）。アスペクトのみのメタデータ ジョブでオプションのアスペクトを変更する場合、関連するエントリタイプの権限は必要ありません。
• メタデータのインポート ジョブを作成する:
  • プロジェクトまたはリソースに対する Dataplex エントリ グループ インポータ（roles/dataplex.entryGroupImporter）
  • プロジェクトまたはリソースに対する Dataplex エントリ / エントリリンク オーナー（roles/dataplex.entryOwner）
• メタデータ ジョブを表示する: プロジェクトに対する Dataplex メタデータ ジョブ閲覧者（roles/dataplex.metadataJobViewer）
• メタデータ ジョブを作成、表示、キャンセルする: プロジェクトに対する Dataplex メタデータ ジョブオーナー（roles/dataplex.metadataJobOwner）

ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

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

Google Cloud リソースを作成する

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

1. インポートするエントリのエントリ グループを作成します。
2. インポートするアスペクトのアスペクト タイプを作成します。
3. インポートするエントリのエントリタイプを作成します。
4. アスペクトのみのメタデータ ジョブを実行する場合は、インポートするアスペクトのエントリを作成します。
5. メタデータのインポート ファイルを保存する Cloud Storage バケットを作成します。

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

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

• ジョブのスコープ: ジョブに含めるエントリ グループ、エントリタイプ、アスペクト タイプ。
• 同期モード: ジョブ内のエントリとアスペクトが更新される方法。
• メタデータ インポート ファイル: ジョブ内のエントリとアスペクトに設定する値を定義するファイル。1 つのメタデータ ジョブで複数のメタデータ インポート ファイルを指定できます。ファイルを Cloud Storage に保存します。
• 比較ロジック: Dataplex Universal Catalog が、変更するエントリとアスペクトを決定する方法。

ジョブのスコープ

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

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

• エントリ グループ: ジョブに含める 1 つ以上のエントリ グループを指定します。ジョブは、これらのエントリ グループに属するエントリとアスペクトのみを変更します。エントリ グループとジョブは同じリージョンに存在する必要があります。

• エントリタイプ: ジョブに含める 1 つ以上のエントリタイプを指定します。ジョブは、これらのエントリタイプに属するエントリとアスペクトのみを変更します。エントリタイプのロケーションは、ジョブのロケーションと一致しているか、エントリタイプがグローバルであることが必要です。

• アスペクト タイプ: ジョブに含めるアスペクト タイプを 1 つ以上指定します。ジョブはそれらのアスペクト タイプに属するアスペクトのみを変更します。アスペクト タイプのロケーションは、ジョブのロケーションと一致しているか、アスペクト タイプがグローバルであることが必要です。

ジョブのスコープには、メタデータ インポート ファイルで指定したエントリタイプとアスペクト タイプをすべて含める必要があります。

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

同期モード

同期モードは、メタデータ インポート ジョブ内のエントリとアスペクトの更新方法を指定します。エントリとアスペクトの両方に同期モードを指定します。インポートするリソースに応じて、次の同期モードの組み合わせがサポートされています。

同期モードは、メタデータ ジョブを作成するときに指定します。

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

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

次の一般的なガイドラインが適用されます。

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

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

• メタデータ ジョブの一部としてメタデータ インポート ファイルを指定する必要があります。ジョブのスコープに含まれるエントリの既存のデータをすべて削除する場合は、空のメタデータ インポート ファイルを指定します。

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

メタデータ インポート ファイルを作成するには、次のセクションの詳細なガイドラインを使用します。

ファイルの構造

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

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

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

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

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

メタデータ インポート ファイル内の各インポート アイテムには、次のフィールドが含まれます（ImportItem を参照）。次の例では、読みやすくするために改行文字が使用されていますが、ファイルを保存するときは、各インポート アイテムの後にのみ改行文字を含めます。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": "