Gestire le richieste di modifica con i flussi di lavoro di governance

Questo documento descrive come i richiedenti, gli approvatori e gli amministratori del workflow gestiscono le richieste di governance in Knowledge Catalog (in precedenza Dataplex Universal Catalog).

Prima di iniziare

Per utilizzare i workflow di governance, assicurati di aver abilitato le API richieste e che gli approvatori e gli amministratori dispongano dei ruoli e delle autorizzazioni di Identity and Access Management (IAM) necessari.

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 gestire le richieste del governo, chiedi all'amministratore di concederti i seguenti ruoli IAM nel progetto:

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.

Gestisci le richieste come richiedente

In qualità di richiedente, avvii le richieste di modifica, ad esempio richiedendo l'accesso ai prodotti di dati o proponendo modifiche ai metadati. Dopo aver inviato una richiesta, puoi monitorarne l'avanzamento, visualizzarne i dettagli, modificarli per le richieste in attesa o eliminare le richieste nello stato NEW prima che un approvatore intervenga.

Visualizza le richieste create

Per visualizzare le richieste che hai creato o ispezionare una richiesta specifica, segui questi passaggi:

Console

  1. Nella console Google Cloud , vai alla pagina Workflow di governance di Knowledge Catalog.

    Vai a Workflow di governance

  2. Fai clic sulla scheda Le mie richieste per visualizzare un elenco delle tue richieste passate e in attesa.

REST

Per elencare le richieste che hai creato, utilizza il metodo changeRequests.list:

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

Per visualizzare una richiesta specifica, 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.
  • USER_EMAIL: il tuo indirizzo email.
  • CHANGE_REQUEST_ID: l'ID univoco della richiesta.

Per le richieste di modifica dei metadati in batch, esamina i campi della risposta per identificare come è stata creata la richiesta:

  • Richiesta inviata dall'utente: author è l'indirizzo email del richiedente e batchChangeMetadataRequest.description.job non è impostato.
  • Richiesta generata dall'agente di arricchimento: author è il account di servizio dell'agente di arricchimento e batchChangeMetadataRequest.description.job.name è impostato sull'ID dell'esecuzione dell'arricchimento.

Modifica una richiesta

Puoi aggiornare una richiesta in attesa utilizzando l'API REST mentre si trova nello stato NEW o FAILED. L'aggiornamento di una richiesta nello stato FAILED ne reimposta lo stato su NEW, in modo che un approvatore possa esaminarla di nuovo. Chi può modificare una richiesta di modifica dei metadati dipende da come è stata creata:

  • Richieste inviate dagli utenti: solo l'autore originale può inviare una richiesta PATCH per aggiornare la motivazione o il payload della richiesta.
  • Richieste generate dagli agenti di arricchimento: oltre all'autore, i revisori e gli approvatori possono inviare una richiesta PATCH mentre la richiesta è nello stato NEW o FAILED per curare il batch, ad esempio per modificare i valori degli aspetti proposti o rimuovere elementi dall'array changes. Il campo author rimane il account di servizio dell'agente di arricchimento.

Per aggiornare una richiesta di modifica in attesa, utilizza il metodo changeRequests.patch.

Per aggiornare solo la motivazione della richiesta, invia la seguente richiesta PATCH:

curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "justification": "NEW_JUSTIFICATION"
  }' \
  "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/changeRequests/CHANGE_REQUEST_ID?updateMask=justification"

Per aggiornare il payload di una richiesta di modifica dei metadati in batch, invia la seguente richiesta PATCH:

curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "justification": "NEW_JUSTIFICATION",
    "batchChangeMetadataRequest": {
      "name": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID",
      "changes": [
        {
          "updateEntryRequest": {
            "entry": {
              "name": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID/entries/EXISTING_ENTRY_ID",
              "aspects": {
                "ASPECT_PROJECT_ID.ASPECT_LOCATION.ASPECT_TYPE_ID": {
                  "data": {
                    "ASPECT_FIELD_NAME": "UPDATED_ASPECT_FIELD_VALUE"
                  }
                }
              }
            },
            "updateMask": "aspects",
            "aspectKeys": [
              "ASPECT_PROJECT_ID.ASPECT_LOCATION.ASPECT_TYPE_ID"
            ]
          }
        }
      ]
    }
  }' \
  "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/changeRequests/CHANGE_REQUEST_ID?updateMask=batchChangeMetadataRequest.changes,justification"

