Utilizzare l'API Meet eCDN on-premise

Questa pagina spiega come utilizzare l'API on-premise della rete di distribuzione dei contenuti (eCDN) di Google Meet Enterprise per il live streaming di Google Meet.

La soluzione API descritta qui consente ai clienti di utilizzare l'intero set di funzionalità della eCDN di Meet senza esporre a Google informazioni sull'IP privato. Puoi definire un nuovo servizio web on-premise nella tua rete che trasmetta un ID anziché le informazioni sull'indirizzo IP privato.

Panoramica dell'eCDN Meet

L'eCDN è integrata in Meet e si avvia automaticamente durante i live streaming dopo che è stata configurata da un amministratore di Google Workspace. Quando l'eCDN Meet è attiva, gli spettatori del live streaming all'interno di una rete locale possono condividere contenuti multimediali in live streaming con altre app peer della rete tramite la condivisione peer-to-peer (P2P). La maggior parte dei dispositivi riceve i contenuti multimediali in live streaming da peer nelle vicinanze e non deve recuperarli dai server di Google. In questo modo si riduce la larghezza di banda totale utilizzata dagli spettatori. Per ulteriori informazioni sulla configurazione e sull'utilizzo di eCDN di Meet, consulta Ospitare live streaming di grandi dimensioni.

L'eCDN richiede che gli spettatori del live streaming di Meet vengano organizzati in gruppi di peering. Un gruppo di peering è una raccolta di nodi autorizzati a condividere contenuti multimediali tra loro. I dispositivi di un gruppo di peering possono essere autorizzati a eseguire il peering o bloccati. I dispositivi consentiti possono connettersi solo ad altri dispositivi nello stesso gruppo di peering. Per ulteriori informazioni sui gruppi di peering, consulta Prima di iniziare a ospitare live streaming di grandi dimensioni.

Quando utilizzare l'API

eCDN può formare gruppi di peering utilizzando diversi criteri di peering: random, subnet o custom rules. Quest'ultimo condivide una tabella di intervalli di rete privati con il server tracker eCDN di Google per mappare gli indirizzi IP privati di ogni nodo peer a un gruppo di peering. Il criterio custom rules è la soluzione preferita ed è adatto alla maggior parte degli ambienti di produzione.

Tuttavia, le norme di custom rules richiedono di condividere con Google ampie porzioni della tua struttura di rete privata. Inoltre, i singoli utenti espongono i propri indirizzi IP privati rilevati localmente a Google durante l'utilizzo di eCDN. Per alcune organizzazioni, le linee guida sulla sicurezza potrebbero non consentire la condivisione di informazioni su IP privati.

Sviluppare con l'API Meet eCDN on-premise

L'API Meet eCDN On-Premises fornisce una specifica del server web che puoi implementare e ospitare localmente nella rete della tua organizzazione. Puoi creare un servizio web personalizzato compatibile con l'API per eseguire tutte le attività dipendenti dalle informazioni IP private in modo che queste non vengano condivise con Google.

L'API comprende i due passaggi critici per l'associazione degli indirizzi IP privati che in genere vengono gestiti dal server tracker eCDN: mappare gli indirizzi IP privati a un gruppo di peering e scambio di dati di offerta/risposta del protocollo Session Description (SDP) durante il signaling WebRTC.

Una volta completato il servizio web, devi configurare la Console di amministrazione per utilizzare un criterio di peering On-premises service e includere l'URL del servizio web personalizzato.

Requisiti

Se hai bisogno che uno di questi requisiti venga attivato per la tua organizzazione, rivolgiti all'amministratore di Google Workspace:

  • Qualsiasi server web che utilizza HTTPS può implementare questa API.

  • Utilizza HTTPS per evitare errori relativi ai contenuti misti.

  • Accetta e restituisce dati JSON. Utilizza qualsiasi codifica dei contenuti supportata dal browser.

  • Pubblica gli endpoint in un route /vn, dove n è la versione dell'API selezionata. Ad esempio, /v1/get-peering-group.

  • Gli spettatori del live streaming di Meet possono conoscere l'URL del tuo servizio web tramite la Console di amministrazione Google. L'URL può essere impostato a livello globale, per unità organizzativa o per gruppo. Assicurati che gli spettatori possano collegarsi all'istanza del servizio assegnata. Per ulteriori informazioni, consulta Configurare la Console di amministrazione.

  • Il servizio dovrebbe restituire una risposta entro due secondi. In caso contrario, il client eCDN si arresta e lo spettatore continua a guardare l'evento dal vivo come utente normale non eCDN, senza alcun risparmio in termini di larghezza di banda.

  • Il servizio deve impostare le seguenti intestazioni CORS (Cross-Origin Resource Sharing):

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

