На этой странице объясняется, как использовать API событий Google Workspace для создания подписки на ресурс Google Workspace. Подписка на Google Workspace позволяет вашему приложению получать информацию о событиях Google Workspace , которые представляют изменения в ресурсе Google Workspace. Чтобы узнать, какие ресурсы и типы событий поддерживает API событий Google Workspace, см. обзор API событий Google Workspace .
На этой странице представлены следующие шаги по созданию подписки на Google Workspace:
- Настройте свою среду.
- Создайте тему Google Cloud Pub/Sub и подпишитесь на неё. Эта тема используется в качестве конечной точки для получения событий Google Workspace.
- Вызовите метод
create
API событий Google Workspace для ресурсаSubscription
. - Проверьте подписку на Google Workspace, чтобы убедиться, что ваша тема Pub/Sub получает события, на которые вы подписаны.
- При желании вы можете настроить отправку событий в конечную точку вашего приложения, чтобы приложение могло обработать событие и при необходимости выполнить действие.
Предпосылки
Скрипт приложений
- Чтобы использовать команды Google Cloud CLI в этом руководстве:
- Установите Google Cloud CLI .
- Чтобы инициализировать
gcloud
CLI, выполните следующий код:
gcloud init
- Проект Google Cloud с включённым биллингом. Для подписок на Chat необходимо также включить Chat API в вашем проекте Cloud и настроить поля «Название приложения» , «URL аватара» и «Описание» . Подробнее см. в статье «Создание приложения Google Chat» .
- Требуется аутентификация пользователя с помощью экрана согласия OAuth, настроенного для приложения. При настройке экрана согласия необходимо указать область действия для поддержки каждого типа событий подписки. Чтобы настроить экран согласия и определить необходимые области действия, см. раздел Выбор областей действия .
- Проект Apps Script:
- Используйте свой проект Google Cloud вместо проекта по умолчанию, созданного автоматически Apps Script.
- Для всех областей действия, добавленных для настройки экрана согласия OAuth, необходимо также добавить их в файл
appsscript.json
в вашем проекте Apps Script. Например: - Включите расширенную службу
Google Workspace Events
.
"oauthScopes": [ "https://www.googleapis.com/auth/chat.messages.readonly" ]
Питон
- Python 3.6 или выше
- Инструмент управления пакетами pip
- Последние клиентские библиотеки Google для Python. Чтобы установить или обновить их, выполните следующую команду в командной строке:
pip3 install --upgrade google-api-python-client google-auth-oauthlib
- Чтобы использовать команды Google Cloud CLI в этом руководстве:
- Установите Google Cloud CLI .
- Чтобы инициализировать
gcloud
CLI, выполните следующий код:
gcloud init
- Проект Google Cloud с включённым биллингом. Для подписок на Chat необходимо также включить Chat API в вашем проекте Cloud и настроить поля «Название приложения» , «URL аватара» и «Описание» . Подробнее см. в статье «Создание приложения Google Chat» .
- Требуется аутентификация пользователя с помощью экрана согласия OAuth, настроенного для приложения. При настройке экрана согласия необходимо указать область действия для поддержки каждого типа событий подписки. Чтобы настроить экран согласия и определить необходимые области действия, см. раздел Выбор областей действия .
Настройте свою среду
В следующем разделе объясняется, как настроить среду перед созданием подписки на Google Workspace.
Включите API событий Google Workspace и API Google Cloud Pub/Sub
Перед использованием API Google необходимо включить их в проекте Google Cloud. Вы можете включить один или несколько API в одном проекте Google Cloud.Консоль Google Cloud
В консоли Google Cloud откройте проект Google Cloud для своего приложения и включите API событий Google Workspace и API Pub/Sub:
gcloud
В рабочем каталоге войдите в свою учетную запись Google:
gcloud auth login
Настройте свой проект как облачный проект для вашего приложения:
gcloud config set project PROJECT_ID
Замените
PROJECT_ID
на идентификатор облачного проекта для вашего приложения.Включите API событий Google Workspace и API Google Cloud Pub/Sub:
gcloud services enable pubsub.googleapis.com workspaceevents.googleapis.com
Создайте учетные данные идентификатора клиента OAuth
Выберите тип приложения для получения конкретных инструкций по созданию идентификатора клиента OAuth:
Веб-приложение
- В консоли Google Cloud перейдите в > > Клиенты .
- Нажмите «Создать клиента» .
- Нажмите Тип приложения > Веб-приложение .
- В поле «Имя» введите имя учётной записи. Оно отображается только в консоли Google Cloud.
- Добавьте авторизованные URI, связанные с вашим приложением:
- Клиентские приложения (JavaScript) – в разделе «Авторизованные источники JavaScript» нажмите « Добавить URI» . Затем введите URI для использования в запросах браузера. Он определяет домены, с которых ваше приложение может отправлять запросы API на сервер OAuth 2.0.
- Серверные приложения (Java, Python и другие) — в разделе «Авторизованные URI перенаправления» нажмите « Добавить URI» . Затем введите URI конечной точки, на которую сервер OAuth 2.0 может отправлять ответы.
- Нажмите «Создать» .
Новые учетные данные появятся в разделе «Идентификаторы клиентов OAuth 2.0» .
Обратите внимание на идентификатор клиента. Секреты клиента не используются в веб-приложениях.
Андроид
- В консоли Google Cloud перейдите в > > Клиенты .
- Нажмите «Создать клиента» .
- Нажмите Тип приложения > Android .
- В поле «Имя» введите имя учётной записи. Оно отображается только в консоли Google Cloud.
- В поле «Имя пакета» введите имя пакета из файла
AndroidManifest.xml
. - В поле «Отпечаток сертификата SHA-1» введите сгенерированный отпечаток сертификата SHA-1 .
- Нажмите «Создать» .
Новые учетные данные появятся в разделе «Идентификаторы клиентов OAuth 2.0».
iOS
- В консоли Google Cloud перейдите в > > Клиенты .
- Нажмите «Создать клиента» .
- Нажмите Тип приложения > iOS .
- В поле «Имя» введите имя учётной записи. Оно отображается только в консоли Google Cloud.
- В поле «Идентификатор пакета» введите идентификатор пакета, указанный в файле
Info.plist
приложения. - Необязательно: если ваше приложение представлено в Apple App Store, введите идентификатор App Store.
- Необязательно: в поле «Идентификатор команды» введите уникальную строку из 10 символов, сгенерированную Apple и назначенную вашей команде.
- Нажмите «Создать» .
Новые учетные данные появятся в разделе «Идентификаторы клиентов OAuth 2.0».
приложение Chrome
- В консоли Google Cloud перейдите в > > Клиенты .
- Нажмите «Создать клиента» .
- Нажмите Тип приложения > Расширение Chrome .
- В поле «Имя» введите имя учётной записи. Оно отображается только в консоли Google Cloud.
- В поле «Идентификатор элемента» введите уникальный 32-символьный идентификатор вашего приложения. Этот идентификатор можно найти в URL-адресе вашего приложения в интернет-магазине Chrome и на панели разработчика интернет-магазина Chrome .
- Нажмите «Создать» .
Новые учетные данные появятся в разделе «Идентификаторы клиентов OAuth 2.0».
Приложение для ПК
- В консоли Google Cloud перейдите в > > Клиенты .
- Нажмите «Создать клиента» .
- Нажмите Тип приложения > Приложение для ПК .
- В поле «Имя» введите имя учётной записи. Оно отображается только в консоли Google Cloud.
- Нажмите «Создать» .
Новые учетные данные появятся в разделе «Идентификаторы клиентов OAuth 2.0».
Телевизоры и устройства ввода с ограниченным доступом
- В консоли Google Cloud перейдите в > > Клиенты .
- Нажмите «Создать клиента» .
- Нажмите Тип приложения > Телевизоры и устройства с ограниченными возможностями ввода .
- В поле «Имя» введите имя учётной записи. Оно отображается только в консоли Google Cloud.
- Нажмите «Создать» .
Новые учетные данные появятся в разделе «Идентификаторы клиентов OAuth 2.0».
Универсальная платформа Windows (UWP)
- В консоли Google Cloud перейдите в > > Клиенты .
- Нажмите «Создать клиента» .
- Нажмите Тип приложения > Универсальная платформа Windows (UWP) .
- В поле «Имя» введите имя учётной записи. Оно отображается только в консоли Google Cloud.
- В поле «Идентификатор магазина» введите уникальный 12-значный идентификатор вашего приложения в Microsoft Store. Этот идентификатор можно найти в URL-адресе вашего приложения в Microsoft Store и в Центре партнёров .
- Нажмите «Создать» .
Новые учетные данные появятся в разделе «Идентификаторы клиентов OAuth 2.0».
Загрузите JSON-файл секретного ключа клиента
Файл секретного ключа клиента — это JSON-представление учетных данных идентификатора клиента OAuth, на которые ваше приложение может ссылаться при предоставлении учетных данных.
В консоли Google Cloud перейдите в > API и службы > Учетные данные .
В разделе «Идентификаторы клиентов OAuth 2.0» нажмите на созданный вами идентификатор клиента.
Нажмите «Загрузить JSON» .
Сохраните файл как
credentials.json
.
Создайте и подпишитесь на тему Pub/Sub
В этом разделе вы создаёте тему Pub/Sub и подписываетесь на неё. Тема Pub/Sub служит конечной точкой уведомлений, куда ваша подписка на Google Workspace получает события.
Дополнительную информацию о создании и управлении темами Pub/Sub см. в документации Pub/Sub .
Чтобы создать тему Pub/Sub и подписаться на нее:
Консоль Google Cloud
В консоли Google Cloud перейдите на страницу Pub/Sub:
Перейти к Google Cloud Pub/Sub
Убедитесь, что для вашего приложения выбран проект Cloud.
Нажмите
Создать тему и выполните следующие действия:- Введите название темы, например,
workspace-events-topic
. - Оставьте выбранным «Добавить подписку по умолчанию» . Pub/Sub присваивает этой подписке по умолчанию имя, похожее на название вашей темы, например,
workspace-events-topic-sub
. - Необязательно: обновите или настройте дополнительные свойства для вашей темы.
- Введите название темы, например,
Нажмите «Создать» . Полное название темы будет иметь формат
projects/ PROJECT_ID /topics/ TOPIC_ID
. Это полное название понадобится вам на следующем этапе.Предоставьте доступ для публикации сообщений Pub/Sub в вашей теме:
- На странице вашей темы перейдите на боковую панель и откройте вкладку «Разрешения» .
- Нажмите Добавить принципала .
- В поле Добавить субъекты добавьте учетную запись службы для приложения Google Workspace, которое доставляет события в вашу подписку:
- Для событий чата,
chat-api-push@system.gserviceaccount.com
. - Предварительная версия для разработчиков : для событий Drive —
drive-api-event-push@system.gserviceaccount.com
. - Для мероприятий Meet,
meet-api-event-push@system.gserviceaccount.com
.
- Для событий чата,
- В меню «Назначить роли» выберите
Pub/Sub Publisher
. - Нажмите «Сохранить» . Обновление разрешений для вашей темы может занять несколько минут.
gcloud
В своем облачном проекте создайте тему, выполнив следующую команду:
gcloud pubsub topics create TOPIC_ID
Замените
TOPIC_ID
уникальным идентификатором вашей темы, например,workspace-events-topic
.В выводе отображается полное название темы в формате
projects/ PROJECT_ID /topics/ TOPIC_ID
. Запишите название и убедитесь, что значение PROJECT_ID соответствует идентификатору облачного проекта вашего приложения. Название темы понадобится вам на следующем шаге, а также для создания подписки на Google Workspace позже.Предоставьте доступ для публикации сообщений в вашей теме:
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
. - Предварительная версия для разработчиков: Чтобы получать события от Drive, используйте
drive-api-event-push@system.gserviceaccount.com
. - Для получения событий от Meet используйте
meet-api-event-push@system.gserviceaccount.com
.
- Для получения событий из чата используйте
Обновление разрешений для вашей темы может занять несколько минут.
-
Создайте подписку Pub/Sub на тему:
gcloud pubsub subscriptions create SUBSCRIPTION_NAME --topic=TOPIC_NAME
Заменить следующее:
-
SUBSCRIPTION_NAME
: Имя вашей подписки, например,workspace-events-subscription
. -
TOPIC_NAME
: Название темы, созданной на предыдущем шаге.
-
Подпишитесь на ресурс Google Workspace
В этом разделе вы подписываетесь на ресурс Google Workspace, события которого вы хотите отслеживать.
Выберите и определите целевой ресурс
В подписке на Google Workspace целевым ресурсом является ресурс Google Workspace, события которого отслеживаются. Целевой ресурс указан в поле targetResource
подписки, отформатированном с использованием полного имени ресурса. Например, для подписки, отслеживающей чат-группу Google ( spaces/AAAABBBBBBB
), значение targetResource
будет: //chat.googleapis.com/spaces/AAAABBBBBBB
.
Прежде чем создавать подписку, изучите следующие разделы, как определить и отформатировать целевой ресурс.
Определите целевой ресурс для чата
Целевой ресурс | Формат | Ограничения |
---|---|---|
Космос | Где SPACE — это идентификатор в имени ресурса | Пользователь чата, который авторизует подписку, должен быть участником пространства через свою учетную запись Google Workspace или Google. |
Все места для пользователя | | Подписка получает события только для тех пространств, в которых пользователь является участником через свое Google Workspace или учетную запись Google. |
Пользователь | Где USER — это идентификатор в имени ресурса | Подписка получает только события о пользователе, который её авторизовал. Пользователь не может авторизовать подписку от имени других пользователей. |
Определите целевой ресурс для Диска
Целевой ресурс | Формат | Ограничения (если применимо) |
---|---|---|
Файл | //googleapis.com/drive/v3/files/ FILE Где FILE — идентификатор в имени ресурса | Пользователь, который авторизует подписку, должен иметь разрешение на файл в рамках подписки, относящееся к событию подписки. |
Общий диск | //googleapis.com/drive/v3/drives/ DRIVE Где DRIVE — это идентификатор в имени ресурса | Подписка получает только события для элементов на общем диске, участником которого пользователь является через свою учетную запись Google Workspace или учетную запись Google. |
Определите целевой ресурс для Meet
Целевой ресурс | Формат | Ограничения (если применимо) |
---|---|---|
Место для встреч | //meet.googleapis.com/spaces/ SPACE Где SPACE — это идентификатор в имени ресурса | |
Пользователь | //cloudidentity.googleapis.com/users/ USER Где USER — это идентификатор в поле | Подписка получает события о конференц-залах, где пользователь относится к одной из следующих категорий:
|
Создайте подписку на Google Workspace
Для создания подписки используется метод subscriptions.create
API Google Workspace Events, который создаёт ресурс Subscription
. Необходимо указать следующие поля:
-
targetResource
: рабочее пространство Google, которое вы определили в предыдущем разделе , отформатированное с использованием полного имени ресурса. -
eventTypes
: массив из одного или нескольких типов событий, которые вы хотите получать о ресурсе. Например, если вашему приложению нужно знать только о новых сообщениях, опубликованных в чате, оно может просто подписаться на события о созданных сообщениях. -
notificationEndpoint
: конечная точка уведомлений, куда отправляются события вашей подписки Google Workspace. Для этого используется тема Pub/Sub, созданная в предыдущем разделе. -
payloadOptions
: параметры, указывающие объём данных о ресурсах, включаемых в полезную нагрузку события. Эта конфигурация влияет на срок действия вашей подписки. Подробнее см. в разделе Данные о событии .
Чтобы создать подписку на Google Workspace:
Скрипт приложений
В проекте 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, созданной в вашем проекте Cloud. Формат:projects/ PROJECT_ID /topics/ TOPIC_ID
. RESOURCE_DATA
: логическое значение, которое указывает, включает ли подписка данные о ресурсах в полезную нагрузку:-
True
: включает все данные ресурсов. Чтобы ограничить количество включаемых полей, добавьте полеfieldMask
и укажите хотя бы одно поле для изменённого ресурса. Включение данных ресурсов поддерживается только подписками на ресурсы чата. -
False
: исключает данные о ресурсах.
-
-
Чтобы создать подписку Google Workspace, запустите функцию
createSubscription
в проекте Apps Script.
Питон
В рабочем каталоге создайте файл с именем
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 , на который вы подписываетесь, отформатированный как его полное имя. Например, чтобы подписаться на пространство Google Chat с идентификаторомAAAABBBB
, используйте//chat.googleapis.com/spaces/AAAABBBB
. -
EVENT_TYPES
: Один или несколько типов событий , на которые вы хотите подписаться в целевом ресурсе. Форматируйте как массив строк, например,'google.workspace.chat.message.v1.created'
. -
TOPIC_NAME
: Полное имя темы Pub/Sub, созданной в вашем проекте Cloud. Формат:projects/ PROJECT_ID /topics/ TOPIC_ID
. RESOURCE_DATA
: логическое значение, которое указывает, включает ли подписка данные о ресурсах в полезную нагрузку:-
True
: включает все данные ресурсов. Чтобы ограничить количество включаемых полей, добавьте полеfieldMask
и укажите хотя бы одно поле для изменённого ресурса. Включение данных ресурсов поддерживается только подписками на ресурсы чата. -
False
: исключает данные о ресурсах.
-
-
Чтобы создать подписку Google Workspace, выполните в терминале следующее:
python3 create_subscription.py
API событий Google Workspace возвращает завершенную длительную операцию , содержащую экземпляр созданного вами ресурса Subscription
.
Протестируйте свою подписку на Google Workspace
Чтобы проверить, получаете ли вы события Google Workspace, вы можете инициировать событие и перенести сообщения в подписку Pub/Sub.
Чтобы протестировать подписку на Google Workspace:
Консоль Google Cloud
Запустите один или несколько типов событий в целевом ресурсе вашей подписки на Google Workspace. Например, если вы подписались на новые сообщения в чат-группе, опубликуйте сообщение в этой чат-группе.
В консоли Google Cloud перейдите на страницу Pub/Sub:
Убедитесь, что для вашего приложения выбран проект Cloud.
В меню Pub/Sub нажмите Подписки .
В таблице найдите подписку Pub/Sub для вашей темы и щелкните название подписки.
Откройте вкладку «Сообщения» .
Нажмите «Pull» . Генерация сообщения Pub/Sub может занять несколько минут.
gcloud
Запустите один или несколько типов событий в целевом ресурсе вашей подписки на Google Workspace. Например, если вы подписались на новые сообщения в чат-группе, опубликуйте сообщение в этой чат-группе.
Выполните следующую команду:
gcloud pubsub subscriptions pull PUBSUB_SUBSCRIPTION_NAME --format=json --limit=MESSAGE_COUNT --auto-ack
Заменить следующее:
-
PUBSUB_SUBSCRIPTION_NAME
: Полное имя вашей подписки Pub/Sub, отформатированное какprojects/ PROJECT_ID /subscriptions/ SUBSCRIPTION_ID
. -
MESSAGE_COUNT
: Максимальное количество сообщений Pub/Sub, которые вы хотите извлечь.
Генерация сообщения Pub/Sub может занять до нескольких минут.
-
Для каждого инициированного вами события Google Workspace в вашу подписку Pub/Sub отправляется сообщение, содержащее это событие. Подробнее см. в разделе Получение событий в виде сообщений Google Cloud Pub/Sub .
Настройте, как ваше приложение получает события
Подписка Pub/Sub, которую вы создали, основана на принципе pull. После тестирования подписки Pub/Sub вы можете обновить тип доставки, чтобы изменить способ получения событий вашим приложением. Например, вы можете настроить подписку Pub/Sub на push-доставку, чтобы ваше приложение могло получать события непосредственно в конечную точку приложения.
Информацию о настройке подписки Pub/Sub см. в документации Pub/Sub .