Utiliser l'API Meet eCDN sur site

Cette page explique comment utiliser l'API Google Meet Enterprise Content Delivery Network (eCDN) On-Premises pour le streaming en direct Google Meet.

La solution d'API décrite ici permet aux clients d'utiliser l'ensemble des fonctionnalités de Meet eCDN sans exposer d'informations d'adresse IP privée à Google. Vous pouvez définir un nouveau service Web sur site dans votre propre réseau qui transmet un ID au lieu des informations d'adresse IP privée.

Présentation de Meet eCDN

eCDN est intégré à Meet et démarre automatiquement lors des diffusions en direct après qu'un administrateur Google Workspace l'a configuré. Lorsque Meet eCDN est activé, les spectateurs d'une diffusion en direct sur un réseau local peuvent partager des contenus diffusés en direct avec d'autres utilisateurs du réseau via le partage peer-to-peer (P2P). La plupart des appareils reçoivent les contenus diffusés en direct de pairs à proximité et n'ont pas besoin de les récupérer sur les serveurs de Google. Cela réduit la bande passante totale utilisée par les spectateurs. Pour en savoir plus sur la configuration et l'utilisation de Meet eCDN, consultez Héberger des diffusions en direct de grande envergure.

eCDN nécessite que les spectateurs du streaming en direct Meet soient regroupés en groupes d'appairage. Un groupe d'appairage est un ensemble de nœuds autorisés à partager des contenus multimédias entre eux. Les appareils d'un groupe d'appairage peuvent être autorisés ou bloqués pour l'appairage. Les appareils autorisés ne peuvent se connecter qu'à d'autres appareils du même groupe d'appairage. Pour en savoir plus sur les groupes d'appairage, consultez Avant de commencer à héberger des diffusions en direct de grande envergure.

Quand utiliser l'API ?

eCDN peut former des groupes d'appairage à l'aide de plusieurs règles d'appairage différentes : random, subnet ou custom rules. Cette dernière partage un tableau de plages de réseau privé avec le serveur de suivi eCDN de Google pour mapper les adresses IP privées de chaque nœud pair à un groupe d'appairage. La règle custom rules est la solution privilégiée et convient à la plupart des environnements de production.

Toutefois, la règle custom rules vous oblige à partager de grandes parties de la structure de votre réseau privé avec Google. De plus, les utilisateurs individuels exposent leurs adresses IP privées détectées localement à Google lorsqu'ils utilisent eCDN. Pour certaines organisations, leurs consignes de sécurité peuvent interdire le partage d'informations d'adresse IP privée.

Développer avec l'API Meet eCDN On-Premises

L'API Meet eCDN On-Premises fournit une spécification de serveur Web que vous pouvez implémenter et héberger localement dans le réseau de votre organisation. Vous pouvez créer un service Web personnalisé compatible avec l'API pour effectuer toutes les tâches dépendant des informations d'adresse IP privée afin que ces informations ne soient pas partagées avec Google.

L'API englobe les deux étapes essentielles pour faire correspondre les adresses IP privées qui sont généralement gérées par le serveur de suivi eCDN : mapper les adresses IP privées à un groupe d'appairage et échanger des données d'offre-réponse du protocole de description de session (SDP, Session Description Protocol) lors de la signalisation WebRTC.

Une fois le service Web terminé, vous devez configurer la console d'administration pour utiliser une règle d'appairage On-premises service et inclure l'URL de votre service Web personnalisé.

Conditions requises

Si vous avez besoin d'activer l'une de ces conditions requises pour votre organisation, demandez à votre administrateur Google Workspace :

  • Tout serveur Web utilisant HTTPS peut implémenter cette API.

  • Utilisez HTTPS pour éviter les échecs de contenu mixte.

  • Acceptez et renvoyez des données JSON. Utilisez n'importe quel encodage de contenu compatible avec votre navigateur.

  • Diffusez des points de terminaison sous une route /vn, où n correspond à la version d'API sélectionnée. Exemple : /v1/get-peering-group.

  • Les spectateurs du streaming en direct Meet peuvent en savoir plus sur l'URL de votre service Web via la console d'administration Google. L'URL peut être définie globalement, par unité organisationnelle ou par groupe. Assurez-vous que les spectateurs peuvent se connecter à l'instance du service qui leur est attribuée. Pour en savoir plus, consultez Configurer la console d'administration.

  • Votre service doit renvoyer une réponse dans un délai de deux secondes. Sinon, le client eCDN s'arrête et le spectateur continue de regarder l'événement en direct en tant qu'utilisateur normal, non eCDN, ce qui lui refuse toute économie de bande passante.

  • Votre service doit définir les en-têtes de partage des ressources entre origines multiples (CORS, Cross-Origin Resource Sharing) suivants :

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

Mapper les adresses IP privées à un groupe d'appairage

