透過管理工作流程要求批次中繼資料變更

本文說明如何使用 REST API，為 Knowledge Catalog (舊稱 Dataplex Universal Catalog) 中的項目群組提交批次中繼資料變更要求。

如果您沒有項目群組的直接寫入權限，可以將最多 250 項建立、更新和刪除項目及項目連結的操作，分組為單一變更要求，以便審查及核准。

事前準備

如要提交批次中繼資料變更要求，請務必啟用必要的 API，並具備目標項目群組的必要 Identity and Access Management (IAM) 角色和權限。

啟用 Dataplex API (如果尚未啟用)。

啟用 API 所需的角色

您必須具備 serviceusage.services.enable 權限，才能啟用 API。如果您建立了專案，可能已透過擁有者角色 (roles/owner) 取得這項權限。否則，您可以透過 Service Usage 管理員角色 (roles/serviceusage.serviceUsageAdmin) 取得這項權限。瞭解如何授予角色。

啟用 API

必要的角色

如要取得要求批次變更項目群組中繼資料所需的權限，請要求管理員授予您目標項目群組的下列 IAM 角色：

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

您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

如要進一步瞭解角色和權限，請參閱「Knowledge Catalog IAM 角色」。

建立批次中繼資料變更要求

提交批次變更要求時，Knowledge Catalog 會檢查要求語法，並確認所有參照的項目類型、切面類型、項目連結類型和父項項目皆存在。要求核准後，Knowledge Catalog 會檢查目標項目和項目連結是否存在。舉例來說，建立現有資源時會傳回 ALREADY_EXISTS 錯誤，更新或刪除缺少的資源時則會傳回 NOT_FOUND 錯誤。

核准者核准批次變更要求後，Knowledge Catalog 會自動按照下列依附元件順序套用作業：

  1. 刪除項目連結。
  2. 刪除項目。
  3. 建立及更新項目。
  4. 建立及更新項目連結。

批次變更要求不提供交易一致性或自動復原功能。核准後，Knowledge Catalog 會個別評估及套用每項作業。

建構批次時，請留意下列參考規則：

  • 請勿參照在同一批次中刪除的項目：您無法建立或更新參照在同一批次中刪除的項目連結，也無法將 parentEntry 設為在同一批次中刪除的項目。
  • 在子項目之前列出父項項目：如果新項目參照同一批次中的另一個項目做為其 parentEntry，請在建立子項項目的要求之前，列出建立父項項目的要求。建立項目或項目連結時，parent 項目群組欄位為選填。如果省略 parent，Knowledge Catalog 會使用 changePayload.name 中的項目群組。如果加入 parent，則必須與 changePayload.name 相符。

如要提交基本批次中繼資料變更要求，請使用 entryGroups.requestBatchMetadataChange 方法：

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID",
    "changePayload": {
      "name": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID",
      "changes": [
        {
          "createEntryRequest": {
            "parent": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID",
            "entryId": "ENTRY_ID",
            "entry": {
              "entryType": "projects/PROJECT_ID/locations/LOCATION/entryTypes/ENTRY_TYPE_ID"
            }
          }
        }
      ]
    },
    "justification": "JUSTIFICATION"
  }' \
  "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID:requestBatchMetadataChange"

更改下列內容：

  • PROJECT_ID： Google Cloud專案的 ID，其中包含項目群組。
  • LOCATION：項目群組的位置，例如 us-central1。
  • ENTRY_GROUP_ID：目標項目群組的 ID。
  • ENTRY_ID：要建立的新項目 ID。
  • ENTRY_TYPE_ID：新項目的項目類型 ID。
  • JUSTIFICATION：需要變更中繼資料的原因，最多 1,024 個半形字元。

服務會傳回回應，其中包含已建立變更要求的資源名稱：

{
  "changeRequest": "projects/123456789012/locations/us-central1/changeRequests/eeb06bad-fc7f-49b9-9fb2-61d1ad4bad32"
}

驗證建立的批次變更要求

如要檢查建立的變更要求，請使用 changeRequests.get 方法：

curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/changeRequests/CHANGE_REQUEST_ID"

更改下列內容：

  • PROJECT_ID：Google Cloud 專案的 ID。
  • LOCATION：資源所在的區域，例如 us-central1。
  • CHANGE_REQUEST_ID：要求的專屬 ID。

服務會傳回包含批次酬載的 ChangeRequest 資源：

使用者提交批次變更要求的回應範例

