Demander des modifications de métadonnées par lot avec des workflows de gouvernance

Ce document explique comment envoyer une demande de modification de métadonnées par lot pour un groupe d'entrées dans Knowledge Catalog (anciennement Dataplex Universal Catalog) à l'aide de l'API REST.

Si vous ne disposez pas d'un accès en écriture direct à un groupe d'entrées, vous pouvez regrouper jusqu'à 250 opérations de création, de mise à jour et de suppression d'entrées et de liens d'entrée dans une seule demande de modification pour examen et approbation.

Avant de commencer

Pour envoyer des requêtes de modification de métadonnées par lot, assurez-vous d'avoir activé les API requises et de disposer des rôles et autorisations IAM (Identity and Access Management) nécessaires sur le groupe d'entrées cible.

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 demander des modifications de métadonnées par lot pour un groupe d'entrées, demandez à votre administrateur de vous accorder les rôles IAM suivants sur le groupe d'entrées cible :

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.

Créer une demande de modification de métadonnées par lot

Lorsque vous envoyez une demande de modification par lot, Knowledge Catalog vérifie la syntaxe de la demande et s'assure que les types d'entrées, les types d'aspects, les types de liens d'entrée et les entrées parentes référencés existent. Lorsque la requête est approuvée, Knowledge Catalog vérifie si les entrées et les liens d'entrée cibles existent. Par exemple, il renvoie une erreur ALREADY_EXISTS lors de la création d'une ressource existante ou une erreur NOT_FOUND lors de la mise à jour ou de la suppression d'une ressource manquante.

Lorsqu'un approbateur approuve une demande de modification par lot, Knowledge Catalog applique automatiquement les opérations dans l'ordre de dépendance suivant :

  1. Supprimer des liens d'entrée.
  2. Supprimer des entrées.
  3. Créer et mettre à jour des entrées.
  4. Créer et mettre à jour des liens d'entrée.

Les requêtes de modification par lot ne fournissent pas de cohérence transactionnelle ni de rollback automatique. Une fois approuvée, Knowledge Catalog évalue et applique chaque opération individuellement.

Tenez compte des règles de référence suivantes lorsque vous créez un lot :

  • Ne référencez pas les entrées supprimées dans le même lot : vous ne pouvez pas créer ni mettre à jour un lien d'entrée qui référence une entrée en cours de suppression dans le même lot, et vous ne pouvez pas définir parentEntry sur une entrée que vous supprimez dans le même lot.
  • Répertoriez les entrées parentes avant les entrées enfants : si une nouvelle entrée fait référence à une autre entrée du même lot en tant que parentEntry, répertoriez la requête qui crée l'entrée parente avant la requête qui crée l'entrée enfant. Lorsque vous créez une entrée ou un lien d'entrée, le champ de groupe d'entrées parent est facultatif. Si vous omettez parent, Knowledge Catalog utilise le groupe d'entrées dans changePayload.name. Si vous incluez parent, il doit correspondre à changePayload.name.

Pour envoyer une demande de modification de métadonnées par lot de base, utilisez la méthode 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"

Remplacez les éléments suivants :

  • PROJECT_ID : ID du projet Google Cloudcontenant le groupe d'entrées.
  • LOCATION : emplacement du groupe d'entrées, par exemple us-central1.
  • ENTRY_GROUP_ID : ID du groupe d'entrées cible.
  • ENTRY_ID : ID de la nouvelle entrée à créer.
  • ENTRY_TYPE_ID : ID du type d'entrée pour la nouvelle entrée.
  • JUSTIFICATION : raison pour laquelle la demande de modification des métadonnées est nécessaire (jusqu'à 1 024 caractères).

Le service renvoie une réponse contenant le nom de ressource de la demande de modification créée :

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

Vérifier la demande de modification par lot créée

Pour inspecter la demande de modification créée, 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.
  • CHANGE_REQUEST_ID : identifiant unique de la requête.

Le service renvoie une ressource ChangeRequest qui contient la charge utile du lot :

Exemple de réponse pour une demande de modification par lot envoyée par un utilisateur

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

Si une exécution de l'agent d'enrichissement crée automatiquement la demande de modification par lot, le champ author contient le compte de service de l'agent d'enrichissement, et le champ batchChangeMetadataRequest.description.job.name contient le nom de la ressource d'exécution de l'enrichissement.

Créer une demande de modification par lot de plusieurs ressources

Pour proposer des modifications à plusieurs ressources d'un même groupe d'entrées, utilisez la méthode entryGroups.requestBatchMetadataChange. Par exemple, vous pouvez utiliser cette méthode pour créer une première entrée, créer une deuxième entrée avec un aspect associé et créer un lien d'entrée directionnel les reliant.

Pour créer une demande de modification par lot de plusieurs ressources, envoyez la requête POST suivante :

Exemple de requête pour créer une demande de modification par lot de plusieurs ressources

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"

Remplacez les éléments suivants :

  • PROJECT_ID : ID du projetGoogle Cloud contenant le groupe d'entrées.
  • LOCATION : emplacement du groupe d'entrées, par exemple us-central1.
  • ENTRY_GROUP_ID : ID du groupe d'entrées cible.
  • FIRST_ENTRY_ID : ID de la première entrée personnalisée, qui est utilisé comme SOURCE dans le lien de l'entrée.
  • SECOND_ENTRY_ID : ID de la deuxième entrée personnalisée avec un aspect associé, qui est utilisé comme TARGET dans le lien d'entrée.
  • ENTRY_TYPE_ID : ID du type d'entrée pour les nouvelles entrées.
  • ASPECT_TYPE_ID : ID du type d'aspect associé à la deuxième entrée.
  • ASPECT_FIELD_NAME : nom du champ dans le modèle d'aspect.
  • ASPECT_FIELD_VALUE : valeur du champ d'aspect.
  • ENTRY_LINK_ID : ID du lien d'entrée connectant les deux entrées.
  • ENTRY_LINK_TYPE_ID : ID du type de lien d'entrée, par exemple my-entry-link-type.
  • JUSTIFICATION : explication de la raison pour laquelle ces modifications de métadonnées sont nécessaires.

Le service renvoie une réponse contenant le nom de ressource de la demande de modification créée :

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

Étapes suivantes