Gérer les demandes de modification avec des workflows de gouvernance

Ce document explique comment les demandeurs, les approbateurs et les administrateurs de workflows gèrent les demandes de gouvernance dans Knowledge Catalog (anciennement Dataplex Universal Catalog).

Avant de commencer

Pour utiliser les workflows de gouvernance, assurez-vous d'avoir activé les API requises et que les approbateurs et les administrateurs disposent des rôles et des autorisations IAM (Identity and Access Management) nécessaires.

Activez l'API Dataplex, si ce n'est pas déjà fait.

Rôles requis pour activer les API

Pour activer des API, vous devez disposer de l'autorisation serviceusage.services.enable. Si vous avez créé le projet, vous disposez probablement déjà de cette autorisation via le rôle Propriétaire (roles/owner). Sinon, vous pouvez l'obtenir via le rôle Administrateur Service Usage (roles/serviceusage.serviceUsageAdmin). Découvrez comment attribuer des rôles.

Activer l'API

Rôles requis

Pour obtenir les autorisations nécessaires pour gérer les demandes de gouvernance, demandez à votre administrateur de vous accorder les rôles IAM suivants sur votre projet :

Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Vous pouvez également obtenir les autorisations requises avec des rôles personnalisés ou d'autres rôles prédéfinis.

Pour en savoir plus sur les rôles et les autorisations, consultez Rôles IAM Knowledge Catalog.

Gérer les demandes en tant que demandeur

En tant que demandeur, vous lancez des demandes de modification, par exemple pour demander l'accès à des produits de données ou proposer des modifications de métadonnées. Après avoir envoyé une demande, vous pouvez suivre sa progression, afficher ses détails, modifier les détails des demandes en attente ou supprimer les demandes à l'état NEW avant qu'un approbateur n'agisse dessus.

Afficher les demandes créées

Pour afficher les requêtes que vous avez créées ou inspecter une requête spécifique, procédez comme suit :

Console

  1. Dans la console Google Cloud , accédez à la page Workflows de gouvernance de Knowledge Catalog.

    Accéder à "Workflows de gouvernance"

  2. Cliquez sur l'onglet Mes demandes pour afficher la liste de vos demandes passées et en attente.

REST

Pour lister les demandes que vous avez créées, utilisez la méthode 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"

Pour afficher une requête spécifique, utilisez la méthode 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"

Remplacez les éléments suivants :

  • PROJECT_ID : ID de votre projetGoogle Cloud .
  • LOCATION : région où se trouve la ressource, par exemple us-central1.
  • USER_EMAIL : votre adresse e-mail.
  • CHANGE_REQUEST_ID : identifiant unique de la requête.

Pour les requêtes de modification de métadonnées par lot, inspectez les champs de réponse pour identifier comment la requête a été créée :

  • Demande envoyée par l'utilisateur : author est l'adresse e-mail du demandeur et batchChangeMetadataRequest.description.job n'est pas défini.
  • Requête générée par l'agent d'enrichissement : author est le compte de service de l'agent d'enrichissement, et batchChangeMetadataRequest.description.job.name est défini sur l'ID d'exécution de l'enrichissement.

Modifier une demande

Vous pouvez mettre à jour une requête en attente à l'aide de l'API REST lorsqu'elle est à l'état NEW ou FAILED. La mise à jour d'une demande à l'état FAILED réinitialise son état sur NEW afin qu'un approbateur puisse l'examiner à nouveau. Les personnes autorisées à modifier une demande de modification des métadonnées dépendent de la façon dont elle a été créée :

  • Demandes envoyées par les utilisateurs : seul l'auteur d'origine peut envoyer une requête PATCH pour mettre à jour la justification ou la charge utile de la demande.
  • Requêtes générées par les agents d'enrichissement : en plus de l'auteur, les réviseurs et les approbateurs peuvent envoyer une requête PATCH pendant que la requête est à l'état NEW ou FAILED pour organiser le lot, par exemple pour modifier les valeurs d'aspect proposées ou supprimer des éléments du tableau changes. Le champ author reste le compte de service de l'agent d'enrichissement.

Pour mettre à jour une demande de modification en attente, utilisez la méthode changeRequests.patch.

Pour ne mettre à jour que la justification de la demande, envoyez la requête PATCH suivante :

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"

Pour mettre à jour la charge utile d'une requête de modification de métadonnées par lot, envoyez la requête PATCH suivante :

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"