Sostituisci quanto segue:

  • PROJECT_ID: l'ID del tuo progettoGoogle Cloud .
  • LOCATION: la regione in cui esiste la richiesta di modifica, ad esempio us-central1.
  • CHANGE_REQUEST_ID: l'ID univoco della richiesta di modifica.
  • NEW_JUSTIFICATION: la motivazione aggiornata per la richiesta di modifica.
  • ENTRY_GROUP_ID: l'ID del gruppo di voci di destinazione.
  • EXISTING_ENTRY_ID: l'ID della voce nel payload batch aggiornato.
  • ASPECT_PROJECT_ID: l'ID del progetto che contiene il tipo di aspetto.
  • ASPECT_LOCATION: la località del tipo di aspetto, ad esempio us-central1 o global.
  • ASPECT_TYPE_ID: l'ID del tipo di aspetto che viene aggiornato.
  • ASPECT_FIELD_NAME: il nome del campo dell'aspetto da aggiornare.
  • UPDATED_ASPECT_FIELD_VALUE: il valore aggiornato del campo dell'aspetto.

Elimina una richiesta

In qualità di richiedente, puoi eliminare solo le richieste che si trovano nello stato NEW. Per eliminare una richiesta, segui questi passaggi:

Console

  1. Nella console Google Cloud , vai alla pagina Knowledge Catalog Workflow di governance.

    Vai a Workflow di governance

  2. Fai clic sulla scheda Le mie richieste.

  3. Individua la riga contenente la richiesta che vuoi eliminare. Se necessario, applica un filtro per isolare la voce.

  4. Fai clic su Azioni e poi su Elimina.

REST

Per eliminare una richiesta, utilizza il metodo changeRequests.delete.

Ad esempio, invia la seguente richiesta DELETE:

curl -X DELETE \
  -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 che vuoi eliminare.

Gestisci le richieste come approvatore

In qualità di approvatore, valuti e intervieni sulle richieste in attesa inviate per le tue risorse di dati.

Notifiche

Quando approvi o rifiuti una richiesta, Knowledge Catalog elabora la decisione e invia una notifica via email al richiedente con il tuo commento di revisione. Per le richieste batch, Knowledge Catalog invia la notifica via email al termine del processo di aggiornamento. Se l'autore è un service account, Knowledge Catalog non invia una notifica.

Considerazioni sull'approvazione

Non puoi approvare la tua richiesta. L'approvatore deve essere un'entità diversa e disporre di tutte le autorizzazioni di scrittura e di utilizzo dei tipi richieste dalle modifiche proposte. Tuttavia, un agente di arricchimento può approvare automaticamente le proprie richieste in base all'affidabilità o inviarle a un approvatore per la revisione. Per le richieste di modifica dei metadati in batch generate da un agente di arricchimento, puoi modificare il payload della richiesta mentre questa si trova nello stato NEW o FAILED prima di approvarla.

Visualizza richieste in attesa

Per visualizzare le richieste in attesa di revisione:

Console

  1. Nella console Google Cloud , vai alla pagina Knowledge Catalog Workflow di governance.

    Vai a Workflow di governance

  2. Fai clic sulla scheda Approvazioni in attesa per visualizzare le richieste in attesa di revisione. Puoi filtrare le richieste per tipo di risorsa, tipo di richiesta o data.

REST

Per elencare le richieste in attesa di revisione all'interno di un progetto e una località specifici, utilizza il metodo changeRequests.list.

Ad esempio, invia la seguente richiesta GET:

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

Sostituisci quanto segue:

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

