Как создать подписку Google Workspace

Apps Script

• Чтобы использовать команды Google Cloud CLI в этом руководстве:
  1. Установите Google Cloud CLI.
  2. Чтобы инициализировать CLI gcloud, выполните следующий код:

    gcloud init
    

• Проект Apps Script:
  • Используйте свой проект Google Cloud вместо проекта по умолчанию, который автоматически создает Apps Script.
  • Для всех областей действия, добавленных при настройке окна запроса доступа OAuth, необходимо также добавить области действия в файл appsscript.json в проекте Apps Script. Например, если вы указали область действия chat.messages, добавьте следующий код:

  "oauthScopes": [
    "https://www.googleapis.com/auth/chat.messages"
  ]
      

  • Включите расширенный сервис Google Workspace Events.

• Проект Google Cloud с включенными платежными функциями. Для подписок на Chat необходимо также включить Chat API в облачном проекте и настроить поля Название приложения, URL аватара и Описание. Подробнее о том, как создать приложение Google Chat…
• Требуется аутентификация и соответствующая область авторизации для каждого типа событий в подписке:
  • Обычно требуется аутентификация пользователя с помощью окна запроса доступа OAuth, настроенного для приложения. При настройке окна запроса доступа необходимо указать область действия, чтобы поддерживать каждый тип событий для подписки. Чтобы настроить окно запроса доступа и определить необходимые области действия, ознакомьтесь с разделом Выбор областей действия.
  • Чтобы подписаться на событие Chat в качестве приложения Chat, требуется аутентификация приложения с разовым одобрением администратора.

Python

• Python 3.6 или более поздней версии
• Инструмент управления пакетами pip
• Последние версии клиентских библиотек Google для Python. Чтобы установить или обновить их, выполните следующую команду в интерфейсе командной строки:

    pip3 install --upgrade google-api-python-client google-auth-oauthlib
    

• Чтобы использовать команды Google Cloud CLI в этом руководстве:
  1. Установите Google Cloud CLI.
  2. Чтобы инициализировать CLI gcloud, выполните следующий код:

    gcloud init
    

• Проект Google Cloud с включенными платежными функциями. Для подписок на Chat необходимо также включить Chat API в облачном проекте и настроить поля Название приложения, URL аватара и Описание. Подробнее о том, как создать приложение Google Chat…
• Требуется аутентификация и соответствующая область авторизации для каждого типа событий в подписке:
  • Обычно требуется аутентификация пользователя с помощью окна запроса доступа OAuth, настроенного для приложения. При настройке окна запроса доступа необходимо указать область действия, чтобы поддерживать каждый тип событий для подписки. Чтобы настроить окно запроса доступа и определить необходимые области действия, ознакомьтесь с разделом Выбор областей действия.
  • Чтобы подписаться на событие Chat в качестве приложения Chat, требуется аутентификация приложения с разовым одобрением администратора.

Консоль Google Cloud

В консоли Google Cloud откройте проект Google Cloud для своего приложения и включите Google Workspace Events API и Pub/Sub API:

Как включить API

gcloud

1. В рабочем каталоге войдите в аккаунт Google:

   gcloud auth login

2. Укажите облачный проект для приложения:

   gcloud config set project PROJECT_ID

   Замените PROJECT_ID на идентификатор проекта облачного проекта для вашего приложения.

3. Включите Google Workspace Events API и Google Cloud Pub/Sub API:

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

Google API Console

1. В Google API Console перейдите на страницу Pub/Sub:

   Перейти в Google Cloud Pub/Sub

   Убедитесь, что выбран облачный проект для вашего приложения.

2. Нажмите add_box Создать тему и выполните следующие действия:

   1. Введите название темы, например workspace-events-topic.
   2. Оставьте флажок Добавить подписку по умолчанию установленным. Pub/Sub присваивает подписке по умолчанию название, похожее на название темы, например workspace-events-topic-sub.
   3. При необходимости измените или настройте дополнительные свойства темы.

3. Нажмите Создать. Полное название темы имеет формат projects/PROJECT_ID/topics/TOPIC_ID. Полное имя понадобится вам на следующем шаге.

4. Предоставьте доступ для публикации сообщений издатель-подписчик в вашей теме:

   1. На странице темы перейдите на боковую панель и откройте вкладку Разрешения.
   2. Нажмите Add Principal (Добавить субъекта).
   3. В поле Добавление субъектов добавьте сервисный аккаунт для приложения Google Workspace, которое отправляет события в вашу подписку:
      1. Для событий Chat:
         • Для приложений Chat (созданных как дополнения Google Workspace, расширяющие возможности Chat) используйте адрес электронной почты сервисного аккаунта на странице конфигурации Chat API. Подробнее о том, как создать приложение Google Chat, использующее Pub/Sub…
         • Для приложений Chat, которые не являются дополнениями Google Workspace, используйте chat-api-push@system.gserviceaccount.com. Подробнее о том, как создать приложение Google Chat, использующее издатель-подписчик…
      2. Для событий Диска: drive-api-event-push@system.gserviceaccount.com.
      3. Для мероприятий Meet: meet-api-event-push@system.gserviceaccount.com.
   4. В меню Назначить роли выберите Pub/Sub Publisher.
   5. Нажмите Сохранить. Обновление разрешений для темы может занять несколько минут.

