Crea una suscripción a Google Workspace

En esta página, se explica cómo usar la API de Google Workspace Events para crear una suscripción a un recurso de Google Workspace. Una suscripción a Google Workspace permite que la app reciba información sobre los eventos de Google Workspace, que representan cambios en un recurso de Google Workspace. Para saber qué recursos y tipos de eventos admite la API de Google Workspace Events, consulta la descripción general de la API de Eventos de Google Workspace.

En esta página, se incluyen los siguientes pasos para crear una suscripción a Google Workspace:

  1. Configurar el entorno
  2. Crear un tema de Google Cloud Pub/Sub y suscribirte a él Debes usar este tema como extremo para recibir eventos de Google Workspace.
  3. Llama al método create() de la API de Google Workspace Events en el recurso Subscription.
  4. Prueba tu suscripción a Google Workspace para asegurarte de que el tema de Pub/Sub reciba los eventos a los que te suscribiste.
  5. De manera opcional, configura cómo enviar eventos a un extremo de tu app para que esta pueda procesar el evento y, de ser necesario, tomar medidas.

Requisitos previos

Python

  • Python 3.6 o superior
  • La herramienta de administración de paquetes pip
  • Las bibliotecas cliente de Google más recientes para Python. Para instalarlos o actualizarlos, ejecuta el siguiente comando en tu interfaz de línea de comandos:
      pip3 install --upgrade google-api-python-client google-auth-oauthlib
      
  • Para usar los comandos de Google Cloud CLI en esta guía, haz lo siguiente:
    1. Instala Google Cloud CLI.
    2. Para inicializar la CLI de gcloud, ejecuta el siguiente código:
    3.   gcloud init
        
  • Un recurso de destino para la suscripción:

    • Para suscribirte a un espacio de Google Chat, es un espacio de Chat en el que el usuario autenticado es miembro. El usuario debe ser miembro del espacio a través de su Cuenta de Google o de Google Workspace (no se admiten usuarios que sean miembros de un espacio a través de un Grupo de Google).

    • Para suscribirte a una sala de reuniones de Google Meet, una sala de reuniones en la que el usuario autenticado sea el propietario. Para crear un espacio, consulta Trabaja con salas de reuniones en la documentación de Google Meet.

    • Para suscribirte a un usuario de Google Meet, el ID de user de la API de Cloud Identity.

  • Un proyecto de Google Cloud con la facturación habilitada

Para suscripciones a Chat, también debes habilitar la API de Chat en tu proyecto de Cloud y configurar los campos Nombre de la app, URL del avatar y Descripción. Para obtener más detalles, consulta Cómo compilar una app de Google Chat.

  • Se requiere la autenticación del usuario con la pantalla de consentimiento de OAuth configurada para la app. Cuando la configures, debes especificar un alcance que admita cada tipo de evento de la suscripción. Para configurar la pantalla de consentimiento y, luego, identificar los permisos requeridos, consulta Cómo elegir los permisos.

Configura tu entorno

En la siguiente sección, se explica cómo configurar tu entorno antes de crear una suscripción a Google Workspace.

Habilita la API de Google Workspace Events y la API de Google Cloud Pub/Sub

Antes de usar las APIs de Google, debes activarlas en un proyecto de Google Cloud. Puedes activar una o más APIs en un solo proyecto de Google Cloud.

Consola de Google Cloud

En la consola de Google Cloud, abre el proyecto de Google Cloud de tu app y habilita la API de Google Workspace Events y la API de Pub/Sub:

Habilita las APIs

gcloud

  1. En el directorio de trabajo, accede a tu Cuenta de Google:

    gcloud auth login
    
  2. Configura tu proyecto en el proyecto de Cloud para tu app:

    gcloud config set project PROJECT_ID
    

    Reemplaza PROJECT_ID por el ID del proyecto de Cloud de tu app.

  3. Habilita la API de Google Workspace Events y la API de Google Cloud Pub/Sub:

    gcloud services enable pubsub.googleapis.com workspaceevents.googleapis.com
    

Crear credenciales de ID de cliente de OAuth

Elige el tipo de aplicación para obtener instrucciones específicas sobre cómo crear un ID de cliente de OAuth:

