Trabalhar com a API Meet eCDN On-Prem

Esta página explica como usar a API On-Premises da rede de fornecimento de conteúdo Enterprise (eCDN) do Google Meet para a transmissão ao vivo do Google Meet.

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

Informações gerais sobre a 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 por 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 Como hospedar transmissões ao vivo para grandes públicos.

A eCDN exige que os espectadores da transmissão ao vivo do Meet sejam organizados 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 dispositivos 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 de peering diferentes: random, subnet ou custom rules. O segundo compartilha uma tabela de intervalos de rede privada com o servidor de rastreamento do eCDN do Google para mapear endereços IP privados de cada nó de peer para um grupo de peering. A política custom rules é a solução recomendada e é adequada para a maioria dos ambientes de produção.

No entanto, a política custom rules exige que você compartilhe grandes partes da sua estrutura de rede privada 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 particulares.

Desenvolver com a API local do Meet eCDN

A API Meet eCDN local 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 privadas, para que as informações não sejam compartilhadas com o Google.

A API inclui as duas etapas essenciais para a correspondência de endereços IP particulares que geralmente são processadas pelo servidor de rastreamento do eCDN: mapear endereços IP particulares para um grupo de peering e troca de dados de oferta-resposta do Protocolo de Descrição de Sessão (SDP, na sigla em inglês) durante a sinalização do WebRTC.

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

Requisitos

Se você precisar ativar algum desses requisitos para sua organização, peça ao administrador do Google Workspace:

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

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

  • Aceitar e retornar 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 do Meet ao vivo podem saber mais sobre o URL do seu serviço da Web no Google Admin Console. O URL pode ser definido globalmente, por unidade organizacional ou por grupo. Verifique se os espectadores conseguem 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á encerrado, e o espectador continuará assistindo o evento ao vivo como um usuário normal, sem a eCDN, negando a economia de largura de banda.

  • Seu serviço precisa definir os seguintes cabeçalhos de compartilhamento de recursos entre origens (CORS):

    • 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 eCDN faz uma chamada sempre que tenta se reconectar ao servidor de rastreador do eCDN. Depois que um dispositivo detecta um endereço IP privado, o endereço 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 privados para um grupo de peering.

O exemplo de código abaixo mostra como chamar o método get-peering-group() com a possível resposta de erro e o corpo de 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:
{
  "result": "PEERING_GROUP_ID",
  "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 precisa ser classificado em um grupo de peering e se conectar ao servidor do rastreador da eCDN.
200 NOT_FOUND null O cliente encerra a sessão da eCDN.
200 BLOCKED null O cliente encerra a sessão da eCDN.
200 Outra 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 string Qualquer string O cliente encerra a sessão da eCDN.

Troca de dados de oferta-resposta do SDP

Para iniciar uma conexão WebRTC, os dispositivos precisam trocar as ofertas e respostas de SDP, incluindo candidatos de estabelecimento de conectividade interativa (ICE, na sigla em inglês), que contêm informações de IP particular. Isso é feito como parte do processo de sinalização do WebRTC.

Os clientes precisam criptografar os candidatos do ICE na rede usando a API Meet eCDN local, com o método encrypt-sdp(). O método usa uma chave que nunca é exposta ao Google. A oferta SDP criptografada é enviada ao peer usando o servidor de rastreador do eCDN. O peer 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 pares conectados.

Depois que a conexão é estabelecida usando a API local da eCDN do Meet, a eCDN opera normalmente. Os pares roteiam mídia pela rede de peering usual, e o tráfego de mídia não passa pela API nem a usa.

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

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

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

Request body:
{
  "data": "SDP_DATA" // raw SDP data
},

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

Response body:
{
  "result": "ENCRYPTED_DATA_STRING", // encrypted data as 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 de resposta esperado:

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

Request body:
{
  "data": "ENCRYPTED_DATA_STRING", // encrypted data as string (size limit: 1 MB)
},

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

Response body:
{
  "result": "SDP_DATA" // raw 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 SDP sejam usados corretamente codificados ou decodificados.
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 local do eCDN do Meet, é necessário configurar o eCDN no Admin Console para incluir o URL do seu serviço da Web personalizado.

Para definir o eCDN, crie uma política de peering usando On-premises service para associar manualmente informações de IP a grupos de peering. Você também pode incluir um número de porta se não estiver usando o 443 padrão. 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.