gcloud

1. В облачном проекте создайте тему, выполнив следующую команду:

   gcloud pubsub topics create TOPIC_ID

   Замените TOPIC_ID уникальным идентификатором темы, например workspace-events-topic.

   В выходных данных будет указано полное название темы в формате projects/PROJECT_ID/topics/TOPIC_ID. Запишите название и убедитесь, что значение атрибута PROJECT_ID – это идентификатор облачного проекта для вашего приложения. Название темы понадобится вам на следующем шаге и при создании подписки Google Workspace.

2. Чтобы предоставить доступ на публикацию сообщений в теме:

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

   Замените следующее:

   • TOPIC_NAME: полное название темы, которое было получено на предыдущем шаге. Формат: projects/PROJECT_ID/topics/TOPIC_ID.

   • GOOGLE_WORKSPACE_APPLICATION – приложение Google Workspace, которое должно отправлять события в вашу подписку:

     • Чтобы получать события из Chat, используйте один из следующих сервисных аккаунтов:
       • Для приложений Chat (созданных как дополнения Google Workspace, расширяющие возможности Chat) используйте адрес электронной почты сервисного аккаунта на странице конфигурации Chat API. Подробнее о том, как создать приложение Google Chat, использующее издатель-подписчик…
       • Для приложений Chat, которые не являются дополнениями, используйте chat-api-push@system.gserviceaccount.com. Подробнее о том, как создать приложение Google Chat, использующее издатель-подписчик…
     • Чтобы получать события с Диска, используйте drive-api-event-push@system.gserviceaccount.com.
     • Чтобы получать события из Meet, используйте meet-api-event-push@system.gserviceaccount.com.

   Обновление разрешений для темы может занять несколько минут.

3. Создайте подписку Pub/Sub для темы:

    gcloud pubsub subscriptions create SUBSCRIPTION_NAME --topic=TOPIC_NAME

   Замените следующее:

   • SUBSCRIPTION_NAME – название подписки, например workspace-events-subscription.
   • TOPIC_NAME – название темы, созданной на предыдущем шаге.

Apps Script

1. В проекте Apps Script создайте новый файл скрипта с названием createSubscription и добавьте следующий код:

   function createSubscription() {
     // The Google Workspace resource to monitor for events.
     const targetResource = 'TARGET_RESOURCE';
   
     // The types of events to receive.
     const eventTypes = [EVENT_TYPES];
   
     // The endpoint to deliver events to, such as a Google Cloud Pub/Sub topic.
     const pubsubTopic = 'TOPIC_NAME';
   
     // Whether to include resource data or not.
     const resourceData = RESOURCE_DATA;
   
     // Call the Workspace Events API using the advanced service.
     const response = WorkspaceEvents.Subscriptions.create({
       targetResource: targetResource,
       eventTypes: eventTypes,
       notificationEndpoint: {
         pubsubTopic: pubsubTopic,
       },
       payloadOptions: {
         includeResource: resourceData
       }
     });
     console.log(response);
   }
   

   Замените следующее:

   • TARGET_RESOURCE – ресурс Google Workspace, на который вы подписываетесь, в формате полного имени ресурса. Например, чтобы подписаться на чат-группу с идентификатором AAAABBBB, используйте //chat.googleapis.com/spaces/AAAABBBB.
   • EVENT_TYPES – один или несколько типов событий, на которые вы хотите подписаться в целевом ресурсе. Формат: массив строк, например 'google.workspace.chat.message.v1.created'.
   • TOPIC_NAME – полное название темы издатель-подписчик, созданной в вашем облачном проекте. Формат: projects/PROJECT_ID/topics/TOPIC_ID.

   • RESOURCE_DATA – логическое значение, указывающее, включены ли в полезную нагрузку данные ресурса:

     • True – включает все данные ресурса. Чтобы ограничить количество полей, добавьте поле fieldMask и укажите хотя бы одно поле для измененного ресурса. Только подписки на ресурсы Chat поддерживают включение данных ресурсов.
     • False: данные о ресурсах исключены.

2. Чтобы создать подписку Google Workspace, запустите функцию createSubscription в проекте Apps Script.

