Utiliser l'API Meet eCDN sur site

Cette page explique comment utiliser l'API sur site de l'eCDN (Enterprise Content Delivery Network) Google Meet 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 l'eCDN Meet sans exposer d'informations IP privées à 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 l'eCDN Meet

L'eCDN est intégré à Meet et démarre automatiquement pendant les diffusions en direct une fois qu'un administrateur Google Workspace l'a configuré. Lorsque l'eCDN Meet 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 P2P (peer-to-peer). La plupart des appareils reçoivent les contenus multimédias 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 Organiser de grandes diffusions en direct.

eCDN nécessite que les spectateurs de la diffusion en direct Meet soient classés dans des groupes de mise en pairage. 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 la section Avant de commencer à diffuser de grandes diffusions en direct.

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. Ce dernier partage un tableau de plages de réseaux privés avec le serveur de suivi eCDN de Google pour mapper les adresses IP privées de chaque nœud de pairage à un groupe de pairage. La règle custom rules est la solution privilégiée et convient à la plupart des environnements de production.

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

Développer avec l'API Meet eCDN sur site

L'API Meet eCDN sur site fournit une spécification de serveur Web que vous pouvez implémenter et héberger localement sur 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épendantes des informations IP privées afin qu'elles ne soient pas partagées avec Google.

L'API comprend 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 sur un groupe d'appariement et échanger des données d'offre-réponse 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 stratégie d'association On-premises service et inclure l'URL de votre service Web personnalisé.

Conditions requises

Si vous avez besoin que l'une de ces exigences soit activée pour votre organisation, demandez à votre administrateur Google Workspace:

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

  • Utilisez HTTPS pour éviter les erreurs liées au contenu mixte.

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

  • Servez des points de terminaison sous un itinéraire /vn, où n est la version de l'API sélectionnée. Exemple : /v1/get-peering-group.

  • Les spectateurs de Meet Live Streaming 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 la section 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 standard, sans eCDN, ce qui lui interdit toute économie de bande passante.

  • Votre service doit définir les en-têtes 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

Mappeur d'adresses IP privées sur 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 a détecté une adresse IP privée, celle-ci doit être mappée au bon groupe d'appariement. 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 de peering 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. Mappage des adresses IP privées sur un groupe d'appairage.

L'exemple de code suivant montre comment appeler la méthode get-peering-group(), ainsi que 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:
{
  "result": "PEERING_GROUP_ID",
  "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 doit être trié dans un groupe d'appariement et se connecter au serveur de suivi de l'eCDN.
200 NOT_FOUND null Le client met fin à la session eCDN.
200 BLOCKED null Le client met fin à la session eCDN.
200 Autre chaîne non vide null Le client met fin à la session eCDN.
302 (Trouvé) Le client suit la redirection vers la nouvelle URL spécifiée dans l'en-tête Location du corps de la réponse.
Tout autre code d'état N'importe quelle chaîne N'importe quelle chaîne Le client met fin à la session eCDN.

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

Pour établir 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 sur site, à l'aide de la méthode encrypt-sdp(). La méthode utilise une clé qui n'est jamais divulgué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 sur 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 sur site, l'eCDN fonctionne normalement. Les pairs acheminent les contenus multimédias via le réseau de peering habituel, et le trafic multimédia ne passe pas par l'API et ne l'utilise pas.

Comment les données de l'offre et de la réponse SDP sont chiffrées et déchiffrées.
Figure 2. Chiffrement et déchiffrement des données d'offre et de réponse SDP

L'exemple de code suivant montre comment appeler la méthode encrypt-sdp(), ainsi que 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" // raw SDP data
},

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

Response body:
{
  "result": "ENCRYPTED_DATA_STRING", // encrypted data as string
  "error": null,
}

L'exemple de code suivant montre comment appeler la méthode decrypt-sdp(), ainsi que 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", // 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,
}

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 N'importe quelle chaîne non vide null Le client met fin à la session eCDN.
302 (Trouvé) Le client suit la redirection vers la nouvelle URL spécifiée dans l'en-tête Location du corps de la réponse.
Tout autre code d'état N'importe quelle valeur N'importe quelle valeur Le client met fin à la session eCDN.

Configuration de la console d'administration

Pour utiliser l'API Meet eCDN sur site, vous devez configurer l'eCDN dans la console d'administration afin d'inclure l'URL de votre service Web personnalisé.

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

Pour en savoir plus sur la configuration d'une stratégie d'appairage, consultez Configurer le regroupement de réseaux.