Nell'elenco restituito, le richieste di modifica dei metadati in batch hanno il campo changeType impostato su BATCH_CHANGE_METADATA. Le richieste create da un'esecuzione dell'agente di arricchimento includono l'ID dell'esecuzione dell'arricchimento in batchChangeMetadataRequest.description.job.name.

Esempio di risposta per una richiesta di modifica in blocco in attesa

{
"changeRequests": [
  {
    "name": "projects/my-project/locations/us-central1/changeRequests/b326114f-472b-457d-81e8-98b8ad89c608",
    "uid": "b326114f-472b-457d-81e8-98b8ad89c608",
    "justification": "Enrichment Agent Proposal: Batch Metadata Change",
    "author": "enrichment-agent@my-project.iam.gserviceaccount.com",
    "state": "NEW",
    "resource": "//dataplex.googleapis.com/projects/my-project/locations/us-central1/entryGroups/my-entry-group",
    "changeType": "BATCH_CHANGE_METADATA",
    "batchChangeMetadataRequest": {
      "name": "projects/my-project/locations/us-central1/entryGroups/my-entry-group",
      "description": {
        "job": {
          "name": "projects/123456789012/locations/us-central1/enrichmentTasks/my-enrichment-task/runs/55199e83-1a1e-4837-bb8c-c402c6bee641"
        }
      },
      "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"
            }
          }
        }
      ]
    }
  }
]
}

Approva una richiesta

Per approvare una richiesta:

Console

  1. Nella console Google Cloud , vai alla pagina Workflow di governance di Knowledge Catalog.

    Vai a Workflow di governance

  2. Fai clic sulla scheda Approvazioni in attesa.

  3. Individua la riga contenente la richiesta che vuoi approvare.

  4. Fai clic su Azioni e poi su Approva.

REST

Per approvare una richiesta, utilizza il metodo changeRequests.approve.

Ad esempio, invia la seguente richiesta POST:

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{}' \
  "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/changeRequests/CHANGE_REQUEST_ID:approve"

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 di modifica che vuoi approvare.

Quando approvi una richiesta di modifica dei metadati in batch inviata da un utente o da un agente di arricchimento, Knowledge Catalog convalida le tue autorizzazioni IAM e le regole del payload in modo sincrono:

  • Se la convalida ha esito positivo, il metodo restituisce ChangeRequest nello stato APPLYING mentre Knowledge Catalog esegue il batch in background:
  {
    "name": "projects/my-project/locations/us-central1/changeRequests/b326114f-472b-457d-81e8-98b8ad89c608",
    "uid": "b326114f-472b-457d-81e8-98b8ad89c608",
    "justification": "Proposing new entry using RequestBatchMetadataChange",
    "author": "requester@example.com",
    "state": "APPLYING",
    "resource": "//dataplex.googleapis.com/projects/my-project/locations/us-central1/entryGroups/my-entry-group",
    "approver": "approver@example.com",
    "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"
            }
          }
        }
      ]
    }
  }
  ```

* If synchronous payload validation fails (for example, with an
`INVALID_ARGUMENT` or `NOT_FOUND` error), the request immediately
transitions to the `FAILED` state instead of `APPLYING`.
* If permission validation fails with a `PERMISSION_DENIED` error, the request
remains in the `NEW` state.

After background execution finishes, poll `changeRequests.get` to check the
final state (`APPROVED` or `FAILED`). If any changes in the batch fail,
`batchChangeMetadataResponse.failedRequests` lists each failed change by its
position in `changes` (starting at `0`) along with the error details:

```json
{
  "name": "projects/my-project/locations/us-central1/changeRequests/b326114f-472b-457d-81e8-98b8ad89c608",
  "state": "APPROVED",
  "changeType": "BATCH_CHANGE_METADATA",
  "batchChangeMetadataResponse": {
    "failedRequests": {
      "1": {
        "code": 5,
        "message": "Entry not found."
      }
    }
  }
}

Per saperne di più sugli stati delle richieste, consulta Percorso di elaborazione dei workflow di governance.

Rifiuta una richiesta