Aplicación web

  1. En la consola de Google Cloud, ve a Menú > APIs y servicios > Credenciales.

    Ir a Credenciales

  2. Haz clic en Crear credenciales > ID de cliente de OAuth.
  3. Haz clic en Tipo de aplicación > Aplicación web.
  4. En el campo Nombre, escribe un nombre para la credencial. Este nombre solo se muestra en la consola de Google Cloud.
  5. Agrega los URIs autorizados relacionados con tu app:
    • Apps del cliente (JavaScript): En Orígenes autorizados de JavaScript, haz clic en Agregar URI. Luego, ingresa el URI que usarás en las solicitudes del navegador. Esto identifica los dominios desde los cuales tu aplicación puede enviar solicitudes de API al servidor OAuth 2.0.
    • Apps del servidor (Java, Python y mucho más): En URI de redireccionamiento autorizados, haz clic en Agregar URI. Luego, ingresa el URI del extremo al que el servidor de OAuth 2.0 pueda enviar respuestas.
  6. Haz clic en Crear. Aparecerá la pantalla de creación del cliente de OAuth, en la que se mostrará tu ID de cliente nuevo y el secreto del cliente.

    Toma nota del ID de cliente. Los secretos del cliente no se usan para aplicaciones web.

  7. Haz clic en OK. La credencial creada recientemente aparecerá en IDs de cliente de OAuth 2.0.

Android

  1. En la consola de Google Cloud, ve a Menú > APIs y servicios > Credenciales.

    Ir a Credenciales

  2. Haz clic en Crear credenciales > ID de cliente de OAuth.
  3. Haz clic en Tipo de aplicación > Android.
  4. En el campo "Nombre", escribe un nombre para la credencial. Este nombre solo se muestra en la consola de Google Cloud.
  5. En el campo "Nombre del paquete", ingresa el nombre del paquete de tu archivo AndroidManifest.xml.
  6. En el campo “Huella digital del certificado SHA-1”, ingresa la huella digital del certificado SHA-1 generado.
  7. Haz clic en Crear. Aparecerá la pantalla de creación del cliente de OAuth, en la que se mostrará tu ID de cliente nuevo.
  8. Haz clic en OK. La credencial creada recientemente aparecerá en “ID de cliente OAuth 2.0”.

iOS

  1. En la consola de Google Cloud, ve a Menú > APIs y servicios > Credenciales.

    Ir a Credenciales

  2. Haz clic en Crear credenciales > ID de cliente de OAuth.
  3. Haz clic en Tipo de aplicación > iOS.
  4. En el campo "Nombre", escribe un nombre para la credencial. Este nombre solo se muestra en la consola de Google Cloud.
  5. En el campo "ID del paquete", ingresa el identificador del paquete como aparece en el archivo Info.plist de la app.
  6. Opcional: Si tu aplicación aparece en la App Store de Apple, ingresa el ID de App Store.
  7. Opcional: En el campo "ID de equipo", ingresa la cadena única de 10 caracteres generada por Apple y asignada a tu equipo.
  8. Haz clic en Crear. Aparecerá la pantalla de creación del cliente de OAuth, en la que se mostrará tu ID de cliente nuevo y el secreto del cliente.
  9. Haz clic en OK. La credencial creada recientemente aparecerá en “ID de cliente OAuth 2.0”.

App de Chrome

  1. En la consola de Google Cloud, ve a Menú > APIs y servicios > Credenciales.

    Ir a Credenciales

  2. Haz clic en Crear credenciales > ID de cliente de OAuth.
  3. Haz clic en Tipo de aplicación > App de Chrome.
  4. En el campo "Nombre", escribe un nombre para la credencial. Este nombre solo se muestra en la consola de Google Cloud.
  5. En el campo “ID de aplicación”, ingresa la cadena de ID única de 32 caracteres de tu app. Puedes encontrar este valor de ID en la URL de Chrome Web Store de tu app y en el Panel del desarrollador de Chrome Web Store.
  6. Haz clic en Crear. Aparecerá la pantalla de creación del cliente de OAuth, en la que se mostrará tu ID de cliente nuevo y el secreto del cliente.
  7. Haz clic en OK. La credencial creada recientemente aparecerá en “ID de cliente OAuth 2.0”.

App de escritorio

  1. En la consola de Google Cloud, ve a Menú > APIs y servicios > Credenciales.

    Ir a Credenciales

  2. Haz clic en Crear credenciales > ID de cliente de OAuth.
  3. Haz clic en Tipo de aplicación > App de escritorio.
  4. En el campo Nombre, escribe un nombre para la credencial. Este nombre solo se muestra en la consola de Google Cloud.
  5. Haz clic en Crear. Aparecerá la pantalla de creación del cliente de OAuth, en la que se mostrará tu ID de cliente nuevo y el secreto del cliente.
  6. Haz clic en OK. La credencial creada recientemente aparecerá en IDs de cliente de OAuth 2.0.

