Solicitar mudanças em lote nos metadados com fluxos de trabalho de governança

Neste documento, descrevemos como enviar uma solicitação de mudança de metadados em lote para um grupo de entrada no Knowledge Catalog (antigo Dataplex Universal Catalog) usando a API REST.

Se você não tiver acesso de gravação direta a um grupo de entradas, poderá agrupar até 250 operações de criação, atualização e exclusão de entradas e links de entrada em uma única solicitação de alteração para análise e aprovação.

Antes de começar

Para enviar solicitações de alteração de metadados em lote, verifique se você ativou as APIs necessárias e se tem os papéis e as permissões do Identity and Access Management (IAM) necessários no grupo de entrada de destino.

Ative a API Dataplex, se ainda não tiver feito isso.

Funções necessárias para ativar APIs

Para ativar APIs, você precisa da permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão pelo papel de proprietário (roles/owner). Caso contrário, é possível conseguir essa permissão pelo papel de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

Ativar a API

Funções exigidas

Para receber as permissões necessárias para solicitar mudanças de metadados em lote para um grupo de entradas, peça ao administrador para conceder a você os seguintes papéis do IAM no grupo de entradas de destino:

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Para mais informações sobre papéis e permissões, consulte Papéis do IAM do Knowledge Catalog.

Criar uma solicitação de mudança de metadados em lote

Quando você envia uma solicitação de mudança em lote, o Knowledge Catalog verifica a sintaxe da solicitação e se os tipos de entrada, de aspecto, de link de entrada e as entradas pai referenciados existem. Quando a solicitação é aprovada, o Knowledge Catalog verifica se as entradas de destino e os links de entrada existem. Por exemplo, ele retorna um erro ALREADY_EXISTS ao criar um recurso existente ou um erro NOT_FOUND ao atualizar ou excluir um recurso ausente.

Quando um aprovador aprova uma solicitação de alteração em lote, o Knowledge Catalog aplica automaticamente as operações na seguinte ordem de dependência:

  1. Excluir links de entrada.
  2. Excluir entradas.
  3. Criar e atualizar entradas.
  4. Criar e atualizar links de entrada.

As solicitações de alteração em lote não oferecem consistência transacional nem reversão automática. Quando aprovado, o Knowledge Catalog avalia e aplica cada operação individualmente.

Lembre-se das seguintes regras de referência ao criar um lote:

  • Não faça referência a entradas excluídas no mesmo lote: não é possível criar ou atualizar um link de entrada que faça referência a uma entrada que está sendo excluída no mesmo lote, e não é possível definir parentEntry como uma entrada que você está excluindo no mesmo lote.
  • Liste as entradas pai antes das entradas filhas: se uma nova entrada fizer referência a outra entrada no mesmo lote que o parentEntry, liste a solicitação que cria a entrada pai antes da solicitação que cria a entrada filha. Ao criar uma entrada ou um link de entrada, o campo do grupo de entradas parent é opcional. Se você omitir parent, o Knowledge Catalog vai usar o grupo de entrada em changePayload.name. Se você incluir parent, ele precisará corresponder a changePayload.name.

Para enviar uma solicitação básica de mudança de metadados em lote, use o método 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"

Substitua:

  • PROJECT_ID: o ID do projeto do Google Cloud que contém o grupo de entrada.
  • LOCATION: o local do grupo de entrada, como us-central1.
  • ENTRY_GROUP_ID: o ID do grupo de entrada de destino.
  • ENTRY_ID: o ID da nova entrada a ser criada.
  • ENTRY_TYPE_ID: o ID do tipo de entrada da nova entrada.
  • JUSTIFICATION: o motivo pelo qual a solicitação de mudança de metadados é necessária, com até 1.024 caracteres.

O serviço retorna uma resposta que contém o nome do recurso da solicitação de alteração criada:

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

Verificar a solicitação de alteração em lote criada

Para inspecionar a solicitação de mudança criada, use o método 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"

Substitua:

  • PROJECT_ID: o ID do seu projeto do Google Cloud .
  • LOCATION: a região em que o recurso existe, como us-central1.
  • CHANGE_REQUEST_ID: o ID exclusivo da solicitação.

O serviço retorna um recurso ChangeRequest que contém o payload em lote:

Exemplo de resposta para uma solicitação de mudança em lote enviada pelo usuário

{
  "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 uma execução do agente de enriquecimento criar a solicitação de alteração em lote automaticamente, o campo author vai conter a conta de serviço do agente de enriquecimento, e o campo batchChangeMetadataRequest.description.job.name vai conter o nome do recurso da execução de enriquecimento.

Criar uma solicitação de alteração em lote de vários recursos

Para propor mudanças em vários recursos em um único grupo de entrada, use o método entryGroups.requestBatchMetadataChange. Por exemplo, é possível usar esse método para criar uma primeira entrada, criar uma segunda entrada com um aspecto anexado e criar um link de entrada direcional que as conecte.

Para criar uma solicitação de mudança em lote de vários recursos, envie a seguinte solicitação POST:

Exemplo de solicitação para criar uma solicitação de mudança em lote de vários recursos

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"

Substitua:

  • PROJECT_ID: o ID do projeto doGoogle Cloud que contém o grupo de entrada.
  • LOCATION: o local do grupo de entrada, como us-central1.
  • ENTRY_GROUP_ID: o ID do grupo de entrada de destino.
  • FIRST_ENTRY_ID: o ID da primeira entrada personalizada, que é usado como SOURCE no link da entrada.
  • SECOND_ENTRY_ID: o ID da segunda entrada personalizada com um aspecto anexado, que é usado como TARGET no link de entrada.
  • ENTRY_TYPE_ID: o ID do tipo de entrada para as novas entradas.
  • ASPECT_TYPE_ID: o ID do tipo de aspecto anexado à segunda entrada.
  • ASPECT_FIELD_NAME: o nome do campo no modelo de aspecto.
  • ASPECT_FIELD_VALUE: o valor do campo de aspecto.
  • ENTRY_LINK_ID: o ID do link de entrada que conecta as duas entradas.
  • ENTRY_LINK_TYPE_ID: o ID do tipo de link de entrada, como my-entry-link-type.
  • JUSTIFICATION: a explicação do motivo pelo qual essas mudanças de metadados são necessárias.

O serviço retorna uma resposta que contém o nome do recurso da solicitação de alteração criada:

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

A seguir