Remplacez les éléments suivants :

  • PROJECT_ID : ID de votre projetGoogle Cloud .
  • LOCATION : région où se trouve la demande de modification, par exemple us-central1.
  • CHANGE_REQUEST_ID : identifiant unique de la demande de modification.
  • NEW_JUSTIFICATION : justification mise à jour de la demande de modification.
  • ENTRY_GROUP_ID : ID du groupe d'entrées cible.
  • EXISTING_ENTRY_ID : ID de l'entrée dans la charge utile du lot mis à jour.
  • ASPECT_PROJECT_ID : ID du projet contenant le type d'aspect.
  • ASPECT_LOCATION : emplacement du type d'aspect, par exemple us-central1 ou global.
  • ASPECT_TYPE_ID : ID du type d'aspect mis à jour.
  • ASPECT_FIELD_NAME : nom du champ d'aspect à mettre à jour.
  • UPDATED_ASPECT_FIELD_VALUE : valeur mise à jour du champ d'aspect.

Supprimer une demande

En tant que demandeur, vous ne pouvez supprimer que les demandes dont l'état est NEW. Pour supprimer une requête, procédez comme suit :

Console

  1. Dans la console Google Cloud , accédez à la page Workflows de gouvernance de Knowledge Catalog.

    Accéder à "Workflows de gouvernance"

  2. Cliquez sur l'onglet Mes demandes.

  3. Localisez la ligne contenant la requête que vous souhaitez supprimer. Si nécessaire, appliquez un filtre pour isoler l'entrée.

  4. Cliquez sur  Actions, puis sur Supprimer.

REST

Pour supprimer une requête, utilisez la méthode changeRequests.delete.

Par exemple, envoyez la requête DELETE suivante :

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"

Remplacez les éléments suivants :

  • PROJECT_ID : ID de votre projetGoogle Cloud .
  • LOCATION : région où se trouve la ressource, par exemple us-central1.
  • CHANGE_REQUEST_ID : ID unique de la requête que vous souhaitez supprimer.

Gérer les demandes en tant qu'approbateur

En tant qu'approbateur, vous évaluez les demandes en attente envoyées pour vos ressources de données et agissez en conséquence.

Notifications

Lorsque vous approuvez ou refusez une demande, Knowledge Catalog traite la décision et envoie une notification par e-mail au demandeur avec votre commentaire d'examen. Pour les requêtes par lot, Knowledge Catalog envoie la notification par e-mail une fois le processus de mise à jour terminé. Si l'auteur est un compte de service, Knowledge Catalog n'envoie pas de notification.

Points à prendre en compte concernant l'approbation

Vous ne pouvez pas approuver votre propre demande. L'approbateur doit être un compte principal différent et disposer de toutes les autorisations d'écriture et d'utilisation de types requises par les modifications proposées. Toutefois, un agent d'enrichissement peut approuver automatiquement ses propres requêtes en fonction de la confiance ou les envoyer à un approbateur pour examen. Pour les requêtes de modification de métadonnées par lot générées par un agent d'enrichissement, vous pouvez modifier la charge utile de la requête lorsqu'elle est à l'état NEW ou FAILED avant de l'approuver.

Afficher les requêtes en attente

Pour afficher les demandes en attente d'examen, procédez comme suit :

Console

  1. Dans la console Google Cloud , accédez à la page Workflows de gouvernance de Knowledge Catalog.

    Accéder à "Workflows de gouvernance"

  2. Cliquez sur l'onglet Approbations en attente pour afficher les demandes en attente d'examen. Vous pouvez filtrer les requêtes par type de ressource, type de requête ou date.

REST

Pour lister les demandes en attente d'examen dans un projet et un emplacement spécifiques, utilisez la méthode changeRequests.list.

Par exemple, envoyez la requête GET suivante :

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"

Remplacez les éléments suivants :

  • PROJECT_ID : ID de votre projetGoogle Cloud .
  • LOCATION : région où se trouve la ressource, par exemple us-central1.

Dans la liste renvoyée, le champ changeType des demandes de modification de métadonnées par lot est défini sur BATCH_CHANGE_METADATA. Les requêtes créées par une exécution d'agent d'enrichissement incluent l'ID d'exécution d'enrichissement dans batchChangeMetadataRequest.description.job.name.

Exemple de réponse pour une demande de modification par lot en attente

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

Approuver une demande

Pour approuver une demande, procédez comme suit :

Console

  1. Dans la console Google Cloud , accédez à la page Workflows de gouvernance de Knowledge Catalog.

    Accéder à "Workflows de gouvernance"

  2. Cliquez sur l'onglet Approbations en attente.

  3. Localisez la ligne contenant la demande que vous souhaitez approuver.

  4. Cliquez sur  Actions, puis sur Approuver.

REST

Pour approuver une demande, utilisez la méthode changeRequests.approve.

Par exemple, envoyez la requête POST suivante :

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"

