透過中繼資料變更動態消息接收通知

本文說明如何設定 Dataplex Universal Catalog 中繼資料變更訊息串流，以便在 Dataplex Universal Catalog 內的中繼資料建立、更新或刪除時，透過 Pub/Sub 接收通知。

如要進一步瞭解中繼資料變更動態饋給，請參閱中繼資料變更動態饋給總覽。

事前準備

熟悉 Pub/Sub 和 Dataplex Universal Catalog API。

Enable the Dataplex Universal Catalog and Pub/Sub APIs.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.
Enable the APIs
建立 Pub/Sub 主題來接收通知。詳情請參閱「建立主題」。
安裝 gcloud。確認已設定 gcloud 的簡短別名。

設定 gcurl 的別名。這會建立包含驗證權杖的捷徑，並為 API 要求設定 JSON 內容類型：

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

設定 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

必要角色和權限

如要設定中繼資料變更動態饋給，請確認您和 Dataplex Universal Catalog 服務帳戶具備必要的 IAM 角色和權限。

使用者角色和權限

如要取得匯出中繼資料和存取中繼資料變更動態消息訊息所需的權限，請要求管理員在專案或機構中授予您下列 IAM 角色：

匯出中繼資料： Dataplex 項目群組匯出者 (roles/dataplex.entryGroupExporter)
存取中繼資料變更動態消息訊息： Pub/Sub 訂閱者 (roles/pubsub.subscriber)

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

這些預先定義的角色具備匯出中繼資料，以及存取中繼資料變更動態饋給訊息所需的權限。如要查看確切的必要權限，請展開「Required permissions」(必要權限) 部分：

所需權限

如要匯出中繼資料及存取中繼資料變更動態饋給訊息，您必須具備下列權限：

匯出中繼資料：
- 專案的 dataplex.metadataFeeds.create
- dataplex.entryGroups.export 在定義動態消息範圍的資源上 (機構、專案或項目群組)
- 專案的 resourcemanager.projects.get
- 專案的 resourcemanager.projects.list
存取中繼資料變更動態消息訊息：
- pubsub.subscriptions.consume 訂閱方案
- pubsub.topics.attachSubscription 主題

您或許還可透過自訂角色或其他預先定義的角色取得這些權限。

Dataplex Universal Catalog 服務帳戶角色和權限

為確保 Dataplex Universal Catalog 服務帳戶具備發布中繼資料變更動態消息訊息的必要權限，請要求管理員在 Pub/Sub 主題中，授予 Dataplex Universal Catalog 服務帳戶 Pub/Sub 發布者 (roles/pubsub.publisher) IAM 角色。

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和機構的存取權」。

這個預先定義的角色具備 pubsub.topics.publish 權限，可發布中繼資料變更動態消息訊息。

管理員或許還可透過自訂角色或其他預先定義的角色，將這項權限授予 Dataplex Universal Catalog 服務帳戶。

將權限授予 Dataplex Universal Catalog 服務帳戶

啟用 Dataplex API 時，系統會建立 Dataplex Universal Catalog 服務代理。您可以透過電子郵件識別服務代理：

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

其中 PROJECT_NUMBER 是您啟用 Dataplex API 的專案編號。

Dataplex Universal Catalog 服務帳戶必須能夠將訊息發布至 Pub/Sub 主題。如要授予這項權限，請在 Pub/Sub 主題上，將 Pub/Sub 發布者角色 (roles/pubsub.publisher) 授予服務帳戶：

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"

更改下列內容：

TOPIC_ID：Pub/Sub 主題的 ID，中繼資料變更動態消息訊息會發布至該主題。
PROJECT_NUMBER：服務帳戶所在的 Dataplex Universal Catalog 專案專案編號。

控制台

前往 Google Cloud 控制台的 Pub/Sub「Topics」(主題) 頁面。

前往主題
選取用於中繼資料動態消息通知的主題，然後視需要按一下「顯示資訊面板」。
在「權限」分頁中，按一下「新增主體」。
在「新增主體」欄位中，輸入 Dataplex Universal Catalog 服務帳戶：service-PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com。
在「指派角色」欄位中，選取「Pub/Sub 發布者」。
按一下 [儲存]。

建立中繼資料變更動態饋給

如要控管哪些變更會產生通知，您可以設定中繼資料變更動態饋給，監控特定資源。方法是指定範圍，例如整個機構、特定專案或特定項目群組。範圍可讓您定義要監控的哪些資源，而篩選器則可進一步精確設定 Dataplex Universal 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

接收通知訊息

設定中繼資料變更記錄後，Dataplex Universal Catalog 會在中繼資料變更時，將訊息發布至指定的 Pub/Sub 主題。如要使用這些訊息，請為該主題建立 Pub/Sub 訂閱項目。

舉例來說，您可以建立提取訂閱項目，並使用 Google Cloud CLI 查看訊息：

建立訂閱項目：
```
gcloud pubsub subscriptions create SUBSCRIPTION_ID --topic=TOPIC_ID
```
更改下列內容：
- SUBSCRIPTION_ID：要建立的訂閱 ID
- TOPIC_ID：中繼資料變更動態消息訊息發布至其中的 Pub/Sub 主題 ID。
從訂閱項目中提取訊息：
```
gcloud pubsub subscriptions pull SUBSCRIPTION_ID --auto-ack --limit=10
```
更改下列內容：
- SUBSCRIPTION_ID：要從中提取訊息的訂閱項目 ID

如要進一步瞭解如何處理 Pub/Sub 訊息，請參閱「從提取訂閱項目接收訊息」。如要瞭解訊息格式，請參閱「資料酬載」。

後續步驟

請參閱中繼資料變更動態消息總覽。
瞭解 Dataplex Universal Catalog IAM 和存取權控管。
排解中繼資料變更動態饋給問題。

透過中繼資料變更動態消息接收通知 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

必要角色和權限

使用者角色和權限

所需權限

Dataplex Universal Catalog 服務帳戶角色和權限

將權限授予 Dataplex Universal Catalog 服務帳戶

gcloud

控制台

建立中繼資料變更動態饋給

REST

查看中繼資料變更動態消息

REST

列出中繼資料變更動態饋給

REST

更新中繼資料變更動態饋給

REST

刪除中繼資料變更動態消息

REST

接收通知訊息

後續步驟

透過中繼資料變更動態消息接收通知