このページは Cloud Translation API によって翻訳されました。

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

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

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

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

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

手順の概要

metadata import API を使用してメタデータをインポートする、おおまかな手順は次のとおりです。

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

また、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.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 リソースを準備します。

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

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

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

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

ジョブのスコープ

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

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

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

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

同期モード

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

目標エントリの同期モードアスペクトの同期モード結果

エントリとそのアスペクトをインポートする

目標	エントリの同期モード	アスペクトの同期モード	結果
エントリとそのアスペクトをインポートする	`FULL`	`INCREMENTAL`	ジョブのスコープのすべてのエントリが変更されます。 Dataplex にエントリが存在しても、メタデータインポートファイルに含まれていない場合は、メタデータジョブの実行時にエントリが削除されます。アスペクトが変更されるのは、メタデータインポートファイルの `updateMask` フィールドと `aspectKeys` フィールドにアスペクトへの参照が含まれている場合のみです。インポートアイテムの構造をご覧ください。
アスペクトのみをインポートする	`NONE`	`INCREMENTAL`	アスペクトは、ジョブのスコープに含まれ、メタデータのインポートファイルに `aspectKeys` フィールドのアスペクトへの参照が含まれている場合に変更されます。インポートアイテムの構造をご覧ください。ジョブのスコープに属するエントリに属する他のメタデータは変更されません。

FULL

INCREMENTAL

ジョブのスコープのすべてのエントリが変更されます。

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

アスペクトが変更されるのは、メタデータインポートファイルの updateMask フィールドと aspectKeys フィールドにアスペクトへの参照が含まれている場合のみです。インポートアイテムの構造をご覧ください。

アスペクトのみをインポートする

NONE

INCREMENTAL

アスペクトは、ジョブのスコープに含まれ、メタデータのインポートファイルに aspectKeys フィールドのアスペクトへの参照が含まれている場合に変更されます。インポートアイテムの構造をご覧ください。

ジョブのスコープに属するエントリに属する他のメタデータは変更されません。

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

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

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

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

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

注意: Dataplex にエントリが存在しても、メタデータインポートファイルに含まれていない場合は、メタデータジョブの実行時にエントリが削除されます。メタデータのインポートファイルにデータが含まれていない場合は、ジョブのスコープに属するすべてのエントリとアスペクトが削除されます。
メタデータジョブの一部としてメタデータのインポートファイルを指定する必要があります。ジョブのスコープに含まれるエントリの既存のデータをすべて削除する場合は、空のメタデータインポートファイルを指定します。
ファイルに配置するエントリとアスペクトはすべて、ジョブのスコープで定義したエントリグループ、エントリタイプ、アスペクトタイプに属している必要があります。

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

ファイルの構造

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

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": "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: エントリとそれに関連付けられたアスペクトに関する情報。アスペクトのみのメタデータジョブでは、アスペクトマップを除くエントリのすべてのオプションフィールドが無視されます。
- 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 です。data ディクショナリは、空であっても必須です。
  - ASPECT_CREATE_TIMESTAMP: 移行元システムでアスペクトが作成された時刻。
  - ASPECT_UPDATE_TIMESTAMP: ソースシステムでアスペクトが更新された時刻。
- PARENT_ENTRY: 親エントリのリソース名。
- FULLY_QUALIFIED_NAME: 外部システムから参照できるエントリの名前。完全修飾名をご覧ください。
UPDATE_MASK_FIELDS: 更新するフィールド（Entry リソースを基準としたパス）。各フィールドはカンマで区切ります。

完全なエントリ同期ジョブでは、アスペクトを含む、変更可能なエントリのすべてのフィールドのパスが Dataplex に含まれます。エントリの作成または再作成時に、updateMask フィールドは無視されます。

アスペクトのみのメタデータジョブでは、この値を aspects に設定します。
ASPECT_KEY: 変更するアスペクト。次の構文をサポートしています。
- ASPECT_TYPE_REFERENCE: エントリに直接アタッチされているアスペクトのアスペクトタイプと一致します。
- ASPECT_TYPE_REFERENCE@PATH: アスペクトタイプと指定されたパスと一致します。
- ASPECT_TYPE_REFERENCE@*: すべてのパスのアスペクトタイプと一致します。
- *@PATH: 指定されたパス上のすべてのアスペクトタイプと一致します。
ASPECT_TYPE_REFERENCE は、アスペクトタイプへの参照に置き換えます。形式は PROJECT_ID_OR_NUMBER.LOCATION_ID.ASPECT_TYPE_ID です。

エントリ全体の同期ジョブで、このフィールドを空白のままにすると、指定されたエントリ内に存在するアスペクトを正確に指定したものとして扱われます。Dataplex は、エントリに必要なすべてのアスペクトのキーを暗黙的に追加します。

ファイルの要件

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

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

比較ロジック

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

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

比較ロジックは、実行するメタデータジョブの種類によって異なります。

エントリ全体の同期ジョブ

完全なエントリ同期メタデータジョブでは、ジョブのスコープに含まれるエントリごとに、Dataplex は次のいずれかの処理を行います。

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

アスペクトのみのジョブ

アスペクトのみのメタデータジョブでは、ジョブのスコープに含まれるアスペクトごとに、Dataplex は次のいずれかの処理を行います。

アスペクトを作成します。アスペクトがプロジェクトに存在せず、メタデータインポートファイルのアスペクトマップ、更新マスクフィールド、アスペクトキーフィールドに含まれている場合、Dataplex はアスペクトを作成します。
アスペクトを削除します。オプションのアスペクトの場合、アスペクトがプロジェクトに存在し、メタデータインポートファイルの更新マスクフィールドとアスペクトキーフィールドに含まれていても、アスペクトマップに含まれていない場合、Dataplex はアスペクトを削除します。

必須のアスペクトは削除できません。
アスペクトを更新します。プロジェクトにアスペクトが存在し、アスペクトマップ、更新マスクフィールド、メタデータインポートファイルのアスペクトキーフィールドに含まれていて、メタデータインポートファイルのアスペクトソースの更新タイムスタンプがプロジェクト内の対応するタイムスタンプよりも新しい場合、Dataplex はアスペクトを更新します。

メタデータインポートファイルにアスペクトソースの更新タイムスタンプが指定されていない場合、Dataplex はアスペクトも更新します。

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 形式）。エントリ全体の同期ジョブを作成する場合は省略可。アスペクトのみのジョブを作成する場合は必須です。詳細については、ジョブのスコープをご覧ください。
ENTRY_SYNC_MODE: エントリの同期モード（FULL や NONE など）。詳細については、同期モードをご覧ください。
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": ENTRY_SYNC_MODE,
    "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 はこのようなエントリを無視しますが、残りのメタデータをファイルからインポートします。

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

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

手順の概要

始める前に

必要なロール

リソースを作成する。

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

ジョブのスコープ

同期モード

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

ファイルの構造

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

ファイルの要件

比較ロジック

エントリ全体の同期ジョブ

アスペクトのみのジョブ

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

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

REST

curl（Linux、macOS、Cloud Shell）

PowerShell（Windows）

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

REST

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

REST

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

REST

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

検証エラー

次のステップ

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

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

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

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

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

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

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

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

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