Gerenciar solicitações de mudança com fluxos de trabalho de governança

Neste documento, descrevemos como solicitantes, aprovadores e administradores de fluxo de trabalho gerenciam solicitações de governança no Knowledge Catalog (antigo Dataplex Universal Catalog).

Antes de começar

Para usar os fluxos de trabalho de governança, verifique se você ativou as APIs necessárias e se os aprovadores e administradores têm os papéis e as permissões necessários do Identity and Access Management (IAM).

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 gerenciar solicitações governamentais, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:

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.

Gerenciar solicitações como solicitante

Como solicitante, você inicia solicitações de mudança, como pedir acesso a produtos de dados ou propor mudanças de metadados. Depois de enviar uma solicitação, é possível monitorar o progresso, conferir os detalhes, editar os detalhes de solicitações pendentes ou excluir solicitações no estado NEW antes que um aprovador tome uma medida.

Ver solicitações criadas

Para ver as solicitações que você criou ou inspecionar uma solicitação específica, faça o seguinte:

Console

  1. No console Google Cloud , acesse a página Fluxos de trabalho de governança do Knowledge Catalog.

    Acessar fluxos de trabalho de governança

  2. Clique na guia Minhas solicitações para ver uma lista das suas solicitações anteriores e pendentes.

REST

Para listar as solicitações que você criou, use o método 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"

Para ver uma solicitação específica, 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.
  • USER_EMAIL: seu endereço de e-mail.
  • CHANGE_REQUEST_ID: o ID exclusivo da solicitação.

Para solicitações de alteração de metadados em lote, inspecione os campos de resposta para identificar como a solicitação foi criada:

  • Solicitação enviada pelo usuário: author é o endereço de e-mail do solicitante, e batchChangeMetadataRequest.description.job não está definido.
  • Solicitação de geração do agente de enriquecimento: author é a conta de serviço do agente de enriquecimento, e batchChangeMetadataRequest.description.job.name é definido como o ID da execução de enriquecimento.

Editar uma solicitação

É possível atualizar uma solicitação pendente usando a API REST enquanto ela está no estado NEW ou FAILED. Atualizar uma solicitação no estado FAILED redefine o estado para NEW para que um aprovador possa analisá-la novamente. Quem pode editar uma solicitação de mudança de metadados depende de como ela foi criada:

  • Solicitações enviadas por usuários: somente o autor original pode enviar uma solicitação PATCH para atualizar a justificativa ou o payload da solicitação.
  • Solicitações geradas por agentes de enriquecimento: além do autor, os revisores e aprovadores podem enviar uma solicitação PATCH enquanto ela está no estado NEW ou FAILED para organizar o lote. Por exemplo, para modificar os valores de aspecto propostos ou remover itens da matriz changes. O campo author permanece como a conta de serviço do agente de enriquecimento.

Para atualizar uma solicitação de alteração pendente, use o método changeRequests.patch.

Para atualizar apenas a justificativa da solicitação, envie a seguinte solicitação 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"

Para atualizar o payload de uma solicitação de alteração de metadados em lote, envie a seguinte solicitação 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"

Substitua:

  • PROJECT_ID: o ID do seu projeto do Google Cloud .
  • LOCATION: a região em que a solicitação de alteração existe, como us-central1.
  • CHANGE_REQUEST_ID: o ID exclusivo da solicitação de alteração.
  • NEW_JUSTIFICATION: a justificativa atualizada para a solicitação de mudança.
  • ENTRY_GROUP_ID: o ID do grupo de entrada de destino.
  • EXISTING_ENTRY_ID: o ID da entrada no payload do lote atualizado.
  • ASPECT_PROJECT_ID: o ID do projeto que contém o tipo de aspecto.
  • ASPECT_LOCATION: o local do tipo de aspecto, como us-central1 ou global.
  • ASPECT_TYPE_ID: o ID do tipo de aspecto que está sendo atualizado.
  • ASPECT_FIELD_NAME: o nome do campo de aspecto a ser atualizado.
  • UPDATED_ASPECT_FIELD_VALUE: o valor atualizado do campo de aspecto.

Excluir uma solicitação

Como solicitante, você só pode excluir solicitações que estejam no estado NEW. Para excluir uma solicitação, faça o seguinte:

Console

  1. No console Google Cloud , acesse a página Fluxos de trabalho de governança do Knowledge Catalog.

    Acessar fluxos de trabalho de governança

  2. Clique na guia Minhas solicitações.

  3. Localize a linha que contém o pedido que você quer excluir. Se necessário, aplique um filtro para isolar a entrada.

  4. Clique em Ações e em Excluir.

REST

Para excluir uma solicitação, use o método changeRequests.delete.

Por exemplo, envie a seguinte solicitação 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"

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 que você quer excluir.

Gerenciar solicitações como aprovador

Como aprovador, você avalia e toma medidas em relação às solicitações pendentes enviadas para seus recursos de dados.

Notificações

Quando você aprova ou rejeita uma solicitação, o Knowledge Catalog processa a decisão e envia uma notificação por e-mail ao solicitante com seu comentário de revisão. Para solicitações em lote, o Knowledge Catalog envia a notificação por e-mail depois que o processo de atualização é concluído. Se o autor for uma conta de serviço, o Knowledge Catalog não enviará uma notificação.

Considerações sobre aprovação