Le client eCDN effectue un appel chaque fois qu'il tente de se reconnecter au serveur de suivi eCDN. Une fois qu'un appareil détecte une adresse IP privée, celle-ci doit être mappée au groupe d'appairage approprié. Vous devez envoyer l'adresse IP privée à un serveur de votre réseau et la résoudre manuellement en un groupe d'appairage à l'aide de la méthode get-peering-group(). Un ID de groupe d'appairage est renvoyé dans la réponse. Lors de la communication avec Google, l'ID de groupe d'appairage résultant est transmis à la place des adresses IP privées.

Comment les adresses IP privées sont mappées à un groupe de peering.
Figure 1 : Mapper les adresses IP privées à un groupe d'appairage

L'exemple de code suivant montre comment appeler la méthode get-peering-group() avec la réponse d'erreur potentielle et le corps de réponse attendu :

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
}

Le tableau suivant présente les formats de réponse attendus :

État HTTP Erreur Autorisé Résultat Réaction du client
200 null true Chaîne non vide Le client est trié dans le groupe d'appairage spécifié et se connecte au serveur de suivi eCDN.
200 null faux Chaîne non vide Le client est marqué comme bloqué par le groupe d'appairage spécifié, sera visible dans l'outil de qualité Meet (MQT) et met fin à la session eCDN.
200 null Chaîne vide Le client met fin à la session eCDN.
200 Chaîne non vide Le client met fin à la session eCDN.
302 (Found) Le client suit la redirection vers la nouvelle URL spécifiée dans l'en-tête Location du corps de réponse.
Tout autre code d'état Le client met fin à la session eCDN.

Format de réponse hérité

Le champ allowed ne faisait pas partie du format de réponse des versions antérieures. Au lieu de cela, des valeurs réservées spéciales pour result déterminaient si l'adresse IP d'un spectateur était bloquée pour l'appairage :

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

Le tableau suivant présente les formats de réponse attendus si le champ allowed n'est pas défini dans le message de réponse :

État HTTP Erreur Résultat Réaction du client
200 null Chaîne non vide Le client doit être trié dans un groupe d'appairage et se connecter au serveur de suivi eCDN.
200 null NOT_FOUND Le client met fin à la session eCDN.
200 null BLOCKED Le client met fin à la session eCDN.
200 Chaîne non vide Le client met fin à la session eCDN.
302 (Found) Le client suit la redirection vers la nouvelle URL spécifiée dans l'en-tête Location du corps de réponse.
Tout autre code d'état Le client met fin à la session eCDN.

Échange de données d'offre-réponse SDP

Pour lancer une connexion WebRTC, les appareils doivent échanger leurs offres et réponses SDP, y compris les candidats ICE (Interactive Connectivity Establishment), qui contiennent des informations d'adresse IP privée. Ils le font dans le cadre du processus de signalisation WebRTC.

Les clients doivent chiffrer leurs candidats ICE dans leur réseau via l'API Meet eCDN On-Premises, à l'aide de la méthode encrypt-sdp(). La méthode utilise une clé qui n'est jamais exposée à Google. L'offre SDP chiffrée est ensuite envoyée au pair à l'aide du serveur de suivi eCDN. Le pair client déchiffre ensuite les informations reçues dans son réseau à l'aide de la méthode decrypt-sdp(). Google transfère ensuite les offres et les réponses entre les pairs connectés.

Une fois la connexion établie à l'aide de l'API Meet eCDN On-Premises, eCDN fonctionne normalement. Les pairs acheminent les contenus multimédias via le réseau d'appairage habituel, et le trafic multimédia ne transite pas par l'API et ne l'utilise pas.

Comment les données d'offre et de réponse SDP sont chiffrées et déchiffrées.
Figure 2 : Chiffrer et déchiffrer les données d'offre et de réponse SDP

L'exemple de code suivant montre comment appeler la méthode encrypt-sdp() avec la réponse d'erreur potentielle et le corps de réponse attendu :

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
}

L'exemple de code suivant montre comment appeler la méthode decrypt-sdp() avec la réponse d'erreur potentielle et le corps de réponse attendu :

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
}

Le tableau suivant présente les formats de réponse attendus :

État HTTP Erreur ID du groupe d'appairage Réaction du client
200 null Chaîne non vide Le client s'attend à ce que des données SDP correctement encodées ou décodées soient utilisées.
200 Toute chaîne non vide null Le client met fin à la session eCDN.
302 (Found) Le client suit la redirection vers la nouvelle URL spécifiée dans l'en-tête Location du corps de réponse.
Tout autre code d'état N'importe quelle valeur N'importe quelle valeur Le client met fin à la session eCDN.

Configurer la console d'administration

Pour utiliser l'API Meet eCDN On-Premises, vous devez configurer eCDN dans la console d'administration pour inclure l'URL de votre service Web personnalisé.

Pour définir eCDN, créez une règle d'appairage à l'aide de On-premises service afin de faire correspondre manuellement les informations d'adresse IP aux groupes d'appairage. Vous pouvez également inclure un numéro de port si vous n'utilisez pas le port 443 par défaut. L'URL doit correspondre au format suivant : WEB_SERVICE.example.com:8080, où WEB_SERVICE correspond au nom de votre service Web.

Pour en savoir plus sur la définition d'une règle d'appairage, consultez Configurer le regroupement de réseaux.