Trabalhar com a API Meet eCDN On-Prem

Esta página explica como usar a API Meet eCDN On-Premises para transmissões ao vivo do Google Meet.

A solução de API descrita aqui permite que os clientes usem o conjunto de atributos completo da eCDN do Meet sem expor informações de IP particular ao Google. É possível definir um novo serviço da Web local na sua própria rede que transmite um ID em vez das informações de endereço IP particular.

Visão geral da eCDN do Meet

A eCDN é integrada ao Meet e iniciada automaticamente durante as transmissões ao vivo depois que um administrador do Google Workspace a configura. Com a eCDN do Meet ativada, os espectadores de uma transmissão ao vivo em uma rede local podem compartilhar mídias transmitidas ao vivo com outros participantes na rede usando o compartilhamento ponto a ponto (P2P). A maioria dos dispositivos recebe a mídia transmitida ao vivo de colegas próximos e não precisa buscá-la nos servidores do Google. Isso reduz a largura de banda total usada pelos espectadores. Para mais informações sobre como configurar e usar a eCDN do Meet, consulte Hospedar grandes transmissões ao vivo.

A eCDN exige que os espectadores de transmissões ao vivo do Meet sejam ordenados em grupos de peering. Um grupo de peering é uma coleção de nós que podem compartilhar mídia entre si. Os dispositivos em um grupo de peering têm permissão ou estão bloqueados para peering. Os aparelhos permitidos só podem se conectar a outros dispositivos no mesmo grupo de peering. Para mais informações sobre grupos de peering, consulte Antes de começar a hospedar grandes transmissões ao vivo.

Quando usar a API

A eCDN pode formar grupos de peering usando várias políticas diferentes: random, subnet ou custom rules. A última compartilha uma tabela de intervalos de rede particular com o servidor de rastreamento da eCDN do Google para mapear endereços IP particulares de cada nó de peering para um grupo. A política custom rules é a solução preferida e adequada na maioria dos ambientes de produção.

No entanto, a política custom rules exige que você compartilhe grandes partes da sua estrutura de rede particular com o Google. Além disso, os usuários individuais expõem os endereços IP particulares detectados localmente ao Google ao usar a eCDN. Para algumas organizações, as diretrizes de segurança podem não permitir o compartilhamento de informações de IP particular.

Desenvolver com a API Meet eCDN On-Premises

A API Meet eCDN On-Premises oferece uma especificação de servidor da Web que pode ser implementada e hospedada localmente na rede da sua organização. É possível criar um serviço da Web personalizado compatível com a API para realizar todas as tarefas dependentes de informações de IP particular para que as informações não sejam compartilhadas com o Google.

A API abrange as duas etapas críticas para correspondência de endereços IP particulares que normalmente são processadas pelo servidor de rastreamento da eCDN: mapear endereços IP particulares para um grupo de peering e troca de dados de oferta e resposta do Protocolo de descrição de sessão (SDP) durante a sinalização WebRTC.

Depois que o serviço da Web for concluído, você deve configurar o Admin Console para usar uma política de peering On-premises service e incluir o URL do seu serviço da Web personalizado.

Requisitos

Se você precisar que algum desses requisitos seja ativado para sua organização, pergunte ao administrador do Google Workspace:

  • Qualquer servidor da Web que use HTTPS pode implementar essa API.

  • Use HTTPS para evitar falhas de conteúdo misto.

  • Aceite e retorne dados JSON. Use qualquer codificação de conteúdo compatível com seu navegador.

  • Forneça endpoints em uma rota /vn, em que n é a versão da API selecionada. Por exemplo, /v1/get-peering-group.

  • Os espectadores de transmissões ao vivo do Meet podem saber o URL do seu serviço da Web pelo Google Admin Console. O URL pode ser definido globalmente, por unidade organizacional ou por grupo. Verifique se os espectadores podem se conectar à instância atribuída do serviço. Para mais informações, consulte Configurar o Admin Console.

  • Seu serviço precisa retornar uma resposta em até dois segundos. Caso contrário, o cliente da eCDN será desligado e o espectador continuará assistindo o evento ao vivo como um usuário normal, sem eCDN, negando a ele qualquer economia de largura de banda.

  • Seu serviço precisa definir os seguintes cabeçalhos de compartilhamento de recursos entre origens (CORS, na sigla em inglês):

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

Mapear endereços IP particulares para um grupo de peering

O cliente da eCDN faz uma chamada sempre que tenta se reconectar ao servidor de rastreamento da eCDN. Depois que um dispositivo detecta um endereço IP particular, ele precisa ser mapeado para o grupo de peering adequado. É necessário enviar o endereço IP particular para um servidor na sua rede e resolvê-lo manualmente para um grupo de peering usando o método get-peering-group(). Um ID de grupo de peering é retornado na resposta. Ao se comunicar com o Google, o ID do grupo de peering resultante é transmitido em vez de endereços IP particulares.

