Administra las solicitudes de cambio con flujos de trabajo de gobernanza

En este documento, se describe cómo los solicitantes, los aprobadores y los administradores de flujos de trabajo administran las solicitudes de administración en Knowledge Catalog (anteriormente, Dataplex Universal Catalog).

Antes de comenzar

Para usar los flujos de trabajo de administración, asegúrate de haber habilitado las APIs necesarias y de que los aprobadores y administradores tengan los roles y permisos de Identity and Access Management (IAM) necesarios.

Habilita la API de Dataplex si aún no está habilitada.

Roles necesarios para habilitar las APIs

Para habilitar las APIs, necesitas el permiso serviceusage.services.enable. Si creaste el proyecto, es probable que ya tengas este permiso a través del rol de propietario (roles/owner). De lo contrario, puedes obtenerlo a través del rol de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin). Obtén más información para otorgar roles.

Habilitar la API

Roles obligatorios

Para obtener los permisos que necesitas para administrar las solicitudes gubernamentales, pídele a tu administrador que te otorgue los siguientes roles de IAM en tu proyecto:

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

Para obtener más información sobre los roles y los permisos, consulta Roles de IAM de Knowledge Catalog.

Administra solicitudes como solicitante

Como solicitante, inicias solicitudes de cambio, como solicitar acceso a productos de datos o proponer cambios en los metadatos. Después de enviar una solicitud, puedes supervisar su progreso, ver los detalles de la solicitud, editar los detalles de las solicitudes pendientes o borrar las solicitudes en el estado NEW antes de que un responsable de aprobación actúe en ellas.

Ver solicitudes creadas

Para ver las solicitudes que creaste o inspeccionar una solicitud específica, haz lo siguiente:

Console

  1. En la consola de Google Cloud , ve a la página Flujos de trabajo de administración de Knowledge Catalog.

    Ir a Flujos de trabajo de administración

  2. Haz clic en la pestaña Mis solicitudes para ver una lista de tus solicitudes anteriores y pendientes.

REST

Para enumerar las solicitudes que creaste, usa el 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 una solicitud específica, usa el 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"

Reemplaza lo siguiente:

  • PROJECT_ID: Es el ID de tu proyecto de Google Cloud .
  • LOCATION: Es la región en la que existe el recurso, como us-central1.
  • USER_EMAIL: el dirección de correo electrónico
  • CHANGE_REQUEST_ID: Es el ID único de la solicitud.

Para las solicitudes de cambio de metadatos por lotes, inspecciona los campos de respuesta para identificar cómo se creó la solicitud:

  • Solicitud enviada por el usuario: author es la dirección de correo electrónico del solicitante y batchChangeMetadataRequest.description.job no está configurada.
  • Solicitud generada por el agente de enriquecimiento: author es la cuenta de servicio del agente de enriquecimiento y batchChangeMetadataRequest.description.job.name se establece en el ID de ejecución del enriquecimiento.

Cómo editar una solicitud

Puedes actualizar una solicitud pendiente con la API de REST mientras se encuentra en el estado NEW o FAILED. Si actualizas una solicitud en el estado FAILED, se restablece su estado a NEW para que un responsable de aprobación pueda volver a revisarla. Quién puede editar una solicitud de cambio de metadatos depende de cómo se creó:

  • Solicitudes enviadas por los usuarios: Solo el autor original puede enviar una solicitud PATCH para actualizar la justificación o la carga útil de la solicitud.
  • Solicitudes generadas por agentes de enriquecimiento: Además del autor, los revisores y aprobadores pueden enviar una solicitud PATCH mientras la solicitud está en el estado NEW o FAILED para seleccionar el lote, por ejemplo, para modificar los valores de aspecto propuestos o quitar elementos del array changes. El campo author sigue siendo la cuenta de servicio del agente de enriquecimiento.

Para actualizar una solicitud de cambio pendiente, usa el método changeRequests.patch.

Para actualizar solo la justificación de la solicitud, envía la siguiente solicitud 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 actualizar la carga útil de una solicitud de cambio de metadatos por lotes, envía la siguiente solicitud 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"

