Richiedi modifiche collettive ai metadati con i workflow di governance

Questo documento descrive come inviare una richiesta di modifica dei metadati in batch per un gruppo di voci in Knowledge Catalog (in precedenza Dataplex Universal Catalog) utilizzando l'API REST.

Se non disponi dell'accesso in scrittura diretto a un gruppo di voci, puoi raggruppare fino a 250 operazioni di creazione, aggiornamento ed eliminazione per voci e link alle voci in un'unica richiesta di modifica per la revisione e l'approvazione.

Prima di iniziare

Per inviare richieste di modifica dei metadati in batch, assicurati di aver abilitato le API richieste e di disporre dei ruoli e delle autorizzazioni di Identity and Access Management (IAM) necessari per il gruppo di voci di destinazione.

Abilita l'API Dataplex, se non è già abilitata.

Ruoli richiesti per abilitare le API

Per abilitare le API, devi disporre dell'autorizzazione serviceusage.services.enable. Se hai creato il progetto, probabilmente hai già questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore Service Usage (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli.

Abilitare l'API

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per richiedere modifiche collettive dei metadati per un gruppo di voci, chiedi all'amministratore di concederti i seguenti ruoli IAM nel gruppo di voci di destinazione:

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Per saperne di più su ruoli e autorizzazioni, consulta Ruoli IAM di Knowledge Catalog.

Crea una richiesta di modifica dei metadati in blocco

Quando invii una richiesta di modifica in batch, Knowledge Catalog controlla la sintassi della richiesta e verifica che esistano i tipi di voci, i tipi di aspetti, i tipi di link di voci e le voci principali a cui viene fatto riferimento. Quando la richiesta viene approvata, Knowledge Catalog verifica se le voci e i link di voce di destinazione esistono, ad esempio restituendo un errore ALREADY_EXISTS durante la creazione di una risorsa esistente o un errore NOT_FOUND durante l'aggiornamento o l'eliminazione di una risorsa mancante.

Quando un approvatore approva una richiesta di modifica in batch, Knowledge Catalog applica automaticamente le operazioni nel seguente ordine di dipendenza:

  1. Eliminare i link di voce.
  2. Elimina le voci.
  3. Creare e aggiornare le voci.
  4. Creare e aggiornare i link alle voci.

Le richieste di modifica in batch non forniscono coerenza transazionale o rollback automatico. Una volta approvata, Knowledge Catalog valuta e applica ogni operazione singolarmente.

Tieni presente le seguenti regole di riferimento quando crei un batch:

  • Non fare riferimento a voci eliminate nello stesso batch: non puoi creare o aggiornare un link di voce che fa riferimento a una voce eliminata nello stesso batch e non puoi impostare parentEntry su una voce che stai eliminando nello stesso batch.
  • Elenca le voci principali prima di quelle secondarie: se una nuova voce fa riferimento a un'altra voce nello stesso batch come parentEntry, elenca la richiesta che crea la voce principale prima della richiesta che crea la voce secondaria. Quando crei una voce o un link di voce, il campo del gruppo di voci parent è facoltativo. Se ometti parent, Knowledge Catalog utilizza il gruppo di voci in changePayload.name. Se includi parent, deve corrispondere a changePayload.name.

Per inviare una richiesta di modifica dei metadati in batch di base, utilizza il metodo 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"

Sostituisci quanto segue:

  • PROJECT_ID: l'ID del progetto Google Cloudche contiene il gruppo di voci.
  • LOCATION: la località del gruppo di voci, ad esempio us-central1.
  • ENTRY_GROUP_ID: l'ID del gruppo di voci di destinazione.
  • ENTRY_ID: l'ID della nuova voce da creare.
  • ENTRY_TYPE_ID: l'ID del tipo di voce per la nuova voce.
  • JUSTIFICATION: il motivo per cui è necessaria la richiesta di modifica dei metadati, fino a 1024 caratteri.

Il servizio restituisce una risposta contenente il nome della risorsa della richiesta di modifica creata:

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

Verifica la richiesta di modifica in batch creata

Per esaminare la richiesta di modifica creata, utilizza il metodo 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"

Sostituisci quanto segue:

  • PROJECT_ID: l'ID del tuo progettoGoogle Cloud .
  • LOCATION: la regione in cui si trova la risorsa, ad esempio us-central1.
  • CHANGE_REQUEST_ID: l'ID univoco della richiesta.

Il servizio restituisce una risorsa ChangeRequest che contiene il payload del batch:

Esempio di risposta per una richiesta di modifica batch inviata dall'utente

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

Se una richiesta di modifica in batch viene creata automaticamente da un'esecuzione dell'agente di arricchimento, il campo author contiene l'account di servizio dell'agente di arricchimento e il campo batchChangeMetadataRequest.description.job.name contiene il nome della risorsa dell'esecuzione dell'arricchimento.

Crea una richiesta di modifica in batch di più risorse

Per proporre modifiche a più risorse in un singolo gruppo di voci, utilizza il metodo entryGroups.requestBatchMetadataChange. Ad esempio, puoi utilizzare questo metodo per creare una prima voce, creare una seconda voce con un aspetto allegato e creare un link di voce direzionale che le colleghi.

Per creare una richiesta di modifica in batch di più risorse, invia la seguente richiesta POST:

Esempio di richiesta per la creazione di una richiesta di modifica batch di più risorse

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"

Sostituisci quanto segue:

  • PROJECT_ID: l'ID del progettoGoogle Cloud che contiene il gruppo di voci.
  • LOCATION: la località del gruppo di voci, ad esempio us-central1.
  • ENTRY_GROUP_ID: l'ID del gruppo di voci di destinazione.
  • FIRST_ENTRY_ID: l'ID della prima voce personalizzata, che viene utilizzato come SOURCE nel link della voce.
  • SECOND_ENTRY_ID: l'ID della seconda voce personalizzata con un aspetto allegato, che viene utilizzato come TARGET nel link della voce.
  • ENTRY_TYPE_ID: l'ID del tipo di voce per le nuove voci.
  • ASPECT_TYPE_ID: l'ID del tipo di aspetto collegato alla seconda voce.
  • ASPECT_FIELD_NAME: il nome del campo nel template di aspetto.
  • ASPECT_FIELD_VALUE: il valore del campo dell'aspetto.
  • ENTRY_LINK_ID: l'ID del link della voce che collega le due voci.
  • ENTRY_LINK_TYPE_ID: l'ID del tipo di link della voce, ad esempio my-entry-link-type.
  • JUSTIFICATION: la spiegazione del motivo per cui sono necessarie queste modifiche ai metadati.

Il servizio restituisce una risposta contenente il nome della risorsa della richiesta di modifica creata:

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

Passaggi successivi