עבודה עם Meet eCDN On-Premises API

בדף הזה מוסבר איך להשתמש ב-API של רשת להעברת תוכן (eCDN) מקומית של Google Meet לשידור חי ב-Google Meet.

פתרון ה-API שמתואר כאן מאפשר ללקוחות להשתמש בכל התכונות של Meet eCDN בלי לחשוף ל-Google מידע על כתובות IP פרטיות. אתם יכולים להגדיר שירות אינטרנט חדש מקומי ברשת שלכם, שיעביר מזהה במקום את פרטי כתובת ה-IP הפרטית.

סקירה כללית של Meet eCDN

‫eCDN מובנה ב-Meet ומתחיל לפעול אוטומטית במהלך שידורים חיים אחרי שאדמין ב-Google Workspace מגדיר אותו. כש-eCDN מופעל ב-Meet, צופים בשידור חי ברשת מקומית יכולים לשתף מדיה בשידור חי עם עמיתים אחרים ברשת באמצעות שיתוף עמית לעמית (P2P). רוב המכשירים מקבלים את המדיה בשידור חי מעמיתים בסביבה הקרובה, ולא צריכים לאחזר אותה משרתי Google. כך מצמצמים את רוחב הפס הכולל שבו הצופים משתמשים. מידע נוסף על ההגדרה והשימוש ב-Meet eCDN זמין במאמר אירוח שידורים חיים מרובי-משתתפים.

כדי להשתמש ב-eCDN, הצופים בשידור החי ב-Meet צריכים להיות מסודרים בקבוצות של עמיתים. קבוצת עמיתים היא אוסף של צמתים שמורשים לשתף מדיה ביניהם. מכשירים בקבוצת שיתוף יכולים לשתף או להיות חסומים משיתוף. מכשירים מורשים יכולים להתחבר רק למכשירים אחרים באותה קבוצת עמיתים. מידע נוסף על קבוצות peering זמין במאמר לפני שמתחילים לארח שידורים חיים גדולים.

מתי כדאי להשתמש ב-API

‫eCDN יכול ליצור קבוצות של רשתות שכנות מקושרות באמצעות כמה סוגים שונים של מדיניות קישור בין רשתות שכנות: random,‏ subnet או custom rules. האפשרות השנייה משתפת טבלה של טווחי רשת פרטיים עם שרת המעקב של ה-eCDN של Google, כדי למפות כתובות IP פרטיות של כל צומת עמית לקבוצת עמיתים. המדיניות custom rules היא הפתרון המועדף ומתאימה לרוב סביבות הייצור.

עם זאת, custom rules המדיניות מחייבת אתכם לשתף עם Google חלקים גדולים ממבנה הרשת הפרטית שלכם. בנוסף, משתמשים פרטיים חושפים את כתובות ה-IP הפרטיות שלהם שזוהו באופן מקומי ל-Google בזמן השימוש ב-eCDN. יכול להיות שבהנחיות האבטחה של חלק מהארגונים לא מאפשרים שיתוף של מידע על כתובות IP פרטיות.

פיתוח באמצעות Meet eCDN On-Premises API

ממשק ה-API של Meet eCDN On-Premises מספק מפרט של שרת אינטרנט שאפשר להטמיע ולארח באופן מקומי ברשת של הארגון. אתם יכולים ליצור שירות אינטרנט בהתאמה אישית שתואם ל-API כדי לבצע את כל המשימות שתלויות במידע על כתובת IP פרטית, כך שהמידע לא ישותף עם Google.

ממשק ה-API כולל את שני השלבים הקריטיים להתאמת כתובות IP פרטיות, שבדרך כלל מטופלים על ידי שרת המעקב של ה-eCDN: מיפוי כתובות IP פרטיות לקבוצת עמיתים וחילופי נתונים של הצעות ותשובות של Session Description Protocol‏ (SDP) במהלך האיתות של WebRTC.

אחרי שיוצרים את שירות האינטרנט, צריך להגדיר את מסוף Admin לשימוש במדיניות של On-premises service peering ולכלול את כתובת ה-URL של שירות האינטרנט המותאם אישית.

דרישות

אם אתם צריכים להפעיל בארגון שלכם את אחת מהדרישות האלה, אתם יכולים לבקש מהאדמין ב-Google Workspace:

  • כל שרת אינטרנט שמשתמש ב-HTTPS יכול להטמיע את ה-API הזה.

  • כדאי להשתמש ב-HTTPS כדי למנוע כשלים בתוכן מעורב.

  • לקבל ולהחזיר נתוני JSON. להשתמש בכל קידוד תוכן שנתמך על ידי הדפדפן.

  • הצגת נקודות קצה במסלול /vn, כאשר n היא גרסת ה-API שנבחרה. לדוגמה: /v1/get-peering-group.

  • הצופים בשידור החי ב-Meet יכולים לראות את כתובת ה-URL של שירות האינטרנט שלכם דרך מסוף Google Admin. אפשר להגדיר את כתובת ה-URL באופן גלובלי, לכל יחידה ארגונית או לכל קבוצה. חשוב לוודא שהצופים יכולים להתחבר למופע השירות שהוקצה להם. מידע נוסף זמין במאמר בנושא הגדרת מסוף Admin.

  • השירות צריך להחזיר תשובה תוך שתי שניות. אחרת, לקוח ה-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 הפרטית לשרת ברשת ולבצע המרה ידנית לקבוצת peering באמצעות השיטה get-peering-group(). מזהה קבוצת הפירינג מוחזר בתשובה. כשמתקשרים עם Google, מועבר מזהה קבוצת הפירינג שנוצר במקום כתובות IP פרטיות.

