Änderungen an Batch-Metadaten mit Governance-Workflows anfordern

In diesem Dokument wird beschrieben, wie Sie mit der REST API eine Batchanfrage zur Metadatenänderung für eine Eintragsgruppe in Knowledge Catalog (früher Dataplex Universal Catalog) senden.

Wenn Sie keinen direkten Schreibzugriff auf eine Eintragsgruppe haben, können Sie bis zu 250 Vorgänge zum Erstellen, Aktualisieren und Löschen von Einträgen und Eintragslinks in einer einzigen Änderungsanfrage zur Überprüfung und Genehmigung zusammenfassen.

Hinweis

Wenn Sie Batch-Anfragen zur Änderung von Metadaten senden möchten, müssen Sie die erforderlichen APIs aktivieren und die erforderlichen IAM-Rollen (Identity and Access Management) und ‑Berechtigungen für die Ziel-Eintragsgruppe haben.

Aktivieren Sie die Dataplex API, falls sie noch nicht aktiviert ist.

Rollen, die zum Aktivieren von APIs erforderlich sind

Zum Aktivieren von APIs benötigen Sie die Berechtigung serviceusage.services.enable. Wenn Sie das Projekt erstellt haben, haben Sie diese Berechtigung wahrscheinlich bereits über die Inhaberrolle (roles/owner). Andernfalls können Sie diese Berechtigung über die Rolle „Service Usage-Administrator“ (roles/serviceusage.serviceUsageAdmin) erhalten. Informationen zum Zuweisen von Rollen

API aktivieren

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für die Ziel-Eintragsgruppe zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Anfordern von Batch-Metadatenänderungen für eine Eintragsgruppe benötigen:

Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Sie können die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.

Weitere Informationen zu Rollen und Berechtigungen finden Sie unter IAM-Rollen für Knowledge Catalog.

Anfrage zur Batch-Metadatenänderung erstellen

Wenn Sie eine Batchänderungsanfrage senden, prüft Knowledge Catalog die Anfragesyntax und verifiziert, ob alle referenzierten Eintragstypen, Aspekttypen, Eintragslinktypen und übergeordneten Einträge vorhanden sind. Wenn die Anfrage genehmigt wird, prüft Knowledge Catalog, ob die Zieleinträge und Eintragslinks vorhanden sind. Beispielsweise wird beim Erstellen einer vorhandenen Ressource ein ALREADY_EXISTS-Fehler oder beim Aktualisieren oder Löschen einer fehlenden Ressource ein NOT_FOUND-Fehler zurückgegeben.

Wenn ein Genehmiger eine Batch-Änderungsanfrage genehmigt, wendet Knowledge Catalog die Vorgänge automatisch in der folgenden Abhängigkeitsreihenfolge an:

  1. Eintragslinks löschen
  2. Einträge löschen.
  3. Einträge erstellen und aktualisieren.
  4. Eintragslinks erstellen und aktualisieren.

Batch-Änderungsanfragen bieten keine Transaktionskonsistenz oder automatischen Rollback. Nach der Genehmigung wertet Knowledge Catalog jeden Vorgang einzeln aus und wendet ihn an.

Beachten Sie beim Erstellen eines Batches die folgenden Referenzregeln:

  • Verweisen Sie nicht auf Einträge, die im selben Batch gelöscht wurden: Sie können keinen Eintragslink erstellen oder aktualisieren, der auf einen Eintrag verweist, der im selben Batch gelöscht wird. Außerdem können Sie parentEntry nicht auf einen Eintrag festlegen, den Sie im selben Batch löschen.
  • Übergeordnete Einträge vor untergeordneten Einträgen auflisten: Wenn ein neuer Eintrag auf einen anderen Eintrag im selben Batch als parentEntry verweist, listen Sie die Anfrage, die den übergeordneten Eintrag erstellt, vor der Anfrage auf, die den untergeordneten Eintrag erstellt. Wenn Sie einen Eintrag oder Eintragslink erstellen, ist das Feld für die Eintragsgruppe parent optional. Wenn Sie parent weglassen, verwendet Knowledge Catalog die Eintragsgruppe in changePayload.name. Wenn Sie parent angeben, muss es mit changePayload.name übereinstimmen.

