メタデータ変更フィードで通知を受け取る

このドキュメントでは、Knowledge Catalog（旧称 Dataplex Universal Catalog）のメタデータ変更フィードを構成して、Knowledge Catalog 内のメタデータが作成、更新、削除されたときに Pub/Sub を介して通知を受け取る方法について説明します。

メタデータ変更フィードの詳細については、 メタデータ変更フィードの概要をご覧ください。

始める前に

Pub/Sub と Dataplex API について理解しておいてください。

  1. Dataplex API と Pub/Sub API を有効にします。

    API を有効にするために必要なロール

    API を有効にするには、serviceusage.services.enable 権限を含む Service Usage 管理者 IAM ロール（roles/serviceusage.serviceUsageAdmin）が必要です。詳しくは、ロールを付与する方法をご覧ください。

    API を有効にする

  2. 通知を受信する Pub/Sub トピックを作成します。詳細については、トピックを作成するをご覧ください。

  3. をインストールしますgcloud gcloud の短いエイリアスが設定されていることを確認します。

  4. gcurl のエイリアスを設定します。これにより、認証トークンを含むショートカットが作成され、API リクエストの JSON コンテンツ タイプが設定されます。

    alias gcurl='curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json"'

  5. DATAPLEX_API 変数を設定します。

    DATAPLEX_API="dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION"

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

    • PROJECT_ID: Dataplex API が有効になっているプロジェクトのプロジェクト ID
    • LOCATION: ジョブが実行されるロケーション（例: us-central1、europe-west3、asia-south1）

必要なロールと権限

メタデータ変更フィードを構成するには、自分と Knowledge Catalog サービス アカウントに必要な IAM ロールと権限が付与されていることを確認します。

ユーザーの役割と権限

メタデータをエクスポートしてメタデータ変更フィード メッセージにアクセスするために必要な権限を取得するには、プロジェクトまたは組織に対する次の IAM ロールを付与するよう管理者に依頼します。

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

これらの事前定義ロールには 、メタデータをエクスポートしてメタデータ変更フィード メッセージにアクセスするために必要な権限が含まれています。必要とされる正確な権限については、「必要な権限」セクションを開いてご確認ください。

必要な権限

メタデータをエクスポートしてメタデータ変更フィード メッセージにアクセスするには、次の権限が必要です。

  • メタデータをエクスポートする:
    • dataplex.metadataFeeds.create プロジェクトに対する
    • dataplex.entryGroups.export フィードのスコープを定義するリソース（組織、プロジェクト、エントリ グループ）に対する
    • resourcemanager.projects.get プロジェクトに対する
    • resourcemanager.projects.list プロジェクトに対する
  • メタデータ変更フィード メッセージにアクセスする:
    • pubsub.subscriptions.consume サブスクリプションに対する
    • pubsub.topics.attachSubscription トピックに対する

カスタムロールや他の事前定義ロールを使用して、これらの権限を取得することもできます。

Knowledge Catalog サービス アカウントのロールと権限

Knowledge Catalog サービス アカウントにメタデータ変更フィード メッセージをパブリッシュするために必要な 権限を付与するには、 管理者に依頼して、 Pub/Sub トピックに対する Pub/Sub パブリッシャー（roles/pubsub.publisher）と Pub/Sub 閲覧者（roles/pubsub.viewer） IAM ロールを Knowledge Catalog サービス アカウントに付与します。

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

この事前定義ロールには、 pubsub.topics.publish 権限と pubsub.topics.get 権限が含まれています。 これは、 メタデータ変更フィード メッセージをパブリッシュするために必要です。

管理者は、カスタムロールや他の事前定義ロールを使用して、この権 101} 限を Knowledge Catalog サービス アカウントに付与することもできます。

Knowledge Catalog サービス アカウントに権限を付与する

Knowledge Catalog のサービス エージェントは、Dataplex API を有効にすると作成されます。サービス エージェントは、次のメール ID で識別できます。

service-PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com

ここで、PROJECT_NUMBER は Dataplex API を有効にしたプロジェクトのプロジェクト番号です。

Knowledge Catalog サービス アカウントには、Pub/Sub トピックにメッセージをパブリッシュし、トピック メタデータを取得する機能が必要です。 これらの権限を付与するには、Pub/Sub トピックに対する Pub/Sub パブリッシャー ロール（roles/pubsub.publisher）と Pub/Sub 閲覧者ロール（roles/pubsub.viewer）をサービス アカウントに付与します。

gcloud

gcloud pubsub topics add-iam-policy-binding コマンドを実行します。

gcloud pubsub topics add-iam-policy-binding TOPIC_ID \
    --member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com" \
    --role="roles/pubsub.publisher"

