使用 Meet eCDN On-Premises API

本頁面說明如何使用 Google Meet Enterprise 內容傳遞聯播網 (eCDN) 的內部 API，為 Google Meet 直播串流服務提供服務。

這裡介紹的 API 解決方案可讓客戶使用 Meet eCDN 的完整功能組合，而無須向 Google 揭露私人 IP 資訊。您可以在自己的網路中定義新的內部部署網路服務，傳遞 ID 而非私人 IP 位址資訊。

Meet eCDN 總覽

eCDN 已內建於 Meet，並會在 Google Workspace 管理員設定後，於直播期間自動啟動。開啟 Meet eCDN 後，區域網路中的直播觀眾就能透過點對點 (P2P) 分享功能，與網路中的其他觀眾分享直播媒體內容。大多數裝置都會接收附近對等裝置的直播媒體，這樣就不必從 Google 伺服器擷取媒體。這麼做可降低觀眾使用的總頻寬。如要進一步瞭解如何設定及使用 Meet eCDN，請參閱「舉辦大型直播」。

eCDN 要求 Meet 直播觀眾必須排入對等群組。對接群組是一組可以互相共用媒體的節點。對接群組中的裝置可允許/禁止彼此對接。允許的裝置只能與同一個對接群組中的其他裝置連線。如要進一步瞭解對等群組，請參閱「舉辦大型直播活動的前置作業」。

使用 API 的時機

eCDN 可使用以下幾種不同的對等互連政策，建立對等互連群組：random、subnet 或 custom rules。後者會將私人網路範圍表格與 Google 的 eCDN 追蹤器伺服器共用，將每個對等節點的私人 IP 位址對應至對等互連群組。custom rules 政策是首選解決方案，適用於大多數正式環境。

不過，custom rules 政策要求您將私人網路結構的大部分內容與 Google 分享。此外，使用者在使用 eCDN 時，也會將在本機偵測到的私人 IP 位址提供給 Google。部分機構的安全指南可能不允許分享私人 IP 資訊。

使用 Meet eCDN 內部部署 API 進行開發

Meet eCDN 內部 API 提供網路伺服器規格，可在貴機構的網路中本地實作及代管。您可以建構與 API 相容的自訂網路服務，執行所有依賴私人 IP 資訊的作業，這樣就不會將資訊分享給 Google。

這個 API 包含兩個關鍵步驟，用於比對私人 IP 位址，這些步驟通常由 eCDN 追蹤器伺服器處理：將私人 IP 位址對應至對等互連群組，以及在 WebRTC 訊號期間使用會話描述協定 (SDP) 提供/回應資料交換。

網路服務完成後，您必須設定管理控制台，以便使用 On-premises service 對等連線政策，並納入自訂網路服務的網址。

需求條件

如果您需要為貴機構啟用下列任何規定，請洽詢 Google Workspace 管理員：

  • 任何使用 HTTPS 的網頁伺服器都可以實作這個 API。

  • 使用 HTTPS 可避免混合內容失敗。

  • 接受及傳回 JSON 資料。使用瀏覽器支援的任何內容編碼。

  • 在 /vn 路徑下提供端點，其中 n 是所選 API 版本。例如：/v1/get-peering-group

  • Meet 直播觀眾可以透過 Google 管理控制台瞭解您的網路服務網址。您可以為整個機構、每個機構單位或每個群組設定網址。請確認觀眾可以連線至服務的指定執行個體。詳情請參閱「設定管理控制台」。

  • 您的服務應在兩秒內傳回回應。否則，eCDN 用戶端會關閉，觀眾會以一般非 eCDN 使用者的身分繼續觀看直播活動，無法節省頻寬。

  • 您的服務必須設定下列跨來源資源共享 (CORS) 標頭：

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

將私人 IP 位址對應至對等群組

eCDN 用戶端每次嘗試重新連線至 eCDN 追蹤工具伺服器時，都會發出呼叫。裝置偵測到私人 IP 位址後，該位址必須對應至適當的對等群組。您必須將私人 IP 位址傳送至網路上的伺服器，然後使用 get-peering-group() 方法手動將其解析為對等群組。回應中會傳回對等群組 ID。與 Google 通訊時，系統會傳遞產生的對等群組 ID，而非私人 IP 位址。

私人 IP 位址如何對應至對等群組。
圖 1. 將私人 IP 位址對應至對等群組。

下列程式碼範例說明如何呼叫 get-peering-group() 方法，以及可能的錯誤回應和預期的回應主體：

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

下表列出預期的回應格式：

HTTP 狀態 錯誤 對等互連群組 ID 用戶端回應
200 null 非空字串 用戶端應分類至對等群組，並繼續連線至 eCDN 追蹤工具伺服器。
200 NOT_FOUND null 用戶端終止 eCDN 工作階段。
200 BLOCKED null 用戶端終止 eCDN 工作階段。
200 其他非空白字串 null 用戶端終止 eCDN 工作階段。
302 (已找到) 用戶端會依循重新導向，前往回應主體 Location 標頭中指定的新網址。
任何其他狀態碼 任何字串 任何字串 用戶端終止 eCDN 工作階段。

SDP 優惠-回覆資料交換

如要啟動 WebRTC 連線，裝置必須交換 SDP 提供項目和答案，包括互動連線建立 (ICE) 候選項目，這些項目都包含私人 IP 資訊。這屬於 WebRTC 信號傳送程序的一部分。

用戶端必須使用 encrypt-sdp() 方法，透過 Meet eCDN 內部 API 在網路中加密 ICE 候選項目。這個方法會使用從未向 Google 公開的金鑰。然後使用 eCDN 追蹤器伺服器，將經過加密的 SDP 優惠傳送至對等端。接著，用戶端同端會使用 decrypt-sdp() 方法，在其網路中解密收到的資訊。接著，Google 會將優惠和答案轉寄給已連結的使用者。

使用 Meet eCDN 內部 API 建立連線後，eCDN 就會正常運作。對等端會透過一般對等網路轉送媒體，且媒體流量不會經過或使用 API。

如何加密及解密 SDP 優惠和答案資料。
圖 2. 加密及解密 SDP 優惠和回應資料。

以下程式碼範例說明如何呼叫 encrypt-sdp() 方法，以及可能的錯誤回應和預期的回應主體：

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

以下程式碼範例說明如何呼叫 decrypt-sdp() 方法，以及可能的錯誤回應和預期的回應主體：

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

下表列出預期的回應格式：

HTTP 狀態 錯誤 對等互連群組 ID 用戶端回應
200 null 非空字串 用戶端會預期使用已正確編碼或解碼的 SDP 資料。
200 任何非空白字串 null 用戶端終止 eCDN 工作階段。
302 (已找到) 用戶端會依循重新導向，前往回應主體 Location 標頭中指定的新網址。
任何其他狀態碼 任何值 任何值 用戶端終止 eCDN 工作階段。

設定管理控制台

如要使用 Meet eCDN 內部 API，您必須在 管理控制台中設定 eCDN，納入自訂網頁服務的網址。

如要設定 eCDN，請使用 On-premises service 建立對等互連政策，以便手動將 IP 資訊比對至對等互連群組。如果您未使用預設的 443，也可以加入通訊埠號碼。網址格式應符合下列格式：WEB_SERVICE.example.com:8080，其中 WEB_SERVICE 是您的網路服務名稱。

如要進一步瞭解如何設定對等連線政策，請參閱「設定網路分組」。