TVs y dispositivos de entrada limitada

  1. En la consola de Google Cloud, ve a Menú > APIs y servicios > Credenciales.

    Ir a Credenciales

  2. Haz clic en Crear credenciales > ID de cliente de OAuth.
  3. Haz clic en Tipo de aplicación > TVs y dispositivos de entrada limitados.
  4. En el campo "Nombre", escribe un nombre para la credencial. Este nombre solo se muestra en la consola de Google Cloud.
  5. Haz clic en Crear. Aparecerá la pantalla de creación del cliente de OAuth, en la que se mostrará tu ID de cliente nuevo y el secreto del cliente.
  6. Haz clic en OK. La credencial creada recientemente aparecerá en “ID de cliente OAuth 2.0”.

Plataforma universal de Windows (UWP)

  1. En la consola de Google Cloud, ve a Menú > APIs y servicios > Credenciales.

    Ir a Credenciales

  2. Haz clic en Crear credenciales > ID de cliente de OAuth.
  3. Haz clic en Tipo de aplicación > Universal Windows Platform (UWP).
  4. En el campo "Nombre", escribe un nombre para la credencial. Este nombre solo se muestra en la consola de Google Cloud.
  5. En el campo "ID de tienda", ingresa el valor del ID de Microsoft Store único de 12 caracteres de tu aplicación. Puedes encontrar este ID en la URL de Microsoft Store de tu app y en el Centro de socios.
  6. Haz clic en Crear. Aparecerá la pantalla de creación del cliente de OAuth, en la que se mostrará tu ID de cliente nuevo y el secreto del cliente.
  7. Haz clic en OK. La credencial creada recientemente aparecerá en “ID de cliente OAuth 2.0”.

Descarga el archivo JSON del secreto del cliente

El archivo del secreto del cliente es una representación JSON de las credenciales de ID de cliente de OAuth a las que tu app puede hacer referencia cuando proporciona credenciales.

  1. En la consola de Google Cloud, ve a Menú > APIs y servicios > Credenciales.

    Ir a Credenciales

  2. En ID de cliente OAuth 2.0, haz clic en el ID de cliente que creaste.

  3. Haz clic en Descargar JSON.

  4. Guarda el archivo como client_secrets.json.

Crea un tema de Pub/Sub y suscríbete a él

En esta sección, crearás un tema de Pub/Sub y una suscripción al tema. Tu tema de Pub/Sub sirve como el extremo de notificación en el que tu suscripción a Google Workspace recibe eventos.

Para obtener más información sobre cómo crear y administrar temas de Pub/Sub, consulta la documentación de Pub/Sub.

Para crear un tema de Pub/Sub y suscribirte a uno, haz lo siguiente:

Consola de Google Cloud

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

    Ir a Google Cloud Pub/Sub

    Asegúrate de que esté seleccionado el proyecto de Cloud para tu app.

  2. Haz clic en Crear tema y haz lo siguiente:

    1. Ingresa un nombre para el tema, como workspace-events-topic.
    2. Deja seleccionada la opción Agregar una suscripción predeterminada. Pub/Sub nombra esta suscripción predeterminada como el nombre de tu tema, como workspace-events-topic-sub.
    3. Opcional: Actualiza o configura propiedades adicionales para tu tema.
  3. Haz clic en Crear. El nombre completo del tema tiene el formato projects/PROJECT_ID/topics/TOPIC_ID. Usarás este nombre completo en un paso posterior.

  4. Otorga acceso para publicar mensajes de Pub/Sub en tu tema:

    1. En la página de tu tema, ve al panel lateral y abre la pestaña Permisos.
    2. Haz clic en Agregar permisos de cuenta principal.
    3. En el campo Agregar principales, agrega la cuenta de servicio para la aplicación de Google Workspace que entrega eventos a la suscripción:
      1. Para eventos de Chat, chat-api-push@system.gserviceaccount.com.
      2. Para eventos de Meet, meet-api-event-push@system.gserviceaccount.com.
    4. En el menú Asignar roles, selecciona Pub/Sub Publisher.
    5. Haz clic en Guardar. Es posible que la actualización de los permisos de tu tema tome unos minutos.

