Recibe notificaciones con feeds de cambios de metadatos

En este documento, se describe cómo configurar los feeds de cambios de metadatos de Knowledge Catalog (anteriormente, Dataplex Universal Catalog) para recibir notificaciones a través de Pub/Sub cuando se crean, actualizan o borran metadatos en Knowledge Catalog.

Para obtener más información sobre los feeds de cambios de metadatos, consulta la Descripción general de los feeds de cambios de metadatos.

Antes de comenzar

Familiarízate con Pub/Sub y la API de Dataplex.

  1. Habilita las APIs de Dataplex y Pub/Sub.

    Roles necesarios para habilitar las APIs

    Para habilitar las APIs, necesitas el rol de IAM de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin), que contiene el permiso serviceusage.services.enable. Obtén más información para otorgar roles.

    Habilitar las API

  2. Crea un tema de Pub/Sub para recibir notificaciones. Para obtener más información, consulta Crea un tema.

  3. Instalar gcloud. Asegúrate de que esté configurado el alias corto de gcloud.

  4. Establece un alias de gcurl. Esto crea un acceso directo que incluye tu token de autenticación y establece el tipo de contenido JSON para las solicitudes a la API:

    alias gcurl='curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json"'

  5. Configura la variable DATAPLEX_API:

    DATAPLEX_API="dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION"

    Reemplaza lo siguiente:

    • PROJECT_ID: Es el ID del proyecto en el que está habilitada la API de Dataplex.
    • LOCATION: Es la ubicación en la que se ejecuta el trabajo, por ejemplo, us-central1, europe-west3 o asia-south1.

Roles y permisos requeridos

Para configurar los feeds de cambios de metadatos, asegúrate de que tú y la cuenta de servicio de Knowledge Catalog tengan los roles y permisos de IAM necesarios.

Roles y permisos de los usuarios

Para obtener los permisos que necesitas para exportar metadatos y acceder a los mensajes de los feeds de cambios de metadatos, pídele a tu administrador que te otorgue los siguientes roles de IAM en el proyecto o la organización:

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

Estos roles predefinidos contienen los permisos necesarios para exportar metadatos y acceder a los mensajes de los feeds de cambios de metadatos. Para ver los permisos exactos que son necesarios, expande la sección Permisos requeridos:

Permisos necesarios

Se requieren los siguientes permisos para exportar metadatos y acceder a los mensajes de los feeds de cambios de metadatos:

  • Exportar metadatos:
    • dataplex.metadataFeeds.create en el proyecto
    • dataplex.entryGroups.export en el recurso que define el alcance del feed (organización, proyecto o grupo de entradas)
    • resourcemanager.projects.get en el proyecto
    • resourcemanager.projects.list en el proyecto
  • Accede a los mensajes de los feeds de cambios en los metadatos:
    • pubsub.subscriptions.consume en la suscripción
    • pubsub.topics.attachSubscription sobre el tema

También puedes obtener estos permisos con roles personalizados o con otros roles predefinidos.

Roles y permisos de la cuenta de servicio de Knowledge Catalog

Para garantizar que la cuenta de servicio de Knowledge Catalog tenga el permiso necesario para publicar mensajes de feeds de cambios de metadatos, pídele a tu administrador que le otorgue a la cuenta de servicio de Knowledge Catalog el rol de IAM de publicador de Pub/Sub (roles/pubsub.publisher) y visualizador de Pub/Sub (roles/pubsub.viewer) en el tema de Pub/Sub.

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

Este rol predefinido contiene los permisos pubsub.topics.publish y pubsub.topics.get, que se requieren para publicar mensajes de feeds de cambios de metadatos.

Es posible que tu administrador también pueda otorgar este permiso a la cuenta de servicio de Knowledge Catalog con roles personalizados o con otros roles predefinidos.

Otorga permisos a la cuenta de servicio de Knowledge Catalog

El agente de servicio en Knowledge Catalog se crea cuando habilitas la API de Dataplex. Puedes identificar al agente de servicio por su ID de correo electrónico:

service-PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com

Aquí, PROJECT_NUMBER es el número del proyecto en el que habilitaste la API de Dataplex.

La cuenta de servicio de Knowledge Catalog requiere la capacidad de publicar mensajes en tu tema de Pub/Sub y recuperar metadatos del tema. Para otorgar estos permisos, asigna a la cuenta de servicio el rol de publicador de Pub/Sub (roles/pubsub.publisher) y el rol de visualizador de Pub/Sub (roles/pubsub.viewer) en el tema de Pub/Sub:

gcloud

Ejecuta el comando gcloud pubsub topics add-iam-policy-binding:

gcloud pubsub topics add-iam-policy-binding TOPIC_ID \
    --member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com" \
    --role="roles/pubsub.publisher"

gcloud pubsub topics add-iam-policy-binding TOPIC_ID \
    --member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com" \
    --role="roles/pubsub.viewer"