gcloud pubsub topics add-iam-policy-binding TOPIC_ID \
    --member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com" \
    --role="roles/pubsub.viewer"

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

  • TOPIC_ID: メタデータ変更フィード メッセージがパブリッシュされる Pub/Sub トピックの ID。
  • PROJECT_NUMBER: サービス アカウントが配置されている Knowledge Catalog プロジェクトのプロジェクト番号。

コンソール

  1. コンソールで、Pub/Sub の [トピック] ページに移動します。 Google Cloud

    トピックに移動

  2. メタデータ フィード通知に使用するトピックを選択し、必要に応じて [情報パネルを表示] をクリックします。

  3. [権限] タブで、[プリンシパルを追加] をクリックします。

  4. [新しいプリンシパル] フィールドに、Knowledge Catalog サービス アカウント: service-PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com を入力します。

  5. [ロールを割り当てる] フィールドで、[Pub/Sub パブリッシャー] を選択します。

  6. [別のロールを追加] をクリックして [Pub/Sub 閲覧者] を選択します。

  7. [保存] をクリックします。

メタデータ変更フィードを作成する

変更によって通知が生成されるかどうかを制御するには、特定のリソースをモニタリングするようにメタデータ変更フィードを構成します。これを行うには、組織全体、特定のプロジェクト、特定のエントリ グループなどのスコープを指定します。 スコープを使用すると、モニタリングするリソースを定義できますが、フィルタを使用して、 Knowledge Catalog が通知を送信するタイミングをさらに絞り込むことができます。

詳細については、メタデータ変更フィードをご覧ください。

REST

メタデータ変更フィードを作成するには、 projects.locations.metadataFeeds.create メソッドを使用します。

組織スコープ

組織全体をモニタリングするメタデータ変更フィードを作成するには、次のコマンドを実行します。

gcurl -X POST -d "$(cat <<EOF
{
  "scope": {
    "organizationLevel": true
  },
  "pubsubTopic": "projects/PROJECT_ID_PUBSUB/topics/TOPIC_ID"
}
EOF
)" "https://${DATAPLEX_API}/metadataFeeds?metadataFeedId=FEED_ID"

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

  • PROJECT_ID_PUBSUB: Pub/Sub トピックが配置されているプロジェクトのプロジェクト ID（例: example-project）
  • TOPIC_ID: メタデータ変更フィード メッセージがパブリッシュされる Pub/Sub トピック ID（例: example-topic）
  • FEED_ID: 作成するメタデータ変更フィード ID（例: example-feed）

プロジェクト スコープ

特定のプロジェクトをモニタリングするメタデータ変更フィードを作成するには、次のコマンドを実行します。

gcurl -X POST -d "$(cat <<EOF
{
  "scope": {
    "projects": [
      "projects/PROJECT_ID_1",
      "projects/PROJECT_ID_2"
    ]
  },
  "pubsubTopic": "projects/PROJECT_ID_PUBSUB/topics/TOPIC_ID"
}
EOF
)" "https://${DATAPLEX_API}/metadataFeeds?metadataFeedId=FEED_ID"

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

  • PROJECT_ID_PUBSUB: Pub/Sub トピックが配置されているプロジェクトのプロジェクト ID（例: example-project）
  • TOPIC_ID: メタデータ変更フィード メッセージがパブリッシュされる Pub/Sub トピック ID（例: example-topic）
  • FEED_ID: 作成するメタデータ変更フィード ID（例: example-feed）

エントリ グループ スコープ

特定のエントリ グループをモニタリングするメタデータ変更フィードを作成するには、次のコマンドを実行します。

gcurl -X POST -d "$(cat <<EOF
{
  "scope": {
    "entryGroups": [
      "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID_1",
      "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID_2"
    ]
  },
  "pubsubTopic": "projects/PROJECT_ID_PUBSUB/topics/TOPIC_ID"
}
EOF
)" "https://${DATAPLEX_API}/metadataFeeds?metadataFeedId=FEED_ID"

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

  • PROJECT_ID_PUBSUB: Pub/Sub トピックが配置されているプロジェクトのプロジェクト ID（例: example-project）
  • LOCATION: フィードを作成するロケーション（例: us-central1）
  • ENTRY_GROUP_ID: モニタリングするエントリ グループ ID（例: example-entry-group）
  • TOPIC_ID: メタデータ変更フィード メッセージがパブリッシュされる Pub/Sub トピック ID（例: example-topic）
  • FEED_ID: 作成するメタデータ変更フィード ID（例: example-feed）

フィルタを使用する

次のコマンドを実行して、フィルタ（エントリタイプでフィルタリング）を使用してメタデータ変更フィードを作成します。

