Создайте подписку на Google Workspace

На этой странице объясняется, как использовать API событий Google Workspace для создания подписки на ресурс Google Workspace. Подписка на Google Workspace позволяет вашему приложению получать информацию о событиях Google Workspace , которые представляют собой изменения в ресурсе Google Workspace. Чтобы узнать, какие ресурсы и типы событий поддерживает Google Workspace Events API, см. обзор Google Workspace Events API .

На этой странице представлены следующие шаги по созданию подписки на Google Workspace:

  1. Настройте свою среду.
  2. Создайте тему Google Cloud Pub/Sub и подпишитесь на нее. Вы используете эту тему как конечную точку для получения событий Google Workspace.
  3. Вызовите метод create() API Google Workspace Events для ресурса Subscription .
  4. Проверьте свою подписку на Google Workspace, чтобы убедиться, что ваша тема Pub/Sub получает события, на которые вы подписаны.
  5. При необходимости настройте способ отправки событий в конечную точку вашего приложения, чтобы ваше приложение могло обрабатывать событие и, при необходимости, предпринимать действия.

Предварительные условия

Скрипт приложений

  • Чтобы использовать команды Google Cloud CLI в этом руководстве:
    1. Установите Google Cloud CLI .
    2. Чтобы инициализировать интерфейс командной строки gcloud , запустите следующий код:
      3.   gcloud init
  • Целевой ресурс для подписки:
    • Чтобы подписаться на пространство Google Chat, то есть пространство Chat, участником которого является прошедший проверку подлинности пользователь. Пользователь должен быть участником пространства через свою учетную запись Google Workspace или Google (пользователи, являющиеся участниками пространства через группу Google, не поддерживаются).
    • Чтобы подписаться на пространство для собраний Google Meet — пространство для собраний, владельцем которого является прошедший проверку подлинности пользователь. Чтобы создать пространство, в документации Google Meet см. раздел Работа с пространствами для собраний .
    • Чтобы подписаться на пользователя Google Meet, необходимо использовать идентификатор user Cloud Identity API.
  • Проект Google Cloud с включенной оплатой. Для подписки на Chat вам также необходимо включить Chat API в своем облачном проекте и настроить поля «Имя приложения» , «URL-адрес аватара» и «Описание» . Подробную информацию см. в разделе Создание приложения Google Chat .
  • Требуется аутентификация пользователя с помощью экрана согласия OAuth, настроенного для приложения. При настройке экрана согласия необходимо указать область для поддержки каждого типа событий для подписки. Чтобы настроить экран согласия и определить необходимые области, см. Выбор областей .
  • Проект скрипта приложений:
    • Используйте свой проект Google Cloud вместо проекта по умолчанию, автоматически созданного Apps Script.
    • Для любых областей, которые вы добавили для настройки экрана согласия OAuth, вам также необходимо добавить области в файл appsscript.json в проекте Apps Script. Например:
      • "oauthScopes": [
  "https://www.googleapis.com/auth/chat.messages.readonly"
]
    • Включите расширенную службу Google Workspace Events .

Питон

  • Python 3.6 или выше
  • Инструмент управления пакетами pip
  • Новейшие клиентские библиотеки Google для Python. Чтобы установить или обновить их, выполните следующую команду в интерфейсе командной строки: 
      pip3 install --upgrade google-api-python-client google-auth-oauthlib
  • Чтобы использовать команды Google Cloud CLI в этом руководстве:
    1. Установите Google Cloud CLI .
    2. Чтобы инициализировать интерфейс командной строки gcloud , запустите следующий код:
      3.   gcloud init
  • Целевой ресурс для подписки:
    • Чтобы подписаться на пространство Google Chat, то есть пространство Chat, участником которого является прошедший проверку подлинности пользователь. Пользователь должен быть участником пространства через свою учетную запись Google Workspace или Google (пользователи, являющиеся участниками пространства через группу Google, не поддерживаются).
    • Чтобы подписаться на пространство для собраний Google Meet — пространство для собраний, владельцем которого является прошедший проверку подлинности пользователь. Чтобы создать пространство, в документации Google Meet см. раздел Работа с пространствами для собраний .
    • Чтобы подписаться на пользователя Google Meet, необходимо использовать идентификатор user Cloud Identity API.
  • Проект Google Cloud с включенной оплатой. Для подписки на Chat вам также необходимо включить Chat API в своем облачном проекте и настроить поля «Имя приложения» , «URL-адрес аватара» и «Описание» . Подробную информацию см. в разделе Создание приложения Google Chat .
  • Требуется аутентификация пользователя с помощью экрана согласия OAuth, настроенного для приложения. При настройке экрана согласия необходимо указать область для поддержки каждого типа событий для подписки. Чтобы настроить экран согласия и определить необходимые области, см. Выбор областей .

Настройте свою среду

В следующем разделе объясняется, как настроить среду перед созданием подписки на Google Workspace.

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

Прежде чем использовать API Google, вам необходимо включить их в проекте Google Cloud. Вы можете включить один или несколько API в одном проекте Google Cloud.

Консоль Google Cloud

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

Включите API

gcloud

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

    gcloud auth login

  2. Настройте свой проект как облачный проект для вашего приложения:

    gcloud config set project PROJECT_ID

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

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

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

Создайте учетные данные идентификатора клиента OAuth.

Выберите тип приложения для получения конкретных инструкций о том, как создать идентификатор клиента OAuth:

веб приложение

  1. В консоли Google Cloud выберите > API и службы > Учетные данные .

    Перейти к учетным данным

  2. Нажмите «Создать учетные данные» > «Идентификатор клиента OAuth» .
  3. Щелкните Тип приложения > Веб-приложение .
  4. В поле Имя введите имя учетных данных. Это имя отображается только в консоли Google Cloud.
  5. Добавьте авторизованные URI, связанные с вашим приложением:
    • Клиентские приложения (JavaScript) . В разделе «Авторизованные источники JavaScript» нажмите « Добавить URI» . Затем введите URI, который будет использоваться для запросов браузера. Это определяет домены, из которых ваше приложение может отправлять запросы API на сервер OAuth 2.0.
    • Серверные приложения (Java, Python и т. д.) – в разделе «Авторизованные URI перенаправления» нажмите « Добавить URI» . Затем введите URI конечной точки, на который сервер OAuth 2.0 может отправлять ответы.
  6. Нажмите Создать . Появится экран создания клиента OAuth, показывающий ваш новый идентификатор клиента и секрет клиента.

    Обратите внимание на идентификатор клиента. Секреты клиента не используются для веб-приложений.

  7. Нажмите ОК . Вновь созданные учетные данные появятся в разделе «Идентификаторы клиентов OAuth 2.0» .

Андроид

  1. В консоли Google Cloud выберите > API и службы > Учетные данные .

    Перейти к учетным данным

  2. Нажмите «Создать учетные данные» > «Идентификатор клиента OAuth» .
  3. Нажмите Тип приложения > Android .
  4. В поле «Имя» введите имя учетных данных. Это имя отображается только в консоли Google Cloud.
  5. В поле «Имя пакета» введите имя пакета из файла AndroidManifest.xml .
  6. В поле «Отпечаток сертификата SHA-1» введите сгенерированный отпечаток сертификата SHA-1 .
  7. Нажмите Создать . Появится экран создания клиента OAuth, на котором будет показан ваш новый идентификатор клиента.
  8. Нажмите ОК . Вновь созданные учетные данные появятся в разделе «Идентификаторы клиентов OAuth 2.0».

iOS

  1. В консоли Google Cloud выберите > API и службы > Учетные данные .

    Перейти к учетным данным

  2. Нажмите «Создать учетные данные» > «Идентификатор клиента OAuth» .
  3. Нажмите Тип приложения > iOS .
  4. В поле «Имя» введите имя учетных данных. Это имя отображается только в консоли Google Cloud.
  5. В поле «Идентификатор пакета» введите идентификатор пакета, указанный в файле Info.plist приложения.
  6. Необязательно: если ваше приложение появилось в Apple App Store, введите идентификатор App Store.
  7. Необязательно: в поле «Идентификатор команды» введите уникальную строку из 10 символов, созданную Apple и назначенную вашей команде.
  8. Нажмите Создать . Появится экран создания клиента OAuth, показывающий ваш новый идентификатор клиента и секрет клиента.
  9. Нажмите ОК . Вновь созданные учетные данные появятся в разделе «Идентификаторы клиентов OAuth 2.0».

Приложение Chrome

  1. В консоли Google Cloud выберите > API и службы > Учетные данные .

    Перейти к учетным данным

  2. Нажмите «Создать учетные данные» > «Идентификатор клиента OAuth» .
  3. Нажмите Тип приложения > Приложение Chrome .
  4. В поле «Имя» введите имя учетных данных. Это имя отображается только в консоли Google Cloud.
  5. В поле «Идентификатор приложения» введите уникальную 32-значную строку идентификатора вашего приложения. Это значение идентификатора можно найти в URL-адресе Интернет-магазина Chrome вашего приложения и на панели инструментов разработчика Интернет-магазина Chrome .
  6. Нажмите Создать . Появится экран создания клиента OAuth, показывающий ваш новый идентификатор клиента и секрет клиента.
  7. Нажмите ОК . Вновь созданные учетные данные появятся в разделе «Идентификаторы клиентов OAuth 2.0».

Настольное приложение

  1. В консоли Google Cloud выберите > API и службы > Учетные данные .

    Перейти к учетным данным

  2. Нажмите «Создать учетные данные» > «Идентификатор клиента OAuth» .
  3. Нажмите Тип приложения > Приложение для ПК .
  4. В поле Имя введите имя учетных данных. Это имя отображается только в консоли Google Cloud.
  5. Нажмите Создать . Появится экран создания клиента OAuth, показывающий ваш новый идентификатор клиента и секрет клиента.
  6. Нажмите ОК . Вновь созданные учетные данные появятся в разделе «Идентификаторы клиентов OAuth 2.0».

Телевизоры и ограниченные устройства ввода

  1. В консоли Google Cloud выберите > API и службы > Учетные данные .

    Перейти к учетным данным

  2. Нажмите «Создать учетные данные» > «Идентификатор клиента OAuth» .
  3. Нажмите «Тип приложения» > «Телевизоры и устройства с ограниченным вводом» .
  4. В поле «Имя» введите имя учетных данных. Это имя отображается только в консоли Google Cloud.
  5. Нажмите Создать . Появится экран создания клиента OAuth, показывающий ваш новый идентификатор клиента и секрет клиента.
  6. Нажмите ОК . Вновь созданные учетные данные появятся в разделе «Идентификаторы клиентов OAuth 2.0».

Универсальная платформа Windows (UWP)

  1. В консоли Google Cloud выберите > API и службы > Учетные данные .

    Перейти к учетным данным

  2. Нажмите «Создать учетные данные» > «Идентификатор клиента OAuth» .
  3. Щелкните Тип приложения > Универсальная платформа Windows (UWP) .
  4. В поле «Имя» введите имя учетных данных. Это имя отображается только в консоли Google Cloud.
  5. В поле «Идентификатор магазина» введите уникальное 12-значное значение идентификатора Microsoft Store вашего приложения. Этот идентификатор можно найти в URL-адресе вашего приложения в Microsoft Store и в Центре партнеров .
  6. Нажмите Создать . Появится экран создания клиента OAuth, показывающий ваш новый идентификатор клиента и секрет клиента.
  7. Нажмите ОК . Вновь созданные учетные данные появятся в разделе «Идентификаторы клиентов OAuth 2.0».

Загрузите JSON-файл секретного клиента.

Секретный файл клиента — это JSON-представление учетных данных идентификатора клиента OAuth, на которое ваше приложение может ссылаться при предоставлении учетных данных.

  1. В консоли Google Cloud выберите > API и службы > Учетные данные .

    Перейти к учетным данным

  2. В разделе «Идентификаторы клиентов OAuth 2.0» щелкните созданный вами идентификатор клиента.

  3. Нажмите «Загрузить JSON» .

  4. Сохраните файл как client_secrets.json .

Создайте тему Pub/Sub и подпишитесь на нее.

В этом разделе вы создаете тему Pub/Sub и подписываетесь на эту тему. Ваша тема Pub/Sub служит конечной точкой уведомлений, откуда ваша подписка на Google Workspace получает события.

Дополнительные сведения о создании тем Pub/Sub и управлении ими см. в документации Pub/Sub .

Чтобы создать тему Pub/Sub и подписаться на нее:

Консоль Google Cloud

  1. В консоли Google Cloud перейдите на страницу Pub/Sub:

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

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

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

    1. Введите название своей темы, например workspace-events-topic .
    2. Оставьте выбранным параметр «Добавить подписку по умолчанию» . Pub/Sub называет эту подписку по умолчанию аналогично названию вашей темы, например workspace-events-topic-sub .
    3. Необязательно: обновите или настройте дополнительные свойства для вашей темы.

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

  4. Предоставьте доступ к публикации сообщений Pub/Sub в вашей теме:

    1. На странице вашей темы перейдите на боковую панель и откройте вкладку «Разрешения» .
    2. Нажмите «Добавить принципала» .
    3. В поле «Добавить участников» добавьте сервисный аккаунт для приложения Google Workspace, который доставляет события в вашу подписку:
      1. Для событий чата: chat-api-push@system.gserviceaccount.com .
      2. Для мероприятий 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-api-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 : название вашей темы, которую вы создали на предыдущем шаге.

Создайте подписку на Google Workspace

В этом разделе вы используете метод subscriptions.create() API Google Workspace Events для создания ресурса Subscription . Вы указываете следующие поля:

  • targetResource : ресурс Google Workspace для отслеживания событий, например чата.
  • eventTypes : массив из одного или нескольких типов событий, которые вы хотите получать о ресурсе. Например, если вашему приложению нужно знать только о новых сообщениях, опубликованных в пространстве чата, ваше приложение может просто подписаться на события о созданных сообщениях.
  • notificationEndpoint : конечная точка уведомлений, в которой ваша подписка на Google Workspace доставляет события. Вы используете тему Pub/Sub, созданную в предыдущем разделе.
  • payloadOptions : параметры, позволяющие указать, сколько данных о ресурсах следует включить в полезные данные события. Эта конфигурация влияет на срок действия вашей подписки. Дополнительную информацию см. в разделе Данные о событиях .

Чтобы создать подписку на Google Workspace:

Скрипт приложений

  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 , на который вы подписываетесь, в формате полного имени ресурса. Например, чтобы подписаться на пространство Google Chat с идентификатором пространства AAAABBBB , используйте //chat.googleapis.com/spaces/AAAABBBB .
    • EVENT_TYPES : один или несколько типов событий , на которые вы хотите подписаться в целевом ресурсе. Отформатируйте его как массив строк, например 'google.workspace.chat.message.v1.created' .
    • TOPIC_NAME : полное название темы Pub/Sub, которую вы создали в своем облачном проекте. В формате projects/ PROJECT_ID /topics/ TOPIC_ID .

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

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

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

Питон

  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('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)

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

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

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

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

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

    python3 create_subscription.py

API событий Google Workspace возвращает завершенную длительную операцию , содержащую экземпляр созданного вами ресурса Subscription .

Проверьте свою подписку на Google Workspace

Чтобы проверить, что вы получаете события Google Workspace, вы можете инициировать событие и переместить сообщения в подписку Pub/Sub.

Чтобы проверить подписку на Google Workspace:

Консоль Google Cloud

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

  2. В консоли Google Cloud перейдите на страницу Pub/Sub:

    Перейти в паб/саб

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

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

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

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

  6. Нажмите «Потянуть» . Создание сообщения Pub/Sub может занять до нескольких минут.

gcloud

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

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

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

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

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

    Создание сообщения Pub/Sub может занять до нескольких минут.

Для каждого инициированного вами события Google Workspace в вашу подписку Pub/Sub доставляется сообщение, содержащее это событие. Подробную информацию см. в разделе Получение событий в виде сообщений Google Cloud Pub/Sub .

Настройте способ получения событий вашим приложением

Созданная вами подписка Pub/Sub основана на запросе. После проверки вашей подписки Pub/Sub вы можете обновить тип доставки, чтобы изменить способ получения событий вашим приложением. Например, вы можете настроить подписку Pub/Sub на тип принудительной доставки, чтобы ваше приложение могло получать события непосредственно в конечную точку приложения.

Дополнительные сведения о настройке подписки Pub/Sub см. в документации Pub/Sub .