איך כתובות IP פרטיות ממופות לקבוצת peering.
איור 1. מיפוי של כתובות IP פרטיות לקבוצת peering.

בדוגמה הבאה אפשר לראות איך קוראים לשיטה 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:
{
  "allowed": boolean,
  "result": string,
  "error": null,
}

בטבלה הבאה מוצגים פורמטים צפויים של תגובות:

סטטוס HTTP שגיאה מותר תוצאה תגובת הלקוח
200 null true מחרוזת לא ריקה הלקוח ימוין לקבוצת הפירינג שצוינה וימשיך להתחבר לשרת המעקב של ה-eCDN.
200 null false מחרוזת לא ריקה הלקוח מסומן כחסום על ידי קבוצת הפירינג שצוינה, הוא יוצג בכלי איכות השיחות ב-Meet‏ (MQT), והסשן ב-eCDN יסתיים.
200 null מחרוזת ריקה הלקוח מסיים את הסשן ב-eCDN.
200 מחרוזת לא ריקה הלקוח מסיים את הסשן ב-eCDN.
‫302 (נמצא) הלקוח עוקב אחרי ההפניה האוטומטית לכתובת ה-URL החדשה שצוינה בכותרת Location של גוף התגובה.
כל קוד סטטוס אחר הלקוח מסיים את הסשן ב-eCDN.

פורמט תשובות מדור קודם

השדה allowed לא היה חלק מפורמט התגובה בגרסאות קודמות. במקום זאת, ערכים מיוחדים שמורים ל-result יקבעו אם כתובת ה-IP של הצופה תיחסם מביצוע peering:

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

בטבלה הבאה מוצגים פורמטי התשובות הצפויים אם השדה allowed לא מוגדר בהודעת התשובה:

סטטוס HTTP שגיאה תוצאה תגובת הלקוח
200 null מחרוזת לא ריקה הלקוח צריך להיות ממוין לקבוצת עמיתים ולהמשיך להתחבר לשרת המעקב של ה-eCDN.
200 null NOT_FOUND הלקוח מסיים את הסשן ב-eCDN.
200 null BLOCKED הלקוח מסיים את הסשן ב-eCDN.
200 מחרוזת לא ריקה הלקוח מסיים את הסשן ב-eCDN.
‫302 (נמצא) הלקוח עוקב אחרי ההפניה האוטומטית לכתובת ה-URL החדשה שצוינה בכותרת Location של גוף התגובה.
כל קוד סטטוס אחר הלקוח מסיים את הסשן ב-eCDN.

החלפת נתונים של SDP offer-answer

כדי ליזום חיבור WebRTC, המכשירים צריכים להחליף ביניהם את הצעות ה-SDP והתשובות, כולל מועמדים ל-ICE‏ (Interactive Connectivity Establishment) שמכילים מידע על כתובות IP פרטיות. הם עושים זאת כחלק מתהליך האיתות של WebRTC.

לקוחות צריכים להצפין את מועמדי ה-ICE שלהם בתוך הרשת שלהם באמצעות Meet eCDN On-Premises API, באמצעות שיטת encrypt-sdp(). השיטה משתמשת במפתח שלא נחשף אף פעם ל-Google. הצעת ה-SDP המוצפנת נשלחת לעמית באמצעות שרת המעקב של ה-eCDN. לאחר מכן, עמית הלקוח מפענח את המידע שהתקבל בתוך הרשת שלו באמצעות השיטה decrypt-sdp(). לאחר מכן Google מעבירה את ההצעות והתשובות בין העמיתים המחוברים.

אחרי שנוצר החיבור באמצעות Meet eCDN On-Premises API, ה-eCDN פועל כרגיל. העמיתים מנתבים את המדיה דרך רשת ה-peering הרגילה, ותעבורת המדיה לא עוברת דרך ה-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 שגיאה מזהה קבוצת שותפים תגובת הלקוח
200 null מחרוזת לא ריקה הלקוח מצפה לשימוש בנתוני SDP מקודדים או מפוענחים בצורה תקינה.
200 כל מחרוזת לא ריקה null הלקוח מסיים את הסשן ב-eCDN.
‫302 (נמצא) הלקוח עוקב אחרי ההפניה האוטומטית לכתובת ה-URL החדשה שצוינה בכותרת Location של גוף התגובה.
כל קוד סטטוס אחר כל ערך כל ערך הלקוח מסיים את הסשן ב-eCDN.

הגדרת מסוף Admin

כדי להשתמש ב-Meet eCDN On-Premises API, צריך להגדיר את ה-eCDN ב מסוף Admin כך שיכלול את כתובת ה-URL של שירות האינטרנט המותאם אישית.

כדי להגדיר את ה-eCDN, יוצרים מדיניות קישור בין רשתות שכנות (peering) באמצעות On-premises service כדי להתאים באופן ידני את פרטי ה-IP לקבוצות של רשתות שכנות. אפשר גם לכלול מספר יציאה אם לא משתמשים ביציאה 443 שמוגדרת כברירת מחדל. כתובת ה-URL צריכה להיות בפורמט הבא: WEB_SERVICE.example.com:8080, כאשר WEB_SERVICE הוא שם שירות האינטרנט שלכם.

מידע נוסף על הגדרת מדיניות שיוך זמין במאמר הגדרת קיבוץ רשתות.