gcloud

  1. En tu proyecto de Cloud, ejecuta el siguiente comando para crear un tema:

    gcloud pubsub topics create TOPIC_ID
    

    Reemplaza TOPIC_ID por un ID único para tu tema, como workspace-events-topic.

    El resultado muestra el nombre completo del tema, con el formato projects/PROJECT_ID/topics/TOPIC_ID. Toma nota del nombre y asegúrate de que el valor de PROJECT_ID sea el ID del proyecto de Cloud de tu app. Usarás el nombre del tema en el siguiente paso y crearás la suscripción a Google Workspace más adelante.

  2. Otorga acceso para publicar mensajes en tu tema:

    gcloud pubsub topics add-iam-policy-binding TOPIC_NAME --member='serviceAccount:GOOGLE_WORKSPACE_APPLICATION' --role='roles/pubsub.publisher'
    

    Reemplaza lo siguiente:

    • TOPIC_NAME: Es el nombre completo del tema, que es el resultado del paso anterior. Tiene el formato projects/PROJECT_ID/topics/TOPIC_ID.
    • GOOGLE_WORKSPACE_APPLICATION: Es la aplicación de Google Workspace que debe entregar eventos a la suscripción:

      • Para recibir eventos de Chat, usa chat-api-push@system.gserviceaccount.com.
      • Para recibir eventos de Meet, usa meet-api-event-push@system.gserviceaccount.com.

    Es posible que la actualización de los permisos de tu tema tarde unos minutos.

  3. Crea una suscripción a Pub/Sub para el tema.

     gcloud pubsub subscriptions create SUBSCRIPTION_NAME --topic=TOPIC_NAME
    

    Reemplaza lo siguiente:

    • SUBSCRIPTION_NAME: Es un nombre para la suscripción, como workspace-events-subscription.
    • TOPIC_NAME: Es el nombre del tema que creaste en el paso anterior.

Crea una suscripción a Google Workspace

En esta sección, usarás el método subscriptions.create() de la API de Google Workspace Events para crear un recurso Subscription. Debes especificar los siguientes campos:

  • targetResource: Es un recurso de Google Workspace para supervisar eventos, como un espacio de Chat.
  • eventTypes: Es un array de uno o más tipos de eventos que deseas recibir acerca del recurso. Por ejemplo, si tu app solo necesita conocer los mensajes nuevos publicados en un espacio de Chat, puede suscribirse a eventos sobre mensajes creados.
  • notificationEndpoint: Un extremo de notificación en el que tu suscripción a Google Workspace entrega eventos. Usa el tema de Pub/Sub que creaste en la sección anterior.
  • payloadOptions: opciones para especificar cuántos datos de recursos se incluirán en la carga útil del evento. Esta configuración afecta la fecha y hora de vencimiento de tu suscripción. Para obtener más información, consulta Datos de eventos.

Para crear una suscripción a Google Workspace, haz lo siguiente:

Python

  1. En tu directorio de trabajo, crea un archivo llamado create_subscription.py y agrega el siguiente código:

    """Create subscription."""
    
    from google_auth_oauthlib.flow import InstalledAppFlow
    from googleapiclient.discovery import build
    
    # Specify required scopes.
    SCOPES = [SCOPES]
    
    # Authenticate with Google Workspace and get user authentication.
    flow = InstalledAppFlow.from_client_secrets_file('client_secrets.json', SCOPES)
    CREDENTIALS = flow.run_local_server()
    
    # The Google Workspace resource to monitor for events.
    TARGET_RESOURCE = 'TARGET_RESOURCE'
    
    # The types of events to receive.
    EVENT_TYPES = [EVENT_TYPES]
    
    # The endpoint to deliver events to, such as a Google Cloud Pub/Sub topic.
    TOPIC = 'TOPIC_NAME'
    
    # Call the Workspace Events API using the service endpoint.
    service = build(
        'workspaceevents',
        'v1',
        credentials=CREDENTIALS,
    )
    
    BODY = {
        'target_resource': TARGET_RESOURCE,
        'event_types': EVENT_TYPES,
        'notification_endpoint': {'pubsub_topic': TOPIC},
        'payload_options': {'include_resource': RESOURCE_DATA},
    }
    response = service.subscriptions().create(body=BODY).execute()
    print(response)
    

    Reemplaza lo siguiente:

    • SCOPES: Uno o más permisos de OAuth que admiten cada tipo de evento para la suscripción. Tiene el formato de un array de cadenas. Para enumerar varios permisos, sepáralos con comas. Por ejemplo, 'https://www.googleapis.com/auth/chat.spaces.readonly', 'https://www.googleapis.com/auth/chat.memberships.readonly'.
    • TARGET_RESOURCE: Es el recurso de Google Workspace al que te estás suscribiendo, con el formato de su nombre completo de recurso. Por ejemplo, para suscribirte a un espacio de Google Chat con el ID del espacio AAAABBBB, usa //chat.googleapis.com/spaces/AAAABBBB.
    • EVENT_TYPES: Uno o más tipos de eventos a los que deseas suscribirte en el recurso de destino. Da formato a un array de cadenas, como 'google.workspace.chat.message.v1.created'.
    • TOPIC_NAME: Es el nombre completo del tema de Pub/Sub que creaste en tu proyecto de Cloud. Tiene el formato projects/PROJECT_ID/topics/TOPIC_ID.
    • RESOURCE_DATA: un valor booleano que especifica si la suscripción incluye datos de recursos en la carga útil:

      • True: Incluye todos los datos de recursos. Para limitar los campos que se incluyen, agrega el campo fieldMask y especifica al menos un campo para el recurso modificado. Solo se admiten las suscripciones a los recursos de Chat, incluidos los datos de recursos.
      • False: Excluye los datos de recursos.
  2. Para crear la suscripción a Google Workspace, ejecuta lo siguiente en tu terminal:

    python3 create_subscription.py
    

La API de Google Workspace Events muestra una operación de larga duración completada que contiene la instancia del recurso Subscription que creaste.

Prueba tu suscripción a Google Workspace

Para probar que recibes eventos de Google Workspace, puedes activar un evento y extraer mensajes a la suscripción a Pub/Sub.

Sigue estos pasos para probar tu suscripción a Google Workspace:

Consola de Google Cloud

  1. Activa uno o más tipos de eventos en el recurso de destino de tu suscripción a Google Workspace. Por ejemplo, si te suscribiste a mensajes nuevos en un espacio de Chat, publica un mensaje en el espacio.

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

    Ir a Pub/Sub

    Asegúrate de que esté seleccionado el proyecto de Cloud para tu app.

  3. En el menú de Pub/Sub, haz clic en Suscripciones.

  4. En la tabla, busca la suscripción a Pub/Sub correspondiente a tu tema y haz clic en el nombre de la suscripción.

  5. Haz clic en la pestaña Mensajes.

  6. Haz clic en Extraer. Un evento puede tardar unos minutos en generar un mensaje de Pub/Sub.

gcloud

  1. Activa uno o más tipos de eventos en el recurso de destino de tu suscripción a Google Workspace. Por ejemplo, si te suscribiste a mensajes nuevos en un espacio de Chat, publica un mensaje en ese espacio.

  2. Ejecuta el siguiente comando:

    gcloud pubsub subscriptions pull PUBSUB_SUBSCRIPTION_NAME --format=json --limit=MESSAGE_COUNT --auto-ack
    

    Reemplaza lo siguiente:

    • PUBSUB_SUBSCRIPTION_NAME: Es el nombre completo de tu suscripción a Pub/Sub, con el formato projects/SUBSCRIPTION_ID/subscriptions/SUBSCRIPTION_ID.
    • MESSAGE_COUNT: La cantidad máxima de mensajes de Pub/Sub que deseas extraer.

    Un evento puede tardar unos minutos en generar un mensaje de Pub/Sub.

Por cada evento de Google Workspace que activaste, se entrega un mensaje a tu suscripción a Pub/Sub que contiene el evento. Para obtener más información, consulta Recibe eventos como mensajes de Google Cloud Pub/Sub.

Configura la forma en que tu app recibe eventos

La suscripción de Pub/Sub que creaste está basada en extracciones. Después de probar la suscripción a Pub/Sub, puedes actualizar el tipo de entrega para cambiar la forma en que la app recibe eventos. Por ejemplo, puedes configurar la suscripción a Pub/Sub para un tipo de entrega de envío, de modo que tu aplicación pueda recibir eventos directamente en un extremo de la aplicación.

Si quieres obtener información para configurar una suscripción a Pub/Sub, consulta la documentación de Pub/Sub.