Python

1. В рабочем каталоге создайте файл с названием create_subscription.py и добавьте в него следующий код:

   """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('credentials.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)
   

   Замените следующее:

   • SCOPES – одна или несколько областей действия OAuth, поддерживающих каждый тип событий для подписки. Форматируется как массив строк. Чтобы указать несколько областей, перечислите их через запятую. Пример: 'https://www.googleapis.com/auth/chat.spaces.readonly', 'https://www.googleapis.com/auth/chat.memberships.readonly'.
   • TARGET_RESOURCE – ресурс Google Workspace, на который вы подписываетесь, в формате полного имени ресурса. Например, чтобы подписаться на чат-группу с идентификатором AAAABBBB, используйте //chat.googleapis.com/spaces/AAAABBBB.
   • EVENT_TYPES – один или несколько типов событий, на которые вы хотите подписаться в целевом ресурсе. Формат: массив строк, например 'google.workspace.chat.message.v1.created'.
   • TOPIC_NAME – полное название темы издатель-подписчик, созданной в вашем облачном проекте. Формат: projects/PROJECT_ID/topics/TOPIC_ID.

   • RESOURCE_DATA – логическое значение, указывающее, включены ли в полезную нагрузку данные ресурса:

     • True – включает все данные ресурса. Чтобы ограничить количество полей, добавьте поле fieldMask и укажите хотя бы одно поле для измененного ресурса. Только подписки на ресурсы Chat поддерживают включение данных ресурсов.
     • False: данные о ресурсах исключены.

2. Чтобы создать подписку Google Workspace, выполните в терминале следующие команды:

   python3 create_subscription.py

Google API Console

1. Запускать один или несколько типов событий в целевом ресурсе подписки Google Workspace. Например, если вы подписались на новые сообщения в чат-группе Chat, опубликуйте сообщение в этой группе.

2. В Google API Console перейдите на страницу Pub/Sub:

   Перейти к Pub/Sub

   Убедитесь, что выбран облачный проект для вашего приложения.

3. В меню Pub/Sub нажмите Подписки.

4. В таблице найдите подписку Pub/Sub для своей темы и нажмите на ее название.

5. Откройте вкладку Сообщения.

6. Нажмите Получить. На создание сообщения Pub/Sub на основе события может уйти несколько минут.

gcloud

1. Запускать один или несколько типов событий в целевом ресурсе подписки Google Workspace. Например, если вы подписались на новые сообщения в чат-группе Chat, опубликуйте сообщение в этой группе.

2. Выполните следующую команду:

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

   Замените следующее:

   • PUBSUB_SUBSCRIPTION_NAME – полное название подписки издатель-подписчик в формате projects/PROJECT_ID/subscriptions/SUBSCRIPTION_ID.
   • MESSAGE_COUNT – максимальное количество сообщений издатель-подписчик, которые вы хотите получить.

   На создание сообщения Pub/Sub на основе события может уйти несколько минут.

Python

  """Create subscription."""

  from google.oauth2 import service_account
  from apiclient.discovery import build

  # Specify required scopes.
  SCOPES = ['https://www.googleapis.com/auth/chat.app.messages.readonly']

  # Specify service account details.
  CREDENTIALS = (
      service_account.Credentials.from_service_account_file('credentials.json')
      .with_scopes(SCOPES)
  )

  # The Google Workspace resource to monitor for events.
  TARGET_RESOURCE = '//chat.googleapis.com/spaces/SPACE_ID'

  # The types of events to receive.
  EVENT_TYPES = [
                  'google.workspace.chat.message.v1.created',
                  'google.workspace.chat.message.v1.updated',
                  'google.workspace.chat.message.v1.deleted',
                ]

  # 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)

Python

"""Create a customer subscription."""

from google.oauth2 import service_account
from apiclient.discovery import build

# Specify required scopes.
# Replace with the scopes needed for the event types you want to receive.
SCOPES = ['https://www.googleapis.com/auth/chat.app.all.messages.readonly']

# Specify service account details.
CREDENTIALS = (
    service_account.Credentials.from_service_account_file('credentials.json')
    .with_scopes(SCOPES)
)

# Monitor all events for the Google Workspace organization.
TARGET_RESOURCE = '//admin.googleapis.com/customers/CUSTOMER_ID'

# The types of events to receive.
EVENT_TYPES = [
    'google.workspace.chat.message.v1.created',
    'google.workspace.chat.message.v1.updated',
    'google.workspace.chat.message.v1.deleted',
]

# The endpoint to deliver events to.
TOPIC = 'TOPIC_NAME'

# Call the Workspace Events API.
# Note: Use the v1beta endpoint for Developer Preview features.
service = build(
    'workspaceevents',
    'v1beta',
    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)