Como os endereços IP particulares são mapeados para um grupo de peering.
Figura 1. Mapeamento de endereços IP particulares para um grupo de peering.

O exemplo de código a seguir mostra como chamar o método get-peering-group() com a possível resposta de erro e o corpo da resposta esperado:

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
}

A tabela a seguir mostra os formatos de resposta esperados:

Status HTTP Erro Permitido Resultado Reação do cliente
200 null verdadeiro String não vazia O cliente é classificado no grupo de peering especificado e continua a se conectar ao servidor de rastreamento da eCDN.
200 null falso String não vazia O cliente é marcado como bloqueado pelo grupo de peering especificado, fica visível em ferramenta de qualidade do Meet (MQT) e encerra a sessão da eCDN.
200 null String vazia O cliente encerra a sessão da eCDN.
200 String não vazia O cliente encerra a sessão da eCDN.
302 (Encontrado) O cliente segue o redirecionamento para o novo URL especificado no cabeçalho Location do corpo da resposta.
Qualquer outro código de status O cliente encerra a sessão da eCDN.

Formato de resposta legado

O campo allowed não fazia parte do formato de resposta das versões anteriores. Em vez disso, valores reservados especiais para result determinariam se o endereço IP de um espectador seria bloqueado para peering:

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

A tabela a seguir mostra os formatos de resposta esperados se o campo allowed não estiver definido na mensagem de resposta:

Status HTTP Erro Resultado Reação do cliente
200 null String não vazia O cliente precisa ser classificado em um grupo de peering e continua a se conectar ao servidor de rastreamento da eCDN.
200 null NOT_FOUND O cliente encerra a sessão da eCDN.
200 null BLOCKED O cliente encerra a sessão da eCDN.
200 String não vazia O cliente encerra a sessão da eCDN.
302 (Encontrado) O cliente segue o redirecionamento para o novo URL especificado no cabeçalho Location do corpo da resposta.
Qualquer outro código de status O cliente encerra a sessão da eCDN.

Troca de dados de oferta e resposta do SDP

Para iniciar uma conexão WebRTC, os dispositivos precisam trocar as ofertas e respostas do SDP, incluindo candidatos de estabelecimento de conectividade interativa (ICE), que contêm informações de IP particular. Eles fazem isso como parte do processo de sinalização WebRTC.

Os clientes precisam criptografar os candidatos ICE na rede usando a API Meet eCDN On-Premises, usando o método encrypt-sdp(). O método usa uma chave que nunca é exposta ao Google. A oferta de SDP criptografada é enviada ao participante usando o servidor de rastreamento da eCDN. O participante do cliente descriptografa as informações recebidas na rede usando o método decrypt-sdp(). Em seguida, o Google encaminha as ofertas e respostas entre os participantes conectados.

Depois que a conexão é estabelecida usando a API Meet eCDN On-Premises, a eCDN funciona normalmente. Os participantes encaminham a mídia pela rede de peering normal, e o tráfego de mídia não passa nem usa a API.

Como os dados de oferta e resposta do SDP são criptografados e descriptografados.
Figura 2. Criptografar e descriptografar os dados de oferta e resposta do SDP.

O exemplo de código a seguir mostra como chamar o método encrypt-sdp() com a possível resposta de erro e o corpo da resposta esperado:

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
}

O exemplo de código a seguir mostra como chamar o método decrypt-sdp() com a possível resposta de erro e o corpo da resposta esperado:

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
}

A tabela a seguir mostra os formatos de resposta esperados:

Status HTTP Erro ID do grupo de peering Reação do cliente
200 null String não vazia O cliente espera que os dados do SDP codificados ou decodificados corretamente sejam usados.
200 Qualquer string não vazia null O cliente encerra a sessão da eCDN.
302 (Encontrado) O cliente segue o redirecionamento para o novo URL especificado no cabeçalho Location do corpo da resposta.
Qualquer outro código de status Qualquer valor Qualquer valor O cliente encerra a sessão da eCDN.

Configurar o Admin Console

Para usar a API Meet eCDN On-Premises, configure a eCDN no Admin Console para incluir o URL do seu serviço da Web personalizado.

Para definir a eCDN, crie uma política de peering usando On-premises service para corresponder manualmente as informações de IP aos grupos de peering. Você também pode incluir um número de porta se não estiver usando o padrão 443. O URL precisa corresponder ao seguinte formato: WEB_SERVICE.example.com:8080, em que WEB_SERVICE é o nome do seu serviço da Web.

Para mais informações sobre como definir uma política de peering, consulte Configurar o agrupamento de redes.