Remplacez les éléments suivants :

  • PROJECT_ID : ID de votre projetGoogle Cloud .
  • LOCATION : région où se trouve la ressource, par exemple us-central1.
  • CHANGE_REQUEST_ID : identifiant unique de la demande de modification que vous souhaitez approuver.

Lorsque vous approuvez une demande de modification de métadonnées par lot envoyée par un utilisateur ou un agent d'enrichissement, Knowledge Catalog valide vos autorisations IAM et vos règles de charge utile de manière synchrone :

  • Si la validation réussit, la méthode renvoie ChangeRequest à l'état APPLYING pendant que Knowledge Catalog exécute le lot en arrière-plan :
  {
    "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."
      }
    }
  }
}

Pour en savoir plus sur les états des demandes, consultez Chemin de traitement des workflows de gouvernance.

Refuser une demande

Pour refuser une demande, procédez comme suit :

Console

  1. Dans la console Google Cloud , accédez à la page Workflows de gouvernance de Knowledge Catalog.

    Accéder à "Workflows de gouvernance"

  2. Cliquez sur l'onglet Approbations en attente.

  3. Localisez la ligne contenant la demande que vous souhaitez refuser.

  4. Cliquez sur  Actions, puis sur Refuser.

  5. Dans la boîte de dialogue, saisissez un motif de refus.

  6. Cliquez sur Refuser pour confirmer.

REST

Pour rejeter une demande, utilisez la méthode changeRequests.reject.

Par exemple, envoyez la requête POST suivante :

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"

Remplacez les éléments suivants :

  • PROJECT_ID : ID de votre projetGoogle Cloud .
  • LOCATION : région où se trouve la ressource, par exemple us-central1.
  • CHANGE_REQUEST_ID : identifiant unique de la demande de modification que vous souhaitez refuser.
  • REJECTION_REASON : justification du refus.

En fournissant un commentaire de refus clair, vous aidez les demandeurs à comprendre la décision et à affiner leurs justifications avant de renvoyer la demande.

Gérer les demandes en tant qu'administrateur de workflow

En tant qu'administrateur de workflow, vous supervisez les demandes de gouvernance dans l'ensemble de votre organisation, configurez les notifications par e-mail pour les approbateurs, auditez l'historique des approbations et supprimez les demandes, quel que soit leur état.

Configurer les notifications par e-mail pour les approbateurs

Vous pouvez configurer des notifications par e-mail pour les approbateurs sur un groupe d'entrées ou un glossaire d'entreprise afin de spécifier jusqu'à 10 adresses e-mail qui seront automatiquement averties chaque fois qu'une demande de modification de métadonnées unique ou par lot est créée pour cette ressource.

Pour configurer des notifications sur un groupe d'entrées, utilisez la méthode 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"

Pour configurer des notifications sur un glossaire d'entreprise, utilisez la méthode 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"

Remplacez les éléments suivants :

  • PROJECT_ID : ID de votre projetGoogle Cloud .
  • LOCATION : emplacement du groupe d'entrées, par exemple us-central1 ou global.
  • ENTRY_GROUP_ID : ID du groupe d'entrées.
  • GLOSSARY_ID : ID du glossaire d'entreprise.
  • APPROVER_EMAIL_1, APPROVER_EMAIL_2 : adresses e-mail des approbateurs potentiels à avertir lorsqu'une demande de modification est créée. Vous pouvez spécifier jusqu'à 10 adresses e-mail.

Afficher toutes les demandes et suivre l'historique des approbations

Vous pouvez afficher toutes les demandes actives et historiques dans tous les états pour surveiller les workflows et auditer l'accès aux produits de données et les modifications de métadonnées :

Console

  1. Dans la console Google Cloud , accédez à la page Workflows de gouvernance de Knowledge Catalog.

    Accéder à "Workflows de gouvernance"

  2. Cliquez sur l'onglet Journal d'approbation pour afficher les approbations, les rejets et les pistes d'audit historiques.

REST

Pour lister toutes les requêtes actives et historiques dans un projet et un emplacement spécifiques, utilisez la méthode changeRequests.list.

Par exemple, envoyez la requête GET suivante :

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

Remplacez les éléments suivants :

  • PROJECT_ID : ID de votre projetGoogle Cloud .
  • LOCATION : région où se trouve la ressource, par exemple us-central1.

Supprimer une demande, quel que soit son état

Contrairement aux demandeurs, qui ne peuvent supprimer que les requêtes à l'état NEW, les administrateurs de workflow peuvent supprimer les requêtes dans n'importe quel état à l'aide de la console Google Cloud ou de la méthode changeRequests.delete. Pour obtenir des instructions, consultez Supprimer une requête.

Étapes suivantes