Verwenden Sie die Methode entryGroups.requestBatchMetadataChange, um eine einfache Batch-Metadatenänderungsanfrage zu senden:

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"

Ersetzen Sie Folgendes:

  • PROJECT_ID: die ID des Google Cloud-Projekts, das die Eintraggruppe enthält.
  • LOCATION: der Standort der Eintraggruppe, z. B. us-central1.
  • ENTRY_GROUP_ID: die ID der Ziel-Eintragsgruppe.
  • ENTRY_ID: die ID des neuen Eintrags, der erstellt werden soll.
  • ENTRY_TYPE_ID: die ID des Eintragstyps für den neuen Eintrag.
  • JUSTIFICATION: Der Grund, warum die Anfrage zur Metadatenänderung erforderlich ist,bis zu 1.024 Zeichen.

Der Dienst gibt eine Antwort mit dem Ressourcennamen der erstellten Änderungsanfrage zurück:

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

Erstellte Batch-Änderungsanfrage prüfen

Verwenden Sie die Methode changeRequests.get, um die erstellte Änderungsanfrage zu prüfen:

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"

Ersetzen Sie Folgendes:

  • PROJECT_ID: die ID IhresGoogle Cloud -Projekts.
  • LOCATION: die Region, in der sich die Ressource befindet, z. B. us-central1.
  • CHANGE_REQUEST_ID: die eindeutige ID der Anfrage.

Der Dienst gibt eine ChangeRequest-Ressource zurück, die die Batch-Nutzlast enthält:

Beispielantwort für eine vom Nutzer gesendete Batchänderungsanfrage

{
  "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"
          }
        }
      }
    ]
  }
}

Wenn die Batchänderungsanfrage automatisch durch einen Anreicherungs-Agent-Ausführung erstellt wird, enthält das Feld author das Dienstkonto des Anreicherungs-Agents und das Feld batchChangeMetadataRequest.description.job.name den Ressourcennamen der Anreicherungsausführung.

Batch-Änderungsanfrage für mehrere Ressourcen erstellen

Wenn Sie Änderungen an mehreren Ressourcen in einer einzelnen Eintraggruppe vorschlagen möchten, verwenden Sie die Methode entryGroups.requestBatchMetadataChange. Mit dieser Methode können Sie beispielsweise einen ersten Eintrag erstellen, einen zweiten Eintrag mit einem angehängten Aspekt erstellen und einen gerichteten Eintragslink erstellen, der sie verbindet.

Senden Sie die folgende POST-Anfrage, um eine Batchänderungsanfrage für mehrere Ressourcen zu erstellen:

Beispielanfrage zum Erstellen einer Batch-Änderungsanfrage für mehrere Ressourcen

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"

Ersetzen Sie Folgendes:

  • PROJECT_ID: die ID desGoogle Cloud -Projekts, das die Eintraggruppe enthält.
  • LOCATION: der Standort der Eintraggruppe, z. B. us-central1.
  • ENTRY_GROUP_ID: die ID der Ziel-Eintragsgruppe.
  • FIRST_ENTRY_ID: die ID des ersten benutzerdefinierten Eintrags, der als SOURCE im Eintragslink verwendet wird.
  • SECOND_ENTRY_ID: die ID des zweiten benutzerdefinierten Eintrags mit einem angehängten Aspekt, der als TARGET im Eintragslink verwendet wird.
  • ENTRY_TYPE_ID: die ID des Eintragstyps für die neuen Einträge.
  • ASPECT_TYPE_ID: die ID des Aspekttyps, der dem zweiten Eintrag angehängt ist.
  • ASPECT_FIELD_NAME: der Name des Felds in der Aspektvorlage.
  • ASPECT_FIELD_VALUE: der Wert für das Aspektfeld.
  • ENTRY_LINK_ID: die ID des Eintragslinks, der die beiden Einträge verbindet.
  • ENTRY_LINK_TYPE_ID: die ID des Eintragsverknüpfungstyps, z. B. my-entry-link-type.
  • JUSTIFICATION: die Erklärung, warum diese Metadatenänderungen erforderlich sind.

Der Dienst gibt eine Antwort mit dem Ressourcennamen der erstellten Änderungsanfrage zurück:

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

Nächste Schritte