gcurl -X POST -d "$(cat <<EOF
{
  "scope": {
    "projects": [
      "projects/PROJECT_ID_1",
      "projects/PROJECT_ID_2"
    ]
  },
  "filter": {
    "entryTypes": [
      "projects/PROJECT_ID/locations/global/entryTypes/bigquery-table"
    ]
  },
  "pubsubTopic": "projects/PROJECT_ID_PUBSUB/topics/TOPIC_ID"
}
EOF
)" "https://${DATAPLEX_API}/metadataFeeds?metadataFeedId=FEED_ID"

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

  • PROJECT_ID_PUBSUB: Pub/Sub トピックが配置されているプロジェクトのプロジェクト ID（例: example-project）
  • TOPIC_ID: メタデータ変更フィード メッセージがパブリッシュされる Pub/Sub トピック ID（例: example-topic）
  • FEED_ID: 作成するメタデータ変更フィード ID（例: example-feed）

対応:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.dataplex.v1.OperationMetadata",
    "createTime": "2023-10-02T15:01:23Z",
    "target": "projects/PROJECT_ID/locations/LOCATION/metadataFeeds/FEED_ID",
    "verb": "create",
    "apiVersion": "v1"
  },
  "done": false
}

メタデータ変更フィードを表示する

メタデータ変更フィードの詳細を表示できます。

REST

メタデータ変更フィードを表示するには、 projects.locations.metadataFeeds.get メソッドを使用します。

次のコマンドを実行します。

gcurl "https://${DATAPLEX_API}/metadataFeeds/FEED_ID"

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

  • FEED_ID: 表示するメタデータ変更フィード ID（例: example-feed）

メタデータ変更フィードを一覧表示する

プロジェクトとロケーションのメタデータ変更フィードを一覧表示できます。

REST

メタデータ変更フィードを一覧表示するには、 projects.locations.metadataFeeds.list メソッドを使用します。

次のコマンドを実行します。

gcurl "https://${DATAPLEX_API}/metadataFeeds"

メタデータ変更フィードを更新する

既存のメタデータ変更フィードのスコープまたはフィルタを更新できます。

REST

メタデータ変更フィードを更新するには、 projects.locations.metadataFeeds.patch メソッドを使用します。

次のコマンドを実行して、メタデータ変更フィードを更新し、エントリタイプ フィルタを削除します。

gcurl -X PATCH -d "$(cat <<EOF
{
  "filter": {
    "entryTypes": []
  }
}
EOF
)" "https://${DATAPLEX_API}/metadataFeeds/FEED_ID?updateMask=filter"

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

  • FEED_ID: 更新するメタデータ変更フィード ID（例: example-feed）

メタデータ変更フィードを削除する

通知を受け取る必要がなくなった場合は、メタデータ変更フィードを削除できます。

メタデータ変更フィードを削除すると、フィードは新しいメタデータの変更を Pub/Sub トピックにパブリッシュしなくなります。ただし、フィードに関連付けられているトピックやサブスクリプションは削除されません。不要になった場合は、手動で削除する必要があります。

フィードまたはサブスクリプションを削除する前に、サブスクライバー アプリケーションが Pub/Sub サブスクリプション内の未処理のメッセージをすべて処理していることを確認してください。

REST

メタデータ変更フィードを削除するには、 projects.locations.metadataFeeds.delete メソッドを使用します。

次のコマンドを実行します。

gcurl -X DELETE \
"https://${DATAPLEX_API}/metadataFeeds/FEED_ID"

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

  • FEED_ID: 削除するメタデータ変更フィード ID（例: example-feed）

通知メッセージを使用する

メタデータ変更フィードを構成すると、メタデータの変更が発生したときに、Knowledge Catalog は指定された Pub/Sub トピックにメッセージをパブリッシュします。これらのメッセージを使用するには、トピックに対する Pub/Sub サブスクリプションを作成します。

たとえば、pull サブスクリプションを作成し、Google Cloud CLI を使用してメッセージを表示できます。

  1. サブスクリプションを作成します。

    gcloud pubsub subscriptions create SUBSCRIPTION_ID --topic=TOPIC_ID

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

    • SUBSCRIPTION_ID: 作成するサブスクリプション ID
    • TOPIC_ID: メタデータ変更フィード メッセージがパブリッシュされる Pub/Sub トピック ID。

  2. サブスクリプションからメッセージを pull します。

    gcloud pubsub subscriptions pull SUBSCRIPTION_ID --auto-ack --limit=10

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

    • SUBSCRIPTION_ID: メッセージを pull するサブスクリプション ID

Pub/Sub メッセージの処理の詳細については、 pull サブスクリプションからメッセージを受信するをご覧ください。メッセージ形式については、 データ ペイロードをご覧ください。

次のステップ