Per rifiutare una richiesta:

Console

  1. Nella console Google Cloud , vai alla pagina Workflow di governance di Knowledge Catalog.

    Vai a Workflow di governance

  2. Fai clic sulla scheda Approvazioni in attesa.

  3. Individua la riga contenente la richiesta che vuoi rifiutare.

  4. Fai clic su Azioni e poi su Rifiuta.

  5. Nella finestra di dialogo, inserisci una motivazione per il rifiuto.

  6. Fai clic su Rifiuta per confermare.

REST

Per rifiutare una richiesta, utilizza il metodo changeRequests.reject.

Ad esempio, invia la seguente richiesta POST:

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "comment": "REJECTION_REASON"
  }' \
  "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/changeRequests/CHANGE_REQUEST_ID:reject"

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 di modifica che vuoi rifiutare.
  • REJECTION_REASON: la motivazione del rifiuto.

Fornire un commento di rifiuto chiaro aiuta i richiedenti a comprendere la decisione e a perfezionare le motivazioni prima di inviare nuovamente la richiesta.

Gestisci le richieste come amministratore del workflow

In qualità di amministratore del workflow, supervisioni le richieste di governance nella tua organizzazione, configuri le notifiche via email per gli approvatori, controlli la cronologia delle approvazioni ed elimini le richieste in qualsiasi stato.

Configura le notifiche via email per gli approvatori

Puoi configurare le notifiche via email per gli approvatori in un gruppo di voci o in un glossario aziendale per specificare fino a 10 indirizzi email che ricevono automaticamente una notifica ogni volta che viene creata una richiesta di modifica dei metadati singola o in batch per la risorsa.

Per configurare le notifiche su un gruppo di voci, utilizza il metodo entryGroups.patch:

curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "changeRequestConfig": {
      "approverEmails": [
        "APPROVER_EMAIL_1",
        "APPROVER_EMAIL_2"
      ]
    }
  }' \
  "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID?updateMask=changeRequestConfig"

Per configurare le notifiche su un glossario aziendale, utilizza il metodo glossaries.patch:

curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "changeRequestConfig": {
      "approverEmails": [
        "APPROVER_EMAIL_1",
        "APPROVER_EMAIL_2"
      ]
    }
  }' \
  "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/global/glossaries/GLOSSARY_ID?updateMask=changeRequestConfig"

Sostituisci quanto segue:

  • PROJECT_ID: l'ID del tuo progettoGoogle Cloud .
  • LOCATION: la località del gruppo di voci, ad esempio us-central1 o global.
  • ENTRY_GROUP_ID: l'ID del gruppo di voci.
  • GLOSSARY_ID: l'ID del glossario aziendale.
  • APPROVER_EMAIL_1, APPROVER_EMAIL_2: gli indirizzi email dei potenziali approvatori da avvisare quando viene creata una richiesta di modifica. Puoi specificare fino a 10 indirizzi email.

Visualizza tutte le richieste e monitora la cronologia delle approvazioni

Puoi visualizzare tutte le richieste attive e storiche in tutti gli stati per monitorare i flussi di lavoro e controllare l'accesso ai prodotti di dati e le modifiche ai metadati:

Console

  1. Nella console Google Cloud , vai alla pagina Knowledge Catalog Workflow di governance.

    Vai a Workflow di governance

  2. Fai clic sulla scheda Log di approvazione per visualizzare le approvazioni, i rifiuti e le tracce di audit storiche completati.

REST

Per elencare tutte le richieste attive e storiche all'interno di un progetto e di una località specifici, utilizza il metodo changeRequests.list.

Ad esempio, invia la seguente richiesta GET:

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

Sostituisci quanto segue:

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

Elimina una richiesta in qualsiasi stato

A differenza dei richiedenti, che possono eliminare solo le richieste nello stato NEW, gli amministratori del workflow possono eliminare le richieste in qualsiasi stato utilizzando la console Google Cloud o il metodo changeRequests.delete. Per istruzioni, consulta Elimina una richiesta.

Passaggi successivi