Mappa gli indirizzi IP privati a un gruppo di peering

Il client eCDN effettua una chiamata ogni volta che tenta di riconnettersi al server di monitoraggio eCDN. Dopo che un dispositivo rileva un indirizzo IP privato, l'indirizzo deve essere mappato al gruppo di peering appropriato. Devi inviare l'indirizzo IP privato a un server sulla tua rete e risolverlo manualmente in un gruppo di peering utilizzando il metodo get-peering-group(). Nella risposta viene restituito un ID gruppo di peering. Quando comunichi con Google, viene passato l'ID gruppo di peering risultante anziché gli indirizzi IP privati.

Come vengono mappati gli indirizzi IP privati a un gruppo di peering.
Figura 1. Mappatura degli indirizzi IP privati a un gruppo di peering.

Il seguente esempio di codice mostra come chiamare il metodo get-peering-group() insieme alla potenziale risposta di errore e al corpo della risposta previsto:

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,
}

La tabella seguente mostra i formati di risposta previsti:

Stato HTTP Errore ID gruppo di peering Reazione del cliente
200 null Stringa non vuota Il client deve essere inserito in un gruppo di peering e deve procedere con la connessione al server di monitoraggio eCDN.
200 NOT_FOUND null Il client termina la sessione eCDN.
200 BLOCKED null Il client termina la sessione eCDN.
200 Altra stringa non vuota null Il client termina la sessione eCDN.
302 (Risultato trovato) Il client segue il reindirizzamento al nuovo URL specificato nell'intestazione Location del corpo della risposta.
Qualsiasi altro codice di stato Qualsiasi stringa Qualsiasi stringa Il client termina la sessione eCDN.

Scambio di dati di offerta e risposta SDP

Per avviare una connessione WebRTC, i dispositivi devono scambiarsi le offerte e le risposte SDP, inclusi i candidati ICE (Interactive Connectivity Establishment), che contengono informazioni sull'IP privato. Lo fanno nell'ambito del processo di scambio di indicatori WebRTC.

I client devono criptare i candidati ICE all'interno della rete tramite l'API Meet eCDN On-Premises, utilizzando il metodo encrypt-sdp(). Il metodo utilizza una chiave che non viene mai esposta a Google. L'offerta SDP criptata viene poi inviata al peer utilizzando il server tracker eCDN. Il peer client decripta quindi le informazioni ricevute all'interno della propria rete utilizzando il metodo decrypt-sdp(). Google poi gira le offerte e le risposte tra i peer collegati.

Una volta stabilita la connessione utilizzando l'API Meet eCDN on-premise, l'eCDN opererà normalmente. I peer indirizzano i contenuti multimediali tramite la normale rete di peering e il traffico multimediale non passa attraverso o non utilizza l'API.

Come vengono criptati e decriptati i dati delle offerte e delle risposte SDP.
Figura 2. Criptare e decriptare i dati delle offerte e delle risposte SDP.

Il seguente esempio di codice mostra come chiamare il metodo encrypt-sdp() insieme alla potenziale risposta di errore e al corpo della risposta previsto:

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,
}

Il seguente esempio di codice mostra come chiamare il metodo decrypt-sdp() insieme alla potenziale risposta di errore e al corpo della risposta previsto:

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,
}

La tabella seguente mostra i formati di risposta previsti:

Stato HTTP Errore ID gruppo di peering Reazione del cliente
200 null Stringa non vuota Il client si aspetta che vengano utilizzati dati SDP codificati o decodificati correttamente.
200 Qualsiasi stringa non vuota null Il client termina la sessione eCDN.
302 (Risultato trovato) Il client segue il reindirizzamento al nuovo URL specificato nell'intestazione Location del corpo della risposta.
Qualsiasi altro codice di stato Qualsiasi valore Qualsiasi valore Il client termina la sessione eCDN.

Configurare la Console di amministrazione

Per utilizzare l'API Meet eCDN on-premise, devi configurare l'eCDN nella Console di amministrazione in modo da includere l'URL del tuo servizio web personalizzato.

Per impostare l'eCDN, crea un criterio di peering utilizzando On-premises service per associare manualmente le informazioni IP ai gruppi di peering. Puoi anche includere un numero di porta se non utilizzi la porta predefinita 443. L'URL deve corrispondere al seguente formato: WEB_SERVICE.example.com:8080, dove WEB_SERVICE è il nome del tuo servizio web.

Per ulteriori informazioni sull'impostazione di un criterio di peering, consulta Configurare il raggruppamento di reti.