Não é possível aprovar sua própria solicitação. O aprovador precisa ser um principal diferente e ter todas as permissões de gravação e uso de tipo exigidas pelas mudanças propostas. No entanto, um agente de enriquecimento pode aprovar automaticamente as próprias solicitações com base na confiança ou enviá-las a um aprovador para revisão. Para solicitações de mudança de metadados em lote geradas por um agente de enriquecimento, é possível editar o payload da solicitação enquanto ela está no estado NEW ou FAILED antes de aprová-la.

Ver solicitações pendentes

Para ver as solicitações pendentes de análise, faça o seguinte:

Console

  1. No console Google Cloud , acesse a página Fluxos de trabalho de governança do Knowledge Catalog.

    Acessar fluxos de trabalho de governança

  2. Clique na guia Aprovações pendentes para ver as solicitações que estão aguardando revisão. É possível filtrar as solicitações por tipo de recurso, tipo de solicitação ou data.

REST

Para listar as solicitações pendentes de revisão em um projeto e local específicos, use o método changeRequests.list.

Por exemplo, envie a seguinte solicitação 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"

Substitua:

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

Na lista retornada, as solicitações de alteração de metadados em lote têm o campo changeType definido como BATCH_CHANGE_METADATA. As solicitações criadas por uma execução do agente de enriquecimento incluem o ID da execução de enriquecimento em batchChangeMetadataRequest.description.job.name.

Exemplo de resposta para uma solicitação de mudança em lote pendente

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

Aprovar um pedido

Para aprovar uma solicitação, faça o seguinte:

Console

  1. No console Google Cloud , acesse a página Fluxos de trabalho de governança do Knowledge Catalog.

    Acessar fluxos de trabalho de governança

  2. Clique na guia Aprovações pendentes.

  3. Encontre a linha que contém o pedido que você quer aprovar.

  4. Clique em Ações e em Aprovar.

REST

Para aprovar uma solicitação, use o método changeRequests.approve.

Por exemplo, envie a seguinte solicitação 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"

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 de mudança que você quer aprovar.

Quando você aprova uma solicitação de mudança de metadados em lote enviada por um usuário ou um agente de enriquecimento, o Knowledge Catalog valida suas permissões do IAM e as regras de payload de forma síncrona:

  • Se a validação for bem-sucedida, o método vai retornar o ChangeRequest no estado APPLYING enquanto o Knowledge Catalog executa o lote em segundo plano:
  {
    "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."
      }
    }
  }
}

Para mais informações sobre os estados de solicitação, consulte Caminho de processamento de fluxos de trabalho de governança.

Recusar uma solicitação

Para rejeitar uma solicitação, faça o seguinte:

Console

  1. No console Google Cloud , acesse a página Fluxos de trabalho de governança do Knowledge Catalog.

    Acessar fluxos de trabalho de governança

  2. Clique na guia Aprovações pendentes.

  3. Localize a linha que contém o pedido que você quer rejeitar.

  4. Clique em Ações e em Rejeitar.

  5. Na caixa de diálogo, insira uma justificativa para a rejeição.

  6. Clique em Rejeitar para confirmar.

REST

Para rejeitar uma solicitação, use o método changeRequests.reject.

Por exemplo, envie a seguinte solicitação 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"

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 de alteração que você quer rejeitar.
  • REJECTION_REASON: a justificativa da rejeição.

Fornecer um comentário de rejeição claro ajuda os solicitantes a entender a decisão e refinar as justificativas antes de reenviar a solicitação.

Gerenciar solicitações como administrador de fluxo de trabalho

Como administrador de fluxo de trabalho, você supervisiona as solicitações de governança em toda a organização, configura notificações por e-mail para aprovadores, audita o histórico de aprovações e exclui solicitações em qualquer estado.

Configurar notificações por e-mail para aprovadores

É possível configurar notificações por e-mail para aprovadores em um grupo de entradas ou em um glossário empresarial para especificar até 10 endereços de e-mail que serão notificados automaticamente sempre que uma solicitação de alteração de metadados única ou em lote for criada para esse recurso.

Para configurar notificações em um grupo de entradas, use o método 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"

Para configurar notificações em um glossário empresarial, use o método 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"

Substitua:

  • PROJECT_ID: o ID do seu projeto do Google Cloud .
  • LOCATION: o local do grupo de entrada, como us-central1 ou global.
  • ENTRY_GROUP_ID: o ID do grupo de entradas.
  • GLOSSARY_ID: o ID do glossário empresarial.
  • APPROVER_EMAIL_1, APPROVER_EMAIL_2: os endereços de e-mail dos possíveis aprovadores que serão notificados quando uma solicitação de mudança for criada. É possível especificar até 10 endereços de e-mail.

Ver todas as solicitações e acompanhar o histórico de aprovação

É possível visualizar todas as solicitações ativas e históricas em todos os estados para monitorar fluxos de trabalho e auditar o acesso a produtos de dados e as mudanças de metadados:

Console

  1. No console Google Cloud , acesse a página Fluxos de trabalho de governança do Knowledge Catalog.

    Acessar fluxos de trabalho de governança

  2. Clique na guia Registro de aprovação para ver as aprovações e rejeições concluídas, além das trilhas de auditoria históricas.

REST

Para listar todas as solicitações ativas e históricas em um projeto e local específicos, use o método changeRequests.list.

Por exemplo, envie a seguinte solicitação GET:

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

Substitua:

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

Excluir uma solicitação em qualquer estado

Ao contrário dos solicitantes, que só podem excluir solicitações no estado NEW, os administradores de fluxo de trabalho podem excluir solicitações em qualquer estado usando o console do Google Cloud ou o método changeRequests.delete. Para instruções, consulte Excluir uma solicitação.

A seguir