Reemplaza lo siguiente:

  • PROJECT_ID: Es el ID de tu proyecto de Google Cloud .
  • LOCATION: Es la región en la que existe la solicitud de cambio, como us-central1.
  • CHANGE_REQUEST_ID: Es el ID único de la solicitud de cambio.
  • NEW_JUSTIFICATION: Es la justificación actualizada para la solicitud de cambio.
  • ENTRY_GROUP_ID: Es el ID del grupo de entradas de destino.
  • EXISTING_ENTRY_ID: Es el ID de la entrada en la carga útil del lote actualizado.
  • ASPECT_PROJECT_ID: Es el ID del proyecto que contiene el tipo de aspecto.
  • ASPECT_LOCATION: Es la ubicación del tipo de aspecto, como us-central1 o global.
  • ASPECT_TYPE_ID: Es el ID del tipo de aspecto que se actualiza.
  • ASPECT_FIELD_NAME: Es el nombre del campo de aspecto que se actualizará.
  • UPDATED_ASPECT_FIELD_VALUE: el valor actualizado del campo de aspecto.

Borra una solicitud

Como solicitante, solo puedes borrar las solicitudes que se encuentren en el estado NEW. Para borrar una solicitud, haz lo siguiente:

Console

  1. En la consola de Google Cloud , ve a la página Flujos de trabajo de administración de Knowledge Catalog.

    Ir a Flujos de trabajo de administración

  2. Haz clic en la pestaña Mis solicitudes.

  3. Busca la fila que contiene la solicitud que quieres borrar. Si es necesario, aplica un filtro para aislar la entrada.

  4. Haz clic en Acciones y, luego, en Borrar.

REST

Para borrar una solicitud, usa el método changeRequests.delete.

Por ejemplo, envía la siguiente solicitud 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"

Reemplaza lo siguiente:

  • PROJECT_ID: Es el ID de tu proyecto de Google Cloud .
  • LOCATION: Es la región en la que existe el recurso, como us-central1.
  • CHANGE_REQUEST_ID: el ID único de la solicitud que deseas borrar.

Administra solicitudes como responsable de aprobación

Como aprobador, evalúas las solicitudes pendientes enviadas para tus recursos de datos y tomas medidas al respecto.

Notificaciones

Cuando apruebas o rechazas una solicitud, Knowledge Catalog procesa la decisión y envía una notificación por correo electrónico al solicitante con tu comentario de revisión. En el caso de las solicitudes por lotes, Knowledge Catalog envía la notificación por correo electrónico después de que se completa el proceso de actualización. Si el autor es una cuenta de servicio, Knowledge Catalog no envía una notificación.

Consideraciones sobre la aprobación

No puedes aprobar tu propia solicitud. El aprobador debe ser un principal diferente y tener todos los permisos de escritura y uso de tipos que requieren los cambios propuestos. Sin embargo, un agente de enriquecimiento puede aprobar automáticamente sus propias solicitudes en función de la confianza o enviarlas a un responsable de aprobación para que las revise. Para las solicitudes de cambio de metadatos por lotes generadas por un agente de enriquecimiento, puedes editar la carga útil de la solicitud mientras la solicitud está en el estado NEW o FAILED antes de aprobarla.

Ver solicitudes pendientes

Para ver las solicitudes pendientes de revisión, haz lo siguiente:

Console

  1. En la consola de Google Cloud , ve a la página Flujos de trabajo de administración de Knowledge Catalog.

    Ir a Flujos de trabajo de administración

  2. Haz clic en la pestaña Aprobaciones pendientes para ver las solicitudes que están pendientes de revisión. Puedes filtrar las solicitudes por tipo de recurso, tipo de solicitud o fecha.

REST

Para enumerar las solicitudes pendientes de revisión en un proyecto y una ubicación específicos, usa el método changeRequests.list.

Por ejemplo, envía la siguiente solicitud 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"

Reemplaza lo siguiente:

  • PROJECT_ID: Es el ID de tu proyecto de Google Cloud .
  • LOCATION: Es la región en la que existe el recurso, como us-central1.

En la lista que se muestra, las solicitudes de cambio de metadatos por lotes tienen el campo changeType establecido en BATCH_CHANGE_METADATA. Las solicitudes creadas por una ejecución de agente de enriquecimiento incluyen el ID de ejecución de enriquecimiento en batchChangeMetadataRequest.description.job.name.

Respuesta de ejemplo para una solicitud de cambio por lotes pendiente

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

Cómo aprobar una solicitud

Para aprobar una solicitud, haz lo siguiente:

Console

  1. En la consola de Google Cloud , ve a la página Flujos de trabajo de administración de Knowledge Catalog.

    Ir a Flujos de trabajo de administración

  2. Haz clic en la pestaña Aprobaciones pendientes.

  3. Busca la fila que contiene la solicitud que quieres aprobar.

  4. Haz clic en Acciones y, luego, en Aprobar.

REST

Para aprobar una solicitud, usa el método changeRequests.approve.

Por ejemplo, envía la siguiente solicitud 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"

Reemplaza lo siguiente:

  • PROJECT_ID: Es el ID de tu proyecto de Google Cloud .
  • LOCATION: Es la región en la que existe el recurso, como us-central1.
  • CHANGE_REQUEST_ID: Es el ID único de la solicitud de cambio que deseas aprobar.

Cuando apruebas una solicitud de cambio de metadatos por lotes enviada por un usuario o un agente de enriquecimiento, Knowledge Catalog valida tus permisos de IAM y las reglas de carga útil de forma síncrona:

  • Si la validación se realiza de forma correcta, el método devuelve el ChangeRequest en el estado APPLYING mientras Knowledge Catalog ejecuta el lote en 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 obtener más información sobre los estados de las solicitudes, consulta Ruta de procesamiento de los flujos de trabajo de administración.

Cómo rechazar una solicitud

Para rechazar una solicitud, haz lo siguiente:

Console

  1. En la consola de Google Cloud , ve a la página Flujos de trabajo de administración de Knowledge Catalog.

    Ir a Flujos de trabajo de administración

  2. Haz clic en la pestaña Aprobaciones pendientes.

  3. Busca la fila que contiene la solicitud que deseas rechazar.

  4. Haz clic en Acciones y, luego, en Rechazar.

  5. En el cuadro de diálogo, ingresa una justificación para el rechazo.

  6. Haz clic en Rechazar para confirmar.

REST

Para rechazar una solicitud, usa el método changeRequests.reject.

Por ejemplo, envía la siguiente solicitud 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"

Reemplaza lo siguiente:

  • PROJECT_ID: Es el ID de tu proyecto de Google Cloud .
  • LOCATION: Es la región en la que existe el recurso, como us-central1.
  • CHANGE_REQUEST_ID: Es el ID único de la solicitud de cambio que quieres rechazar.
  • REJECTION_REASON: Es la justificación del rechazo.

Proporcionar un comentario de rechazo claro ayuda a los solicitantes a comprender la decisión y definir mejor sus justificaciones antes de volver a enviar la solicitud.

Administra solicitudes como administrador de flujos de trabajo

Como administrador de flujos de trabajo, supervisas las solicitudes de administración en toda tu organización, configuras las notificaciones por correo electrónico para los aprobadores, auditas el historial de aprobaciones y borras las solicitudes en cualquier estado.

Configura las notificaciones por correo electrónico para los responsables de aprobación

Puedes configurar las notificaciones por correo electrónico para los responsables de aprobación en un grupo de entradas o un glosario empresarial para especificar hasta 10 direcciones de correo electrónico que se notifiquen automáticamente cada vez que se cree una solicitud de cambio de metadatos única o por lotes para ese recurso.

Para configurar las notificaciones en un grupo de entradas, usa el 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 las notificaciones en un glosario empresarial, usa el 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"

Reemplaza lo siguiente:

  • PROJECT_ID: Es el ID de tu proyecto de Google Cloud .
  • LOCATION: Es la ubicación del grupo de entradas, como us-central1 o global.
  • ENTRY_GROUP_ID: Es el ID del grupo de entradas.
  • GLOSSARY_ID: Es el ID del glosario empresarial.
  • APPROVER_EMAIL_1, APPROVER_EMAIL_2: Son las direcciones de correo electrónico de los aprobadores potenciales a los que se les notificará cuando se cree una solicitud de cambio. Puedes especificar hasta 10 direcciones de correo electrónico.

Ver todas las solicitudes y hacer un seguimiento del historial de aprobaciones

Puedes ver todas las solicitudes activas y del historial en todos los estados para supervisar los flujos de trabajo y auditar el acceso a los productos de datos y los cambios en los metadatos:

Console

  1. En la consola de Google Cloud , ve a la página Flujos de trabajo de administración de Knowledge Catalog.

    Ir a Flujos de trabajo de administración

  2. Haz clic en la pestaña Registro de aprobaciones para ver las aprobaciones, los rechazos y los registros de auditoría históricos completados.

REST

Para enumerar todas las solicitudes activas y del historial dentro de un proyecto y una ubicación específicos, usa el método changeRequests.list.

Por ejemplo, envía la siguiente solicitud GET:

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

Reemplaza lo siguiente:

  • PROJECT_ID: Es el ID de tu proyecto de Google Cloud .
  • LOCATION: Es la región en la que existe el recurso, como us-central1.

Borra una solicitud en cualquier estado

A diferencia de los solicitantes, que solo pueden borrar solicitudes en el estado NEW, los administradores de flujo de trabajo pueden borrar solicitudes en cualquier estado con la consola de Google Cloud o el método changeRequests.delete. Para obtener instrucciones, consulta Borra una solicitud.

¿Qué sigue?