{
  "name": "projects/123456789012/locations/us-central1/changeRequests/eeb06bad-fc7f-49b9-9fb2-61d1ad4bad32",
  "uid": "eeb06bad-fc7f-49b9-9fb2-61d1ad4bad32",
  "createTime": "2026-09-14T09:06:40.352156739Z",
  "updateTime": "2026-09-14T09:06:41.714939166Z",
  "justification": "Requesting creation of a new entry",
  "author": "requester@example.com",
  "state": "NEW",
  "resource": "//dataplex.googleapis.com/projects/my-project/locations/us-central1/entryGroups/my-entry-group",
  "etag": "0YSwO12PxwypRJj6kqM3CTZ9BYk4wk3yasxdiMDE3MU",
  "changeType": "BATCH_CHANGE_METADATA",
  "batchChangeMetadataRequest": {
    "name": "projects/my-project/locations/us-central1/entryGroups/my-entry-group",
    "changes": [
      {
        "createEntryRequest": {
          "parent": "projects/my-project/locations/us-central1/entryGroups/my-entry-group",
          "entryId": "new-entry-id",
          "entry": {
            "entryType": "projects/my-project/locations/us-central1/entryTypes/my-entry-type"
          }
        }
      }
    ]
  }
}

如果擴充代理程式執行作業自動建立批次變更要求，author 欄位會包含擴充代理程式服務帳戶，batchChangeMetadataRequest.description.job.name 欄位則會包含擴充執行作業資源名稱。

建立多資源批次變更要求

如要對單一項目群組中的多項資源提出變更建議，請使用 entryGroups.requestBatchMetadataChange 方法。舉例來說，您可以使用這個方法建立第一個項目、建立附加切面的第二個項目，以及建立連結兩者的定向項目連結。

如要建立多資源批次變更要求，請傳送下列 POST 要求：

建立多資源批次變更要求的要求範例

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID",
    "changePayload": {
      "name": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID",
      "changes": [
        {
          "createEntryRequest": {
            "parent": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID",
            "entryId": "FIRST_ENTRY_ID",
            "entry": {
              "entryType": "projects/PROJECT_ID/locations/LOCATION/entryTypes/ENTRY_TYPE_ID"
            }
          }
        },
        {
          "createEntryRequest": {
            "parent": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID",
            "entryId": "SECOND_ENTRY_ID",
            "entry": {
              "entryType": "projects/PROJECT_ID/locations/LOCATION/entryTypes/ENTRY_TYPE_ID",
              "aspects": {
                "PROJECT_ID.LOCATION.ASPECT_TYPE_ID": {
                  "data": {
                    "ASPECT_FIELD_NAME": "ASPECT_FIELD_VALUE"
                  }
                }
              }
            }
          }
        },
        {
          "createEntryLinkRequest": {
            "parent": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID",
            "entryLinkId": "ENTRY_LINK_ID",
            "entryLink": {
              "entryLinkType": "projects/PROJECT_ID/locations/LOCATION/entryLinkTypes/ENTRY_LINK_TYPE_ID",
              "entryReferences": [
                {
                  "name": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID/entries/FIRST_ENTRY_ID",
                  "type": "SOURCE"
                },
                {
                  "name": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID/entries/SECOND_ENTRY_ID",
                  "type": "TARGET"
                }
              ]
            }
          }
        }
      ]
    },
    "justification": "JUSTIFICATION"
  }' \
  "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID:requestBatchMetadataChange"

更改下列內容：

  • PROJECT_ID：包含項目群組的Google Cloud 專案 ID。
  • LOCATION：項目群組的位置，例如 us-central1。
  • ENTRY_GROUP_ID：目標項目群組的 ID。
  • FIRST_ENTRY_ID：第一個自訂項目的 ID，在項目連結中做為 SOURCE。
  • SECOND_ENTRY_ID：第二個自訂項目的 ID，其中附加了切面，在項目連結中做為 TARGET 使用。
  • ENTRY_TYPE_ID：新項目的項目類型 ID。
  • ASPECT_TYPE_ID：附加至第二個項目的切面類型 ID。
  • ASPECT_FIELD_NAME：切面範本中的 欄位名稱。
  • ASPECT_FIELD_VALUE：切面欄位的值。
  • ENTRY_LINK_ID：連結兩個項目的項目連結 ID。
  • ENTRY_LINK_TYPE_ID：項目連結類型的 ID，例如 my-entry-link-type。
  • JUSTIFICATION：說明為何需要變更這些中繼資料。

服務會傳回回應，其中包含所建立變更要求的資源名稱：

{
  "changeRequest": "projects/123456789012/locations/us-central1/changeRequests/eeb06bad-fc7f-49b9-9fb2-61d1ad4bad32"
}

後續步驟