使用 Meet eCDN On-Premises API

本頁說明如何使用 Google Meet Enterprise 內容傳遞聯播網 (eCDN) On-Premises API，透過 Google Meet 直播。

本文所述的 API 解決方案可讓客戶使用 Meet eCDN 的完整功能組合，同時不會向 Google 揭露私人 IP 資訊。您可以在自己的網路中定義新的地端部署網路服務，傳遞 ID 而非私人 IP 位址資訊。

Meet eCDN 總覽

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

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

API 的使用時機

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

不過，custom rules 政策規定您必須與 Google 分享大部分的私人網路結構。此外，使用 eCDN 時，個別使用者會向 Google 揭露本地偵測到的私人 IP 位址。部分機構的安全規範可能不允許分享私人 IP 資訊。

使用 Meet eCDN On-Premises API 進行開發

Meet eCDN On-Premises API 提供網頁伺服器規格，您可以在貴機構的網路中實作及代管。您可以建構與 API 相容的自訂網路服務，執行所有需要私人 IP 資訊的作業，這樣資訊就不會與 Google 分享。

API 涵蓋兩個重要步驟，可比對通常由 eCDN 追蹤伺服器處理的私人 IP 位址：將私人 IP 位址對應至對等互連群組，以及在 WebRTC 信號傳輸期間交換 Session Description Protocol (SDP) 提議/回應資料。

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

需求條件

如要為貴機構啟用上述任一規定，請洽詢 Google Workspace 管理員：

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

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

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

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

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

  • 服務應在兩秒內傳回回應。否則 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 null NOT_FOUND 用戶端結束 eCDN 工作階段。
200 null BLOCKED 用戶端結束 eCDN 工作階段。
200 其他非空字串 null 用戶端結束 eCDN 工作階段。
302 (已找到) 用戶端會按照重新導向，前往回應主體 Location 標頭中指定的新網址。
任何其他狀態碼 任何字串 任何字串 用戶端結束 eCDN 工作階段。

SDP 提議/答覆資料交換

如要啟動 WebRTC 連線，裝置必須交換 SDP 提議和回覆，包括含有私人 IP 資訊的互動式連線建立 (ICE) 候選項目。他們會在 WebRTC 信號傳輸程序中執行這項操作。

用戶端必須透過 Meet eCDN On-Premises API，使用 encrypt-sdp() 方法加密網路內的 ICE 候選項目。這個方法使用的金鑰絕不會洩漏給 Google。然後，系統會使用 eCDN 追蹤器伺服器，將加密的 SDP 提議傳送給對等互連裝置。接著，用戶端對等互連裝置會使用 decrypt-sdp() 方法，在網路內解密收到的資訊。Google 接著會在連線的對等互連裝置之間轉送要約和答案。

使用 Meet eCDN On-Premises 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 On-Premises API，請在 管理控制台中設定 eCDN，並加入自訂網路服務的網址。

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

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