Reemplaza lo siguiente:

  • TOPIC_ID: Es el ID de tu tema de Pub/Sub en el que se publican los mensajes del feed de cambios de metadatos.
  • PROJECT_NUMBER: Es el número del proyecto de Knowledge Catalog en el que se encuentra la cuenta de servicio.

Console

  1. En la consola de Google Cloud , ve a la página Temas de Pub/Sub.

    Ir a temas

  2. Selecciona el tema que usas para las notificaciones del feed de metadatos y, si es necesario, haz clic en Mostrar panel de información.

  3. En la pestaña Permisos, haz clic en Agregar principal.

  4. En el campo Principales nuevas, ingresa la cuenta de servicio de Knowledge Catalog: service-PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com.

  5. En el campo Asignar roles, selecciona Publicador de Pub/Sub.

  6. Haz clic en Agregar otro rol y selecciona Visualizador de Pub/Sub.

  7. Haz clic en Guardar.

Crea un feed de cambios de metadatos

Para controlar qué cambios generan notificaciones, puedes configurar un feed de cambios de metadatos para supervisar recursos específicos. Para ello, debes especificar un alcance, como toda tu organización, proyectos específicos o grupos de entradas específicos. Si bien el alcance te permite definir qué recursos supervisar, puedes usar filtros para definir con mayor precisión cuándo Knowledge Catalog envía notificaciones.

Para obtener más información, consulta Feed de cambios de metadatos.

REST

Para crear un feed de cambios de metadatos, usa el método projects.locations.metadataFeeds.create.

Permiso de la organización

Ejecuta el siguiente comando para crear un feed de cambios de metadatos que supervise toda la organización:

gcurl -X POST -d "$(cat <<EOF
{
  "scope": {
    "organizationLevel": true
  },
  "pubsubTopic": "projects/PROJECT_ID_PUBSUB/topics/TOPIC_ID"
}
EOF
)" "https://${DATAPLEX_API}/metadataFeeds?metadataFeedId=FEED_ID"

Reemplaza lo siguiente:

  • PROJECT_ID_PUBSUB: Es el ID del proyecto en el que se encuentra el tema de Pub/Sub, por ejemplo, example-project.
  • TOPIC_ID: Es el ID del tema de Pub/Sub en el que se publican los mensajes del feed de cambios de metadatos, por ejemplo, example-topic.
  • FEED_ID: Es el ID del feed de cambios de metadatos que deseas crear, por ejemplo, example-feed.

Alcance del proyecto

Ejecuta el siguiente comando para crear un feed de cambios de metadatos que supervise proyectos específicos:

gcurl -X POST -d "$(cat <<EOF
{
  "scope": {
    "projects": [
      "projects/PROJECT_ID_1",
      "projects/PROJECT_ID_2"
    ]
  },
  "pubsubTopic": "projects/PROJECT_ID_PUBSUB/topics/TOPIC_ID"
}
EOF
)" "https://${DATAPLEX_API}/metadataFeeds?metadataFeedId=FEED_ID"

Reemplaza lo siguiente:

  • PROJECT_ID_PUBSUB: Es el ID del proyecto en el que se encuentra el tema de Pub/Sub, por ejemplo, example-project.
  • TOPIC_ID: Es el ID del tema de Pub/Sub en el que se publican los mensajes del feed de cambios de metadatos, por ejemplo, example-topic.
  • FEED_ID: Es el ID del feed de cambios de metadatos que deseas crear, por ejemplo, example-feed.

Alcance del grupo de entrada

Ejecuta el siguiente comando para crear un feed de cambios de metadatos que supervise grupos de entradas específicos:

gcurl -X POST -d "$(cat <<EOF
{
  "scope": {
    "entryGroups": [
      "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID_1",
      "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID_2"
    ]
  },
  "pubsubTopic": "projects/PROJECT_ID_PUBSUB/topics/TOPIC_ID"
}
EOF
)" "https://${DATAPLEX_API}/metadataFeeds?metadataFeedId=FEED_ID"

Reemplaza lo siguiente:

  • PROJECT_ID_PUBSUB: Es el ID del proyecto en el que se encuentra el tema de Pub/Sub, por ejemplo, example-project.
  • LOCATION: Es la ubicación en la que deseas crear el feed, por ejemplo, us-central1.
  • ENTRY_GROUP_ID: Es el ID del grupo de entradas que se supervisará, por ejemplo, example-entry-group.
  • TOPIC_ID: Es el ID del tema de Pub/Sub en el que se publican los mensajes del feed de cambios de metadatos, por ejemplo, example-topic.
  • FEED_ID: Es el ID del feed de cambios de metadatos que deseas crear, por ejemplo, example-feed.

Con filtros

Ejecuta el siguiente comando para crear un feed de cambios de metadatos con filtros (filtrado por tipo de entrada):

gcurl -X POST -d "$(cat <<EOF
{
  "scope": {
    "projects": [
      "projects/PROJECT_ID_1",
      "projects/PROJECT_ID_2"
    ]
  },
  "filter": {
    "entryTypes": [
      "projects/PROJECT_ID/locations/global/entryTypes/bigquery-table"
    ]
  },
  "pubsubTopic": "projects/PROJECT_ID_PUBSUB/topics/TOPIC_ID"
}
EOF
)" "https://${DATAPLEX_API}/metadataFeeds?metadataFeedId=FEED_ID"

Reemplaza lo siguiente:

  • PROJECT_ID_PUBSUB: Es el ID del proyecto en el que se encuentra el tema de Pub/Sub, por ejemplo, example-project.
  • TOPIC_ID: Es el ID del tema de Pub/Sub en el que se publican los mensajes del feed de cambios de metadatos, por ejemplo, example-topic.
  • FEED_ID: Es el ID del feed de cambios de metadatos que deseas crear, por ejemplo, example-feed.

Respuesta:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.dataplex.v1.OperationMetadata",
    "createTime": "2023-10-02T15:01:23Z",
    "target": "projects/PROJECT_ID/locations/LOCATION/metadataFeeds/FEED_ID",
    "verb": "create",
    "apiVersion": "v1"
  },
  "done": false
}

Visualiza los feeds de cambios de metadatos

Puedes ver los detalles de un feed de cambios de metadatos.

REST

Para ver un feed de cambios de metadatos, usa el método projects.locations.metadataFeeds.get.

Ejecuta el comando siguiente:

gcurl "https://${DATAPLEX_API}/metadataFeeds/FEED_ID"

Reemplaza lo siguiente:

  • FEED_ID: Es el ID del feed de cambios de metadatos que deseas ver, por ejemplo, example-feed.

Enumera los feeds de cambios de metadatos

Puedes enumerar los feeds de cambios de metadatos en un proyecto y una ubicación.

REST

Para enumerar los feeds de cambios de metadatos, usa el método projects.locations.metadataFeeds.list.

Ejecuta el comando siguiente:

gcurl "https://${DATAPLEX_API}/metadataFeeds"

Actualiza un feed de cambios de metadatos

Puedes actualizar el alcance o los filtros de un feed de cambios de metadatos existente.

REST

Para actualizar un feed de cambios de metadatos, usa el método projects.locations.metadataFeeds.patch.

Ejecuta el siguiente comando para actualizar el feed de cambios de metadatos y quitar los filtros de tipo de entrada:

gcurl -X PATCH -d "$(cat <<EOF
{
  "filter": {
    "entryTypes": []
  }
}
EOF
)" "https://${DATAPLEX_API}/metadataFeeds/FEED_ID?updateMask=filter"

Reemplaza lo siguiente:

  • FEED_ID: ID del feed de cambios de metadatos que deseas actualizar, por ejemplo, example-feed

Borra un feed de cambios de metadatos

Puedes borrar un feed de cambios de metadatos si ya no necesitas recibir notificaciones.

Si borras un feed de cambios de metadatos, el feed dejará de publicar cambios de metadatos nuevos en tu tema de Pub/Sub. Sin embargo, no borra el tema ni la suscripción asociados con el feed. Si ya no los necesitas, debes borrarlos de forma manual.

Antes de borrar el feed o la suscripción, asegúrate de que tus aplicaciones de suscriptor hayan procesado todos los mensajes pendientes en la suscripción de Pub/Sub.

REST

Para borrar un feed de cambios de metadatos, usa el método projects.locations.metadataFeeds.delete.

Ejecuta el comando siguiente:

gcurl -X DELETE \
"https://${DATAPLEX_API}/metadataFeeds/FEED_ID"

Reemplaza lo siguiente:

  • FEED_ID: Es el ID del feed de cambios de metadatos que deseas borrar, por ejemplo, example-feed.

Consume mensajes de notificación

Después de configurar un feed de cambios de metadatos, Knowledge Catalog publica mensajes en el tema de Pub/Sub especificado cuando se producen cambios en los metadatos. Para consumir estos mensajes, crea una suscripción a Pub/Sub para el tema.

Por ejemplo, puedes crear una suscripción de extracción y usar Google Cloud CLI para ver mensajes:

  1. Crea una suscripción:

    gcloud pubsub subscriptions create SUBSCRIPTION_ID --topic=TOPIC_ID

    Reemplaza lo siguiente:

    • SUBSCRIPTION_ID: Es el ID de la suscripción que deseas crear.
    • TOPIC_ID: Es el ID del tema de Pub/Sub en el que se publican los mensajes del feed de cambios de metadatos.

  2. Extrae mensajes de la suscripción:

    gcloud pubsub subscriptions pull SUBSCRIPTION_ID --auto-ack --limit=10

    Reemplaza lo siguiente:

    • SUBSCRIPTION_ID: ID de la suscripción desde la que deseas extraer mensajes

Para obtener más información sobre el procesamiento de mensajes de Pub/Sub, consulta Cómo recibir mensajes de una suscripción de extracción. Para obtener información sobre el formato del mensaje, consulta Carga útil de datos.

¿Qué sigue?