На этой странице объясняется, как использовать API событий Google Workspace для создания подписки на ресурс Google Workspace. Подписка на Google Workspace позволяет вашему приложению получать информацию о событиях Google Workspace , которые представляют собой изменения в ресурсе Google Workspace. Чтобы узнать, какие ресурсы и типы событий поддерживает Google Workspace Events API, см. обзор Google Workspace Events API .
На этой странице представлены следующие шаги по созданию подписки на Google Workspace:
- Настройте свою среду.
- Создайте тему Google Cloud Pub/Sub и подпишитесь на нее. Вы используете эту тему как конечную точку для получения событий Google Workspace.
- Вызовите метод
create()
API Google Workspace Events для ресурсаSubscription
. - Проверьте свою подписку на Google Workspace, чтобы убедиться, что ваша тема Pub/Sub получает события, на которые вы подписаны.
- При необходимости настройте способ отправки событий в конечную точку вашего приложения, чтобы ваше приложение могло обрабатывать событие и, при необходимости, предпринимать действия.
Предварительные условия
Скрипт приложений
- Чтобы использовать команды Google Cloud CLI в этом руководстве:
- Установите Google Cloud CLI .
- Чтобы инициализировать интерфейс командной строки
gcloud
, запустите следующий код:
gcloud init
- Проект Google Cloud с включенной оплатой. Для подписки на Chat вам также необходимо включить Chat API в своем облачном проекте и настроить поля «Имя приложения» , «URL-адрес аватара» и «Описание» . Подробную информацию см. в разделе Создание приложения Google Chat .
- Требуется аутентификация пользователя с помощью экрана согласия OAuth, настроенного для приложения. При настройке экрана согласия необходимо указать область для поддержки каждого типа событий для подписки. Чтобы настроить экран согласия и определить необходимые области, см. Выбор областей .
- Проект скрипта приложений:
- Используйте свой проект 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
, запустите следующий код:
gcloud init
- Проект 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:
gcloud
В своем рабочем каталоге войдите в свою учетную запись Google:
gcloud auth login
Настройте свой проект как облачный проект для вашего приложения:
gcloud config set project PROJECT_ID
Замените
PROJECT_ID
на идентификатор проекта Cloud для вашего приложения.Включите API Google Workspace Events и API Google Cloud Pub/Sub:
gcloud services enable pubsub.googleapis.com workspaceevents.googleapis.com
Создайте учетные данные идентификатора клиента OAuth.
Выберите тип приложения для получения конкретных инструкций о том, как создать идентификатор клиента OAuth:
Веб-приложение
- В консоли Google Cloud выберите > API и службы > Учетные данные .
- Нажмите «Создать учетные данные» > «Идентификатор клиента OAuth» .
- Щелкните Тип приложения > Веб-приложение .
- В поле Имя введите имя учетных данных. Это имя отображается только в консоли Google Cloud.
- Добавьте авторизованные URI, связанные с вашим приложением:
- Клиентские приложения (JavaScript) . В разделе «Авторизованные источники JavaScript» нажмите « Добавить URI» . Затем введите URI, который будет использоваться для запросов браузера. Это определяет домены, из которых ваше приложение может отправлять запросы API на сервер OAuth 2.0.
- Серверные приложения (Java, Python и т. д.) – в разделе «Авторизованные URI перенаправления» нажмите « Добавить URI» . Затем введите URI конечной точки, на который сервер OAuth 2.0 может отправлять ответы.
- Нажмите Создать . Появится экран создания клиента OAuth, показывающий ваш новый идентификатор клиента и секрет клиента.
Обратите внимание на идентификатор клиента. Секреты клиента не используются для веб-приложений.
- Нажмите ОК . Вновь созданные учетные данные появятся в разделе «Идентификаторы клиентов OAuth 2.0» .
Андроид
- В консоли Google Cloud выберите > API и службы > Учетные данные .
- Нажмите «Создать учетные данные» > «Идентификатор клиента OAuth» .
- Нажмите Тип приложения > Android .
- В поле «Имя» введите имя учетных данных. Это имя отображается только в консоли Google Cloud.
- В поле «Имя пакета» введите имя пакета из файла
AndroidManifest.xml
. - В поле «Отпечаток сертификата SHA-1» введите сгенерированный отпечаток сертификата SHA-1 .
- Нажмите Создать . Появится экран создания клиента OAuth, на котором будет показан ваш новый идентификатор клиента.
- Нажмите ОК . Вновь созданные учетные данные появятся в разделе «Идентификаторы клиентов OAuth 2.0».
iOS
- В консоли Google Cloud выберите > API и службы > Учетные данные .
- Нажмите «Создать учетные данные» > «Идентификатор клиента OAuth» .
- Нажмите Тип приложения > iOS .
- В поле «Имя» введите имя учетных данных. Это имя отображается только в консоли Google Cloud.
- В поле «Идентификатор пакета» введите идентификатор пакета, указанный в файле
Info.plist
приложения. - Необязательно: если ваше приложение появилось в Apple App Store, введите идентификатор App Store.
- Необязательно: в поле «Идентификатор команды» введите уникальную строку из 10 символов, созданную Apple и назначенную вашей команде.
- Нажмите Создать . Появится экран создания клиента OAuth, показывающий ваш новый идентификатор клиента и секрет клиента.
- Нажмите ОК . Вновь созданные учетные данные появятся в разделе «Идентификаторы клиентов OAuth 2.0».
Приложение Chrome
- В консоли Google Cloud выберите > API и службы > Учетные данные .
- Нажмите «Создать учетные данные» > «Идентификатор клиента OAuth» .
- Нажмите Тип приложения > Приложение Chrome .
- В поле «Имя» введите имя учетных данных. Это имя отображается только в консоли Google Cloud.
- В поле «Идентификатор приложения» введите уникальную 32-значную строку идентификатора вашего приложения. Это значение идентификатора можно найти в URL-адресе Интернет-магазина Chrome вашего приложения и на панели инструментов разработчика Интернет-магазина Chrome .
- Нажмите Создать . Появится экран создания клиента OAuth, показывающий ваш новый идентификатор клиента и секрет клиента.
- Нажмите ОК . Вновь созданные учетные данные появятся в разделе «Идентификаторы клиентов OAuth 2.0».
Настольное приложение
- В консоли Google Cloud выберите > API и службы > Учетные данные .
- Нажмите «Создать учетные данные» > «Идентификатор клиента OAuth» .
- Нажмите Тип приложения > Приложение для ПК .
- В поле Имя введите имя учетных данных. Это имя отображается только в консоли Google Cloud.
- Нажмите Создать . Появится экран создания клиента OAuth, показывающий ваш новый идентификатор клиента и секрет клиента.
- Нажмите ОК . Вновь созданные учетные данные появятся в разделе «Идентификаторы клиентов OAuth 2.0».
Телевизоры и ограниченные устройства ввода
- В консоли Google Cloud выберите > API и службы > Учетные данные .
- Нажмите «Создать учетные данные» > «Идентификатор клиента OAuth» .
- Нажмите «Тип приложения» > «Телевизоры и устройства с ограниченным вводом» .
- В поле «Имя» введите имя учетных данных. Это имя отображается только в консоли Google Cloud.
- Нажмите Создать . Появится экран создания клиента OAuth, показывающий ваш новый идентификатор клиента и секрет клиента.
- Нажмите ОК . Вновь созданные учетные данные появятся в разделе «Идентификаторы клиентов OAuth 2.0».
Универсальная платформа Windows (UWP)
- В консоли Google Cloud выберите > API и службы > Учетные данные .
- Нажмите «Создать учетные данные» > «Идентификатор клиента OAuth» .
- Щелкните Тип приложения > Универсальная платформа Windows (UWP) .
- В поле «Имя» введите имя учетных данных. Это имя отображается только в консоли Google Cloud.
- В поле «Идентификатор магазина» введите уникальное 12-значное значение идентификатора Microsoft Store вашего приложения. Этот идентификатор можно найти в URL-адресе вашего приложения в Microsoft Store и в Центре партнеров .
- Нажмите Создать . Появится экран создания клиента OAuth, показывающий ваш новый идентификатор клиента и секрет клиента.
- Нажмите ОК . Вновь созданные учетные данные появятся в разделе «Идентификаторы клиентов OAuth 2.0».
Загрузите JSON-файл секретного клиента.
Секретный файл клиента — это JSON-представление учетных данных идентификатора клиента OAuth, на которое ваше приложение может ссылаться при предоставлении учетных данных.
В консоли Google Cloud выберите > API и службы > Учетные данные .
В разделе «Идентификаторы клиентов OAuth 2.0» щелкните созданный вами идентификатор клиента.
Нажмите «Загрузить JSON» .
Сохраните файл как
client_secrets.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.
Убедитесь, что для вашего приложения выбран облачный проект.
Нажмите
Создать тему и выполните следующие действия:- Введите название своей темы, например
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
. - Для мероприятий 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
. - Чтобы получать события от 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 Chat ( spaces/AAAABBBBBBB
), значение targetResource
— //chat.googleapis.com/spaces/AAAABBBBBBB
.
Прежде чем создавать подписку, воспользуйтесь следующими разделами, чтобы узнать, как идентифицировать и форматировать целевой ресурс.
Определите целевой ресурс для Chat
Целевой ресурс | Формат | Ограничения |
---|---|---|
Космос | где SPACE — это идентификатор в имени ресурса | Пользователь Chat, который авторизует подписку, должен быть участником пространства через свою учетную запись Google Workspace или Google. |
Все пространства для пользователя | | Подписка получает события только для тех пространств, участником которых является пользователь через свою Google Workspace или учетную запись Google. |
Пользователь | где USER — это идентификатор в имени | Подписка получает только события о пользователе, который авторизовал подписку. Пользователь не может авторизовать подписку от имени других пользователей. |
Определите целевой ресурс для Meet
Целевой ресурс | Формат | Ограничения (если применимо) |
---|---|---|
Место для встреч | //meet.googleapis.com/spaces/ SPACE где SPACE — это идентификатор в имени ресурса | |
Пользователь | //cloudidentity.googleapis.com/users/ USER где USER — это идентификатор в поле | Подписка получает события о пространствах для собраний, где пользователь является одним из следующих:
|
Создайте подписку на Google Workspace
Чтобы создать подписку, вы используете метод subscriptions.create()
API Google Workspace Events для создания ресурса Subscription
. Вы указываете следующие поля:
-
targetResource
: Google Workspace, указанный в предыдущем разделе , отформатированный с использованием полного имени ресурса. -
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 с идентификатором чат-группы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
: исключает данные ресурсов.
-
-
Чтобы создать подписку на 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('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
: исключает данные ресурсов.
-
-
Чтобы создать подписку на 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:
Убедитесь, что для вашего приложения выбран облачный проект.
В меню Pub/Sub нажмите «Подписки» .
В таблице найдите подписку Pub/Sub для вашей темы и нажмите на название подписки.
Откройте вкладку «Сообщения» .
Нажмите «Потянуть» . Создание сообщения 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/ 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 .