Solicita cambios en los metadatos por lotes con flujos de trabajo de administración

En este documento, se describe cómo enviar una solicitud de cambio de metadatos por lotes para un grupo de entradas en Knowledge Catalog (antes Dataplex Universal Catalog) con la API de REST.

Si no tienes acceso de escritura directo a un grupo de entradas, puedes agrupar hasta 250 operaciones de creación, actualización y eliminación de entradas y vínculos de entrada en una sola solicitud de cambio para su revisión y aprobación.

Antes de comenzar

Para enviar solicitudes de cambio de metadatos por lotes, asegúrate de haber habilitado las APIs requeridas y de tener los roles y permisos de Identity and Access Management (IAM) necesarios en el grupo de entradas de destino.

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 solicitar cambios de metadatos por lotes en un grupo de entradas, pídele a tu administrador que te otorgue los siguientes roles de IAM en el grupo de entradas de destino:

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.

Crea una solicitud de cambio de metadatos por lotes

Cuando envías una solicitud de cambio por lotes, Knowledge Catalog verifica la sintaxis de la solicitud y que existan los tipos de entrada, los tipos de aspecto, los tipos de vínculo de entrada y las entradas superiores a las que se hace referencia. Cuando se aprueba la solicitud, Knowledge Catalog verifica si existen las entradas y los vínculos de entrada de destino; por ejemplo, devuelve un error ALREADY_EXISTS cuando se crea un recurso existente o un error NOT_FOUND cuando se actualiza o borra un recurso faltante.

Cuando un responsable de aprobación aprueba una solicitud de cambio por lotes, Knowledge Catalog aplica automáticamente las operaciones en el siguiente orden de dependencia:

  1. Borrar vínculos de entrada
  2. Borra entradas.
  3. Crear y actualizar entradas
  4. Crear y actualizar vínculos de entrada

Las solicitudes de cambio por lotes no proporcionan coherencia transaccional ni reversión automática. Cuando se aprueba, Knowledge Catalog evalúa y aplica cada operación de forma individual.

Ten en cuenta las siguientes reglas de referencia cuando construyas un lote:

  • No hagas referencia a entradas borradas en el mismo lote: No puedes crear ni actualizar un vínculo de entrada que haga referencia a una entrada que se borra en el mismo lote, y no puedes establecer parentEntry en una entrada que borras en el mismo lote.
  • Enumera las entradas superiores antes que las secundarias: Si una entrada nueva hace referencia a otra entrada en el mismo lote que su parentEntry, enumera la solicitud que crea la entrada superior antes de la solicitud que crea la entrada secundaria. Cuando creas una entrada o un vínculo de entrada, el campo del grupo de entradas parent es opcional. Si omites parent, Knowledge Catalog usa el grupo de entradas en changePayload.name. Si incluyes parent, debe coincidir con changePayload.name.

Para enviar una solicitud básica de cambio de metadatos por lotes, usa el 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"

Reemplaza lo siguiente:

  • PROJECT_ID: Es el ID del proyecto de Google Cloud que contiene el grupo de entradas.
  • LOCATION: Es la ubicación del grupo de entradas, como us-central1.
  • ENTRY_GROUP_ID: Es el ID del grupo de entradas de destino.
  • ENTRY_ID: Es el ID de la entrada nueva que se creará.
  • ENTRY_TYPE_ID: Es el ID del tipo de entrada para la entrada nueva.
  • JUSTIFICATION: Es el motivo por el que se necesita la solicitud de cambio de metadatos, de hasta 1,024 caracteres.

El servicio devuelve una respuesta que contiene el nombre del recurso de la solicitud de cambio creada:

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

Verifica la solicitud de cambio por lotes creada

Para inspeccionar la solicitud de cambio creada, 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.
  • CHANGE_REQUEST_ID: Es el ID único de la solicitud.

El servicio devuelve un recurso ChangeRequest que contiene la carga útil del lote:

Respuesta de muestra para una solicitud de cambio por lotes enviada por el usuario

{
  "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 una ejecución del agente de enriquecimiento crea la solicitud de cambio por lotes de forma automática, el campo author contiene la cuenta de servicio del agente de enriquecimiento y el campo batchChangeMetadataRequest.description.job.name contiene el nombre del recurso de ejecución del enriquecimiento.

Crea una solicitud de cambio por lotes de varios recursos

Para proponer cambios en varios recursos de un solo grupo de entradas, usa el método entryGroups.requestBatchMetadataChange. Por ejemplo, puedes usar este método para crear una primera entrada, crear una segunda entrada con un aspecto adjunto y crear un vínculo de entrada direccional que las conecte.

Para crear una solicitud de cambio por lotes de varios recursos, envía la siguiente solicitud POST:

Solicitud de muestra para crear una solicitud de cambio por lotes de varios 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"

Reemplaza lo siguiente:

  • PROJECT_ID: Es el ID del proyecto de Google Cloud que contiene el grupo de entradas.
  • LOCATION: Es la ubicación del grupo de entradas, como us-central1.
  • ENTRY_GROUP_ID: Es el ID del grupo de entradas de destino.
  • FIRST_ENTRY_ID: Es el ID de la primera entrada personalizada, que se usa como SOURCE en el vínculo de la entrada.
  • SECOND_ENTRY_ID: Es el ID de la segunda entrada personalizada con un aspecto adjunto, que se usa como TARGET en el vínculo de entrada.
  • ENTRY_TYPE_ID: Es el ID del tipo de entrada para las entradas nuevas.
  • ASPECT_TYPE_ID: Es el ID del tipo de aspecto adjunto a la segunda entrada.
  • ASPECT_FIELD_NAME: Es el nombre del campo en la plantilla de aspecto.
  • ASPECT_FIELD_VALUE: Es el valor del campo de aspecto.
  • ENTRY_LINK_ID: Es el ID del vínculo de entrada que conecta las dos entradas.
  • ENTRY_LINK_TYPE_ID: Es el ID del tipo de vínculo de entrada, como my-entry-link-type.
  • JUSTIFICATION: Es la explicación de por qué se necesitan estos cambios en los metadatos.

El servicio devuelve una respuesta que contiene el nombre del recurso de la solicitud de cambio creada:

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

¿Qué sigue?