Работа с локальным API Meet eCDN

На этой странице объясняется, как использовать локальный API сети доставки контента Google Meet Enterprise Content Delivery Network (eCDN) для потоковой передачи видео в прямом эфире Google Meet.

Описанное здесь API-решение позволяет клиентам использовать весь набор функций Meet eCDN, не раскрывая Google информацию о частных IP-адресах. Вы можете определить новый локальный веб-сервис в своей сети, который будет передавать идентификатор вместо информации о частном IP-адресе.

Представляем обзор eCDN.

eCDN is built into Meet and starts automatically during livestreams after a Google Workspace administrator sets it up. With Meet eCDN turned on, livestream viewers within a local network can share live-streamed media with other peers in the network through peer-to-peer (P2P) sharing. Most devices receive the live-streamed media from nearby peers and don't need to fetch it from Google's servers. This lowers the total bandwidth used by viewers. For more information on setting up and using Meet eCDN, see Hosting large live streams .

Для работы eCDN необходимо, чтобы пользователи Meet Live Streaming были объединены в пиринговые группы. Пиринговая группа — это совокупность узлов, которым разрешено обмениваться медиафайлами друг с другом. Устройствам в пиринговой группе либо разрешается, либо запрещается устанавливать пиринг. Разрешенные устройства могут подключаться только к другим устройствам в той же пиринговой группе. Дополнительную информацию о пиринговых группах см. в разделе «Перед началом проведения масштабных прямых трансляций» .

Когда использовать API

eCDN может формировать пиринговые группы, используя несколько различных политик пиринга: random , subnet или custom rules . Последняя использует общую таблицу диапазонов частных сетей с сервером отслеживания eCDN от Google для сопоставления частных IP-адресов каждого узла пиринга с пиринговой группой. Политика custom rules является предпочтительным решением и подходит для большинства производственных сред.

Однако политика custom rules требует от вас предоставления Google доступа к значительной части структуры вашей частной сети. Кроме того, отдельные пользователи раскрывают Google свои локально обнаруженные частные IP-адреса при использовании eCDN. В некоторых организациях правила безопасности могут не разрешать передачу информации о частных IP-адресах.

Разработка с использованием локального API Meet eCDN

API Meet eCDN On-Premises предоставляет спецификацию веб-сервера, которую вы можете внедрить и разместить локально в сети вашей организации. Вы можете создать собственный веб-сервис, совместимый с этим API, для выполнения всех задач, зависящих от информации о частном IP-адресе, чтобы эта информация не передавалась в Google.

API включает в себя два критически важных этапа сопоставления частных IP-адресов, которые обычно обрабатываются сервером отслеживания eCDN: сопоставление частных IP-адресов с группой пиринга и обмен данными предложения-ответа по протоколу описания сессии (SDP) во время сигнализации WebRTC.

После завершения настройки веб-сервиса необходимо настроить консоль администратора для использования политики пиринга On-premises service и указать URL-адрес вашего пользовательского веб-сервиса.

Требования

Если для вашей организации необходимо включить какие-либо из этих требований, обратитесь к администратору Google Workspace:

  • Любой веб-сервер, использующий HTTPS, может реализовать этот API.

  • Используйте HTTPS, чтобы предотвратить ошибки, связанные с несовместимым контентом.

  • Принимать и возвращать данные в формате JSON. Использовать любую кодировку контента, поддерживаемую вашим браузером.

  • Обслуживайте конечные точки по маршруту /v n где n — выбранная версия API. Например, /v1/get-peering-group .

  • Зрители прямых трансляций могут узнать URL-адрес вашего веб-сервиса через консоль администратора Google. URL-адрес можно установить глобально, для каждого подразделения организации или для каждой группы. Убедитесь, что зрители могут подключиться к назначенному им экземпляру сервиса. Для получения дополнительной информации см. раздел «Настройка консоли администратора» .

  • Ваш сервис должен возвращать ответ в течение двух секунд. В противном случае клиент eCDN завершает работу, и зритель продолжает смотреть прямую трансляцию как обычный пользователь, не использующий eCDN, лишая себя возможности сэкономить трафик.

  • Ваша служба должна устанавливать следующие заголовки Cross-Origin Resource Sharing (CORS):

    • Access-Control-Allow-Origin: meet.google.com
    • Access-Control-Allow-Headers: GET, POST, OPTIONS
    • Access-Control-Allow-Credentials: true

Привязать частные IP-адреса к пиринговой группе

The eCDN client makes a call every time it tries reconnecting to the eCDN tracker server. After a device detects a private IP address, the address must be mapped to the proper peering group. You must send the private IP address to a server on your network and manually resolve it to a peering group using the get-peering-group() method. A peering group ID is returned in the response. When communicating with Google, the resulting peering group ID is passed instead of private IP addresses.

Как частные IP-адреса сопоставляются с пиринговой группой.
Рисунок 1. Сопоставление частных IP-адресов с пиринговой группой.

Приведённый ниже пример кода демонстрирует вызов метода get-peering-group() вместе с возможным ответом об ошибке и ожидаемым телом ответа:

POST /v1/get-peering-group
Content-Type: application/json

Request body:
{
  "availableIPs": []{
    "format": "ipv4"|"ipv6",
    "address": "DETECTED_ADDRESS"
  }
}

Error response:
{
  "result": null,
  "error": "ERROR_MESSAGE"
}

Response body:
{
  "allowed": boolean,
  "result": string,
  "error": null
}

В таблице ниже представлены ожидаемые форматы ответов:

HTTP-статус Ошибка Допустимый Результат Реакция клиента
200 нулевой истинный Непустая строка Клиент попадает в указанную группу пиринга и подключается к серверу отслеживания eCDN.
200 нулевой ЛОЖЬ Непустая строка Клиент помечается как заблокированный указанной группой пиринга, становится видимым в инструменте Meet Quality Tool (MQT) и завершает сессию eCDN.
200 нулевой Пустая строка Клиент завершает сессию eCDN.
200 Непустая строка Клиент завершает сессию eCDN.
302 (Найдено) Клиент переходит по перенаправлению на новый URL-адрес, указанный в заголовке Location тела ответа.
Любой другой код состояния Клиент завершает сессию eCDN.

Устаревший формат ответа

Поле allowed отсутствовало в формате ответа более ранних версий. Вместо этого специальные зарезервированные значения для result определяли, будет ли IP-адрес пользователя заблокирован для установления пирингового соединения:

Legacy response body:
{
  "result": string,
  "error": null,
}

В таблице ниже показаны ожидаемые форматы ответа, если в ответном сообщении не указано allowed поле:

HTTP-статус Ошибка Результат Реакция клиента
200 нулевой Непустая строка Клиент должен быть отнесен к группе пиринга и приступить к подключению к серверу отслеживания eCDN.
200 нулевой NOT_FOUND Клиент завершает сессию eCDN.
200 нулевой BLOCKED Клиент завершает сессию eCDN.
200 Непустая строка Клиент завершает сессию eCDN.
302 (Найдено) Клиент переходит по перенаправлению на новый URL-адрес, указанный в заголовке Location тела ответа.
Любой другой код состояния Клиент завершает сессию eCDN.

Обмен данными между предложениями и ответами SDP

Для установления соединения WebRTC устройства должны обмениваться своими предложениями и ответами SDP, включая кандидаты на установление интерактивного соединения (ICE), содержащие конфиденциальную IP-информацию. Это происходит в рамках процесса сигнализации WebRTC.

Clients must encrypt their ICE candidates inside their network through the Meet eCDN On-Premises API, using the encrypt-sdp() method. The method uses a key that's never exposed to Google. The encrypted SDP offer is then sent to the peer using the eCDN tracker server. The client peer then decrypts the received information inside their network using the decrypt-sdp() method. Google then forwards the offers and answers between the connected peers.

После установления соединения с использованием API Meet eCDN On-Premises, eCDN работает в обычном режиме. Узел-партнер направляет медиапоток через обычную пиринговую сеть, и медиатрафик не проходит через API и не использует его.

Как происходит шифрование и расшифровка данных, предлагаемых и принимаемых в рамках SDP.
Рисунок 2. Шифрование и расшифровка данных предложения и ответа SDP.

Приведённый ниже пример кода демонстрирует вызов метода encrypt-sdp() вместе с возможным ответом об ошибке и ожидаемым телом ответа:

POST /v1/encrypt-sdp
Content-Type: application/json

Request body:
{
  "data": "SDP_DATA"
},

Error response:
{
  "result": null,
  "error": "ERROR_MESSAGE"
}

Response body:
{
  "result": "ENCRYPTED_DATA_STRING",
  "error": null
}

Приведённый ниже пример кода демонстрирует вызов метода decrypt-sdp() вместе с возможным ответом об ошибке и ожидаемым телом ответа:

POST /v1/decrypt-sdp
Content-Type: application/json

Request body:
{
  "data": "ENCRYPTED_DATA_STRING"
},

Error response:
{
  "result": null,
  "error": "ERROR_MESSAGE"
}

Response body:
{
  "result": "SDP_DATA",
  "error": null
}

В таблице ниже представлены ожидаемые форматы ответов:

HTTP-статус Ошибка Идентификатор пиринговой группы Реакция клиента
200 нулевой Непустая строка Клиент ожидает использования корректно закодированных или декодированных данных SDP.
200 Любая непустая строка нулевой Клиент завершает сессию eCDN.
302 (Найдено) Клиент переходит по перенаправлению на новый URL-адрес, указанный в заголовке Location тела ответа.
Любой другой код состояния Любая ценность Любая ценность Клиент завершает сессию eCDN.

Настройте консоль администратора.

Для использования API Meet eCDN On-Premises необходимо настроить eCDN в консоли администратора , добавив URL-адрес вашей пользовательской веб-службы.

Для настройки eCDN создайте политику пиринга с помощью On-premises service , чтобы вручную сопоставить IP-адреса с группами пиринга. Вы также можете указать номер порта, если не используете порт по умолчанию 443. URL-адрес должен соответствовать следующему формату: WEB_SERVICE.example.com:8080 , где WEB_SERVICE — это имя вашей веб-службы.

Для получения дополнительной информации о настройке политики пиринга см. раздел «Настройка группировки сети» .