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

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

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

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

Предпосылки

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

  • Чтобы использовать команды Google Cloud CLI в этом руководстве:
    1. Установите Google Cloud CLI .
    2. Чтобы инициализировать gcloud CLI, выполните следующий код:
    3.   gcloud init
        
  • Проект Google Cloud с включённым биллингом. Для подписок на Chat необходимо также включить Chat API в вашем проекте Cloud и настроить поля «Название приложения» , «URL аватара» и «Описание» . Подробнее см. в статье «Создание приложения Google Chat» .
  • Требуется аутентификация пользователя с помощью экрана согласия OAuth, настроенного для приложения. При настройке экрана согласия необходимо указать область действия для поддержки каждого типа событий подписки. Чтобы настроить экран согласия и определить необходимые области действия, см. раздел Выбор областей действия .
  • Проект Apps Script:
    • Используйте свой проект 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 CLI, выполните следующий код:
    3.   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:

Включить API

gcloud

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

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

    gcloud config set project PROJECT_ID

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

  3. Включите API событий Google Workspace и API Google Cloud Pub/Sub:

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

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

Выберите тип приложения для получения конкретных инструкций по созданию идентификатора клиента 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-файл секретного ключа клиента

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

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

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

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

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

  4. Сохраните файл как credentials.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

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

  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. Предварительная версия для разработчиков : для событий Drive — drive-api-event-push@system.gserviceaccount.com .
      3. Для мероприятий Meet, meet-api-event-push@system.gserviceaccount.com .
    4. В меню «Назначить роли» выберите Pub/Sub Publisher .
    5. Нажмите «Сохранить» . Обновление разрешений для вашей темы может занять несколько минут.

gcloud

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

    gcloud pubsub topics create TOPIC_ID

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

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

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

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

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

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

      • Для получения событий из чата используйте chat-api-push@system.gserviceaccount.com .
      • Предварительная версия для разработчиков: Чтобы получать события от Drive, используйте drive-api-event-push@system.gserviceaccount.com .
      • Для получения событий от Meet используйте meet-api-event-push@system.gserviceaccount.com .

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

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

     gcloud pubsub subscriptions create SUBSCRIPTION_NAME --topic=TOPIC_NAME

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

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

Подпишитесь на ресурс Google Workspace

В этом разделе вы подписываетесь на ресурс Google Workspace, события которого вы хотите отслеживать.

Выберите и определите целевой ресурс

В подписке на Google Workspace целевым ресурсом является ресурс Google Workspace, события которого отслеживаются. Целевой ресурс указан в поле targetResource подписки, отформатированном с использованием полного имени ресурса. Например, для подписки, отслеживающей чат-группу Google ( spaces/AAAABBBBBBB ), значение targetResource будет: //chat.googleapis.com/spaces/AAAABBBBBBB .

Прежде чем создавать подписку, изучите следующие разделы, как определить и отформатировать целевой ресурс.

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

Целевой ресурс Формат Ограничения
Космос

//chat.googleapis.com/spaces/ SPACE

Где SPACE — это идентификатор в имени ресурса space Chat API. Вы можете получить идентификатор из URL пространства или с помощью метода spaces.list() .

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

//chat.googleapis.com/spaces/-

Подписка получает события только для тех пространств, в которых пользователь является участником через свое Google Workspace или учетную запись Google.
Пользователь

//cloudidentity.googleapis.com/users/ USER

Где USER — это идентификатор в имени ресурса user API чата. Подробнее см. в разделе Идентификация и указание пользователей Google Chat .

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

Определите целевой ресурс для Диска

Целевой ресурс Формат Ограничения (если применимо)
Файл //googleapis.com/drive/v3/files/ FILE

Где FILE — идентификатор в имени ресурса files API Диска. Идентификатор можно получить из URL-адреса файла или с помощью метода files.list .

Пользователь, который авторизует подписку, должен иметь разрешение на файл в рамках подписки, относящееся к событию подписки.
Общий диск //googleapis.com/drive/v3/drives/ DRIVE

Где DRIVE — это идентификатор в имени ресурса drives API. Идентификатор можно получить из URL-адреса диска или с помощью метода drives.list .

Подписка получает только события для элементов на общем диске, участником которого пользователь является через свою учетную запись Google Workspace или учетную запись Google.

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

Целевой ресурс Формат Ограничения (если применимо)
Место для встреч //meet.googleapis.com/spaces/ SPACE

Где SPACE — это идентификатор в имени ресурса space REST API Meet. Подробнее см. в статье «Как Meet определяет пространство для встречи» .

Пользователь //cloudidentity.googleapis.com/users/ USER

Где USER — это идентификатор в поле signedinUser.user ресурса participant REST API Meet. Подробнее см. в разделе Работа с участниками .

Подписка получает события о конференц-залах, где пользователь относится к одной из следующих категорий:

  • Владелец помещения для проведения встреч.
  • Участник в месте встречи.
  • Организатор события в Google Календаре, связанного с местом проведения встречи.

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

Для создания подписки используется метод subscriptions.create API Google Workspace Events, который создаёт ресурс Subscription . Необходимо указать следующие поля:

  • targetResource : рабочее пространство Google, которое вы определили в предыдущем разделе , отформатированное с использованием полного имени ресурса.
  • 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, созданной в вашем проекте Cloud. Формат: projects/ PROJECT_ID /topics/ TOPIC_ID .
    • RESOURCE_DATA : логическое значение, которое указывает, включает ли подписка данные о ресурсах в полезную нагрузку:

      • True : включает все данные ресурсов. Чтобы ограничить количество включаемых полей, добавьте поле fieldMask и укажите хотя бы одно поле для изменённого ресурса. Включение данных ресурсов поддерживается только подписками на ресурсы чата.
      • 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('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 : исключает данные о ресурсах.
  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:

    Перейти в Pub/Sub

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

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

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

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

  6. Нажмите «Pull» . Генерация сообщения 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/ 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 .