Создайте подписку на 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 , запустите следующий код:

    gcloud init
    

• Проект 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 , запустите следующий код:

    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:

Включите 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.

Примечание. Если вы используете Apps Script, вы можете пропустить этот шаг.

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

Примечание. Чтобы запустить пример кода из этого руководства, выберите приложение для ПК и следуйте инструкциям.

Веб-приложение

1. В консоли Google Cloud перейдите в Меню > > Клиенты .

   Перейти к Клиентам

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

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

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

Андроид

1. В консоли Google Cloud перейдите в Меню > > Клиенты .

   Перейти к Клиентам

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

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

iOS

1. В консоли Google Cloud перейдите в Меню > > Клиенты .

   Перейти к Клиентам

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

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

Приложение Chrome

1. В консоли Google Cloud перейдите в Меню > > Клиенты .

   Перейти к Клиентам

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

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

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

1. В консоли Google Cloud перейдите в Меню > > Клиенты .

   Перейти к Клиентам

2. Нажмите Создать клиента .
3. Нажмите Тип приложения > Приложение для ПК .
4. В поле Имя введите имя учетных данных. Это имя отображается только в консоли Google Cloud.
5. Нажмите Создать .

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

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

1. В консоли Google Cloud перейдите в Меню > > Клиенты .

   Перейти к Клиентам

2. Нажмите Создать клиента .
3. Нажмите «Тип приложения» > «Телевизоры и устройства с ограниченным вводом» .
4. В поле «Имя» введите имя учетных данных. Это имя отображается только в консоли Google Cloud.
5. Нажмите Создать .

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

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

1. В консоли Google Cloud перейдите в Меню > > Клиенты .

   Перейти к Клиентам

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

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

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

Примечание. Если вы используете Apps Script, вы можете пропустить этот шаг.

Секретный файл клиента — это 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. Для событий чата: [e-mail] .
      2. Для мероприятий Meet [e-mail] .
   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, которое должно доставлять события в вашу подписку:

     • Чтобы получать события из чата, используйте [e-mail] .
     • Чтобы получать события от Meet, используйте [e-mail] .

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

3. Создайте подписку 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

Целевой ресурс	Формат	Ограничения
Космос	//chat.googleapis.com/spaces/ SPACE где SPACE — это идентификатор в имени ресурса space Chat API. Вы можете получить идентификатор из URL-адреса пространства или с помощью метода spaces.list() .	Пользователь Chat, который авторизует подписку, должен быть участником пространства через свою Google Workspace или учетную запись Google.
Все пространства для пользователя	//chat.googleapis.com/spaces/-	Подписка получает события только для тех пространств, участником которых является пользователь через свою учетную запись Google Workspace или Google.
Пользователь	//cloudidentity.googleapis.com/users/ USER где USER — это идентификатор в имени user ресурса Chat API. Подробную информацию см. в разделе Идентификация и указание пользователей Google Chat .	Подписка получает только события о пользователе, который авторизовал подписку. Пользователь не может авторизовать подписку от имени других пользователей.

Определите целевой ресурс для Meet

Целевой ресурс	Формат	Ограничения (если применимо)
Место для встреч	//meet.googleapis.com/spaces/ SPACE где SPACE — это идентификатор в имени ресурса space Meet REST API. Подробную информацию см. в разделе «Как Meet определяет место для встреч» .
Пользователь	//cloudidentity.googleapis.com/users/ USER где USER — это идентификатор в поле signedinUser.user ресурса participant Meet REST API. Подробнее см. Работа с участниками .	Подписка получает события о пространствах для собраний, где пользователь является одним из следующих: Владелец конференц-зала. Участник встречи. Организатор мероприятия Календаря Google, связанного с местом встречи.

Создайте подписку на 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 .

Примечание. Вы не можете установить проект Apps Script в качестве конечной точки принудительной доставки в Pub/Sub. Чтобы отправить сообщения Pub/Sub в проект Apps Script, необходимо опубликовать скрипт как веб-приложение .

Связанные темы

• Руководство. Наблюдайте за событиями собраний с помощью Python и REST API Google Meet
• Получить подписку
• Получение списка подписок
• Обновить или продлить подписку
• Устраните ошибки и повторно активируйте подписку
• Удалить подписку