הגדרת נתיבי שירות

‫Media CDN מספקת יכולות מתקדמות של ניתוב HTTP שמאפשרות לכם למפות תנועה לתצורות קצה ולמקורות ספציפיים ברמה מפורטת.

הגדרת כלל ניתוב

הגדרת כלל ניתוב לשירות Media CDN.

המסוף

  1. נכנסים לדף Media CDN במסוף Google Cloud .

    מעבר אל Media CDN

  2. כדי לפתוח את הדף פרטים של השירות שרוצים להגדיר עבורו כלל ניתוב, לוחצים על שם השירות.

  3. כדי לעבור למצב עריכה, לוחצים על הלחצן עריכה.

  4. כדי לעבור לקטע ניתוב, לוחצים על הבא.

  5. צריך לציין לפחות כלל אחד של מארח. לוחצים על הוספת כלל של מארח. לאחר מכן, מבצעים את הפעולות הבאות:

    1. בקטע מארחים, מציינים לפחות מארח אחד להתאמה.

    2. בקטע תיאור, צריך להזין תיאור קצר של כלל המארח.

    לחלופין, כדי לערוך כלל של מארח, לוחצים על החץ כדי להרחיב אותו.

  6. צריך לציין לפחות כלל ניתוב אחד. לוחצים על הוספת כלל ניתוב.

    לחלופין, כדי לערוך כלל ניתוב, לוחצים על עריכה בשורה הרלוונטית.

  7. בחלונית עריכת כלל ניתוב, בשדה עדיפות, מגדירים ערך לעדיפות הניתוב.

  8. בקטע תיאור, מזינים תיאור קצר שיעזור לזהות את הכלל ברשימת הכללים.

  9. בקטע התאמה, מציינים לפחות תנאי התאמה אחד. לוחצים על הוספת תנאי התאמה. לאחר מכן, מבצעים את הפעולות הבאות:

    1. בקטע סוג התאמה, בוחרים באחת מהאפשרויות של התאמה לנתיב.

    2. בהתאמה לנתיב מציינים את השמות, הנתיבים או התבניות. מומלץ להשתמש בהתאמת דוגמת עיצוב של תווים כלליים לחיפוש.

      אם צריך, בוחרים גם באפשרות הפעלת תלות באותיות רישיות עבור ערך הנתיב.

    3. אופציונלי: בוחרים באפשרות הכותרות זהות והפרמטרים של השאילתה זהים. לאחר מכן, לוחצים על הכפתורים הרלוונטיים כדי להוסיף כותרות ופרמטרים של שאילתות. לכל פרמטר מציינים את השם, סוג ההתאמה והערך.

      מידע נוסף זמין במאמר התאמה של כותרות ופרמטרים של שאילתות.

    4. כדי לשמור את תנאי ההתאמה, לוחצים על סיום.

  10. בקטע פעולה ראשית, בוחרים באחת מהאפשרויות הבאות:

    • שליפה ממקור: כדי להפנות בקשות למקור ספציפי, בוחרים באפשרות הזו ואז בוחרים מקור.

    • הפניה לכתובת URL אחרת: כדי להפנות בקשות, בוחרים באפשרות הזו. לאחר מכן, מציינים את סוג ההפניה האוטומטית, הנתיב וקוד הסטטוס.

      אופציונלי: בוחרים באפשרות הפניה אוטומטית של כל התשובות ל-HTTPS או באפשרות להסרת השאילתה.

  11. לוחצים על הגדרות מתקדמות.

    1. בקטע Header action (פעולה בכותרת), לוחצים על Add an item (הוספת פריט).

      בוחרים סוג פעולה ומציינים כותרת כצמד של שם וערך. לאחר מכן, לוחצים על סיום.

    2. בקטע פעולת ניתוב, לוחצים על הוספת פריט.

      מציינים את סוג הפעולה ואת האפשרויות שקשורות אליה. לאחר מכן, לוחצים על סיום.

  12. בקטע HTTP method filtering (סינון לפי שיטת HTTP), בוחרים באפשרות Customize HTTP method filtering (התאמה אישית של סינון לפי שיטת HTTP).

    לאחר מכן, בוחרים את השיטות של HTTP שרוצים להעביר דרך ה-proxy למקור.

  13. כדי לשמור את כלל הניתוב, לוחצים על שמירה.

  14. כדי לשמור את השינויים בשירות, לוחצים על עדכון השירות.

‫gcloud ו-YAML

  1. מייצאים את ההגדרה של Media CDN לקובץ YAML. משתמשים בפקודה gcloud edge-cache services export.

    gcloud edge-cache services export SERVICE_NAME \
    --destination=FILENAME.yaml

    מחליפים את מה שכתוב בשדות הבאים:

    • ‫SERVICE_NAME: השם של השירות
    • ‫FILENAME : השם של קובץ ה-YAML

  2. מעדכנים את קובץ ה-YAML עם ההגדרות הנדרשות, כמו שמתואר בקטעים שבדף הזה.

  3. כדי לעדכן את השירות, מייבאים את ההגדרה של Media CDN מקובץ ה-YAML. משתמשים בפקודה gcloud edge-cache services import.

    gcloud edge-cache services import SERVICE_NAME \
    --source=FILENAME.yaml

בקשות להתאמה

הגדרה של Media CDN מכילה קבוצה של מסלולים שמוגדרים בקטע Routing של משאב EdgeCacheService. המסלולים האלה תואמים לבקשות על סמך מארח (לפחות). לפרטים נוספים על ניתוב תעבורה למקור, אפשר לעיין במאמרים HostRule וPathMatcher. לכל מסלול אפשר להגדיר הגדרות CDN משלו, שינויים, הפניות מחדש, מדיניות CORS, כותרות HTTP בהתאמה אישית ומיפוי מקורות. יכול להיות שלמסלולים שונים יש נקודת מוצא משותפת.

לדוגמה, אתם יכולים לנתב בקשות למניפסטים למקור ספציפי ולהגדיר TTL קצר למטמון ומדיניות שלילית של שמירה במטמון. אפשר לפצל בקשות לפלחים למקור אחר באמצעות כותרות ופרמטרים של שאילתות כדי להפריד סוגים ספציפיים של מניפסטים או משתמשים.

בדוגמה הבאה מוצג ניתוב של בקשות שתואמות לכותרת ספציפית, לפרמטר שאילתה ולקידומת נתיב עבור המארח media.example.com:

name: prod-service
routing:
  hostRules:
  - hosts:
    - media.example.com
    pathMatcher: example_routes
  pathMatchers:
  - name: example_routes
    routeRules:
    - priority: 10
      origin: staging-live-origin
      matchRules:
      - prefixMatch: /vod/
        headerMatches:
        - headerName: "x-staging-client"
          presentMatch: true
        queryParameterMatches:
        - name: "live"
          exactMatch: "yes"
      routeAction:
        cdnPolicy:
          defaultTtl: 5s

התאמת נתיבים

‫Media CDN תומך בהתאמה מלאה (מדויקת), בהתאמה של תחיליות ובהתאמה של נתיבים עם תווים כלליים לחיפוש. אפשר לשלב התאמה של נתיבים עם התאמה שמבוססת על מארח, כותרת ופרמטרים של שאילתות כדי ליצור כללי ניתוב מדויקים של בקשות.

יש שלוש דרכים להתאים נתיב של כתובת URL.

שדה תיאור דוגמה
matchRules[].fullPathMatch התנאי fullPathMatch תואם לנתיב כתובת ה-URL המלא, שלא כולל את מחרוזת השאילתה. אם רלוונטי, צריך לציין לוכסנים בסוף.

מסלול עם כלל התאמה של fullPathMatch: "/stream/" תואם ל-/stream/ אבל לא ל-/stream או ל-/stream/us/hls/1234.ts.

fullPathMatch היא התאמה מדויקת.
matchRules[].prefixMatch התנאי prefixMatch תואם לקידומת של נתיב כתובת ה-URL. כתובות URL שמתחילות באותו מחרוזת תואמות.

מסלול עם כלל התאמה prefixMatch: "/videos/" מתאים גם ל-/videos/hls/58481314/manifest.m3u8 וגם ל-/videos/dash כי שניהם מכילים את הקידומת /videos/.
matchRules[].pathTemplateMatch התנאי pathTemplateMatch תומך באופרטורים של תווים כלליים לחיפוש, ומאפשר להתאים תבניות מורכבות של כתובות URL וקטעי נתיב, וגם ללכוד משתנים עם שמות כדי לשכתב כתובות URL.

מסלול עם כלל התאמה של pathTemplateMatch: "/**.m3u8" מתאים לכל נתיב כתובת ה-URL שמסתיים ב-.m3u8.

הדפוס הזה מתאים גם ל-/content/en-GB/13/51491/manifest_193193.m3u8 וגם ל-/p/abc/1234/manifest_1080p5000.m3u8.

דוגמאות נוספות מופיעות בקטע בנושא התאמת תבניות.

פרטים נוספים אפשר למצוא במפרט ה-API של MatchRule.

לדוגמה, כדי להתאים את כל הבקשות שמתחילות ב-/stream/, יוצרים כלל ניתוב בדומה לכלל הבא:

name: prod-service
routing:
  hostRules:
  - hosts:
    - media.example.com
    - *.vod.example.com
    pathMatcher: example_routes
  pathMatchers:
  - name: example_routes
    routeRules:
    - priority: 1
      matchRules:
      - prefixMatch: /stream/

בדוגמה הזו, כלל ההתאמה כולל במפורש את קו הנטוי בסוף:

  • בקשה אל media.example.com/stream/id/1234/hls/manifest.m3u8 תואמת למסלול הזה.
  • בקשה אל media.example.com/stream-eu/id/4567/hls/manifest.m3u8 לא תואמת למסלול הזה.

במקרה השני, Media CDN מחזיר שגיאת HTTP 404, אלא אם הוגדר מסלול אחר או מסלול כללי.

הסבר על אופן הפעולה של העדיפות בניתוב עם קידומות דומות מופיע בקטע סדר העדיפות של המסלולים.

התאמת דפוסים (תווים כלליים לחיפוש)

התאמה לתבנית מאפשרת להתאים מספר חלקים של כתובת URL, כולל כתובות URL חלקיות וסיומות (סיומות של קבצים), באמצעות תחביר של תווים כלליים.

אפשר גם לשייך אחד או יותר מפלחים של נתיב למשתנים עם שם בשדה pathTemplateMatch, ואז להפנות למשתנים האלה כשכותבים מחדש את כתובת ה-URL בשדה pathTemplateMatch.pathTemplateRewrite כך אפשר לשנות את הסדר של פלחי כתובות ה-URL ולהסיר אותם לפני שהבקשה נשלחת למקור.

בדוגמה הבאה אפשר לראות איך מתאימים שני סיומות שונות של כתובות URL:

# EdgeCacheService.routing.pathMatchers[]
    routeRules:
    - priority: 1
      description: "Match video segments"
      matchRules:
      - pathTemplateMatch: "/**.ts"
      - pathTemplateMatch: "/**.m4s"
      origin: prod-video-storage

התחביר הנתמך כולל את הדברים הבאים.

אופרטור התאמות דוגמה
* התאמה לקטע נתיב יחיד, עד למפריד הנתיב הבא: / /videos/*/*/*.m4s matches /videos/123414/hls/1080p5000_00001.m4s.
** התאמה לאפס או יותר פלחים של נתיבים. אם הוא מופיע, הוא חייב להיות האופרטור האחרון. /**.mpd matches /content/123/india/dash/55/manifest.mpd.
{name} or {name=*}

משתנה עם שם שתואם לקטע נתיב אחד.

תואם לפלח נתיב יחיד, עד למפריד הנתיבים הבא: /.

‫/content/{format}/{lang}/{id}/{file}.vtt תואם ל- /content/hls/en-us/12345/en_193913.vtt ומתעד את format="hls", lang="en-us", id="12345", ו-file="en_193913" כמשתנים.
{name=videos/*} משתנה עם שם שתואם ליותר מפלח נתיב אחד. פלח הנתיב שתואם ל-videos/* נלכד כמשתנה בעל שם. ‫/videos/{language=lang/*}/* matches /videos/lang/en/video.m4s and populates the path variable language with the value lang/en.
{name=**}

משתנה עם שם שתואם לאפס או יותר פלחים של נתיב.

אם הוא מופיע, הוא חייב להיות האופרטור האחרון.

‫/**.m3u8 או /{path=**}.m3u8 מתאימים לכל פלחי הנתיב עד לתוסף.

‫/videos/{file=**} matches /videos/en-GB/def566/manifest.m3u8, including the extension, and captures the path variable file="en-GB/def566/manifest.m3u8.

הערות:

  • אם לא משכתבים כתובת URL, אפשר להשתמש באופרטורים הפשוטים יותר * ו-**.
  • כשמשתמשים במשתנים כדי לתעד מקטעי נתיב, אי אפשר להפנות לחלקים בכתובת ה-URL שלא תועדו על ידי משתנה בpathTemplateRewrite. לדוגמה, אפשר לעיין בקטע תיעוד משתני נתיב.
  • אי אפשר להפנות למשתנים ב-pathTemplateRewrite הבא שלא קיימים ב-pathTemplateMatch באותו מסלול.
  • המשתנים תלויי-רישיות, כלומר {FORMAT}, {forMAT} ו-{format} מייצגים משתנים וערכים שונים.
  • אפשר לציין עד 10 אופרטורים (תווים כלליים או משתנים) בהתאמה. השדות pathTemplateMatch ו-pathTemplateRewrite לא יכולים להכיל יותר מ-255 תווים.

דוגמה: התאמה לפי סיומת קובץ

בדוגמה הבאה מוצג תרחיש שימוש נפוץ באופרטורים של תווים כלליים: התאמה של כל מקטעי הנתיב עד לסיומת.

במקרה כזה, צריך לבצע את הפעולות הבאות:

  • אחזור מניפסטים של סרטונים (פלייליסטים) שמסתיימים ב-.m3u8 וב-.mpd ממקור המניפסט, והחלת TTL קצר (5 שניות) על התגובות האלה כי הן משתנות באופן קבוע.
  • מאחזרים קטעי וידאו שמסתיימים ב-.ts וב-.m4s ממקור הקטע, ו מחילים על התגובות האלה TTL ארוך יותר (יום אחד).

הגישה הזו נפוצה בשימוש בשירותים של SSAI (הטמעת מודעות בצד השרת) או DAI (הטמעת מודעות דינמיות), ובסרטונים בשידור חי שבהם קובץ המניפסט מתעדכן כל כמה שניות.

ההגדרה הבאה מדגימה איך להגדיר את הניתוב של Media CDN כדי לתמוך בכך:

name: prod-service
routing:
  hostRules:
  - hosts:
    - media.example.com
    pathMatcher: example_routes
  pathMatchers:
  - name: example_routes
    routeRules:
    # the first route only matches video manifests
    - priority: 1
      matchRules:
      - pathTemplateMatch: "/**.m3u8" # "**" matches all path segments
      - pathTemplateMatch: "/**.mpd"
      origin: manifest-origin
      routeAction:
        cdnPolicy:
          cacheMode: FORCE_CACHE_ALL
          defaultTtl: 5s
    # the second route matches video segments, fetches them
    # from a separate origin server, caching them for a longer
    # duration (1 day).
    - priority: 2
      matchRules:
      - pathTemplateMatch: "/**.ts"
      - pathTemplateMatch: "/**.m4s"
      origin: segment-origin
      routeAction:
        cdnPolicy:
          cacheMode: FORCE_CACHE_ALL
          defaultTtl: 86400s

דוגמה: תיעוד משתני נתיב

בדוגמה הבאה מוצג אופן השימוש במשתנים עם שמות כדי לתאר פלח נתיב אחד או יותר.

אפשר להשתמש במשתנים האלה ב-pathTemplateRewrite כדי לשכתב את הנתיב לפני שהבקשה נשלחת למקור, או כדי ליצור pathTemplateMatch מורכב שמתאר את עצמו.

routing:
  hostRules:
  - hosts:
    - media.example.com
    pathMatcher: example_routes
  pathMatchers:
  - name: example_routes
    routeRules:
    - priority: 1
      matchRules:
      # Matches a request of "/us/en/hls/123139139/segments/00001.ts"
      - pathTemplateMatch: "/{country}/{lang}/{format}/{id}/{file=**}"
      origin: my-origin
      routeAction:
        urlRewrite:
          # Rewrites to "/123139139/hls/segments/00001.ts"
          pathTemplateRewrite: "/{id}/{format}/{file}"

פרטים נוספים:

  • כל משתנה {name} מתעד פלח נתיב יחיד. פלח נתיב הוא כל התווים בין זוג של / (לוכסנים) בנתיב כתובת ה-URL.
  • משתנה של {name=**} לוכד את כל פלחי הנתיב שנותרו. במקרה הזה, הוא תואם גם ל-segments/00001.ts וגם ל-master.m3u8.
  • ב-pathTemplateRewrite באותו מסלול, מתייחסים שוב לחלק מהמשתנים שצוינו ב-pathTemplateMatch. השמטתם במפורש את המשתנים {country} ו-{lang} כי הם לא תואמים למבנה הספרייה במקור.

בדוגמה הזו, יקרו הדברים הבאים:

  • כתובת ה-URL של בקשה נכנסת /us/en/hls/123139139/segment_00001.ts תואמת ל-pathTemplateMatch ונכתבת מחדש כ-/123139139/hls/segment_00001.ts לפני שהיא נשלחת למקור.
  • כתובת URL של בקשה נכנסת /us/123139139/master.m3u8 לא תואמת ל-pathTemplateMatch, ומתקבל קוד סטטוס HTTP 404 (Not Found).
  • כתובת URL של בקשה נכנסת /br/es/dash/c966cbbe6ae3/subtitle_00001.vtt תואמת גם ל-pathTemplateMatch ונכתבת מחדש כ-/c966cbbe6ae3/dash/subtitle_00001.vtt לפני שהיא נשלחת למקור.

מידע נוסף על האינטראקציה בין התאמה לתווים כלליים לבין שכתוב כתובות URL זמין בקטע שכתובים.

התאמת מארחים

כל שירות יכול להתאים למספר שמות מארחים, וכל קבוצה של שמות מארחים מכילה קבוצה משלה של נתיבים (שנקראים path matchers). במקרה הנפוץ ביותר, כל שמות המארחים של שירות ממופים לקבוצה אחת של מסלולים משותפים עם רשימה אחת של מארחים ורכיב אחד להתאמת נתיבים.

name: prod-service
routing:
  hostRules:
  - hosts:
    - media.example.com
    - *.vod.example.com
    pathMatcher: example_routes
  pathMatchers:
  - name: example_routes
    routeRules:
    # list of routes for the configured hosts
    - priority: 999
      matchRules:
      - prefixMatch: /
      origin: DEFAULT_ORIGIN

למארחים שלא תואמים מוצג דף HTTP 404 שמוגדר כברירת מחדל. כדי לאשר כל מארח, אפשר לכלול את התו הכללי לחיפוש * כערך hostRules[].hosts[].

אפשר גם להגדיר קבוצות של מסלולים (לדוגמה, קיבוץ לפי מדינה או לפי שידור חי לעומת לפי דרישה). לכל שירות יש מדיניות אבטחה אחת, ולכן בדרך כלל מומלץ להגדיר שירות אחד לכל שוק (אזור גיאוגרפי) או עומס עבודה.

הערות:

  • כותרות מארח (או HTTP/2 :authority) שמכילות יציאה מותאמות באופן מרומז למארח מוגדר. אין צורך לציין במפורש את היציאות.
  • אם הבקשה היא באמצעות HTTP, רשומה של hostRules[].hosts[] *.vod.example.com תתאים ל-us.vod.example.com ול-us.vod.example.com:80.
  • אם הבקשה היא באמצעות HTTPS‏ (TLS), רשומה של hostRules[].hosts[]‏ *.vod.example.com תתאים ל-us.vod.example.com:443.

פרטים נוספים אפשר למצוא במפרט ה-API של HostRule.

התאמה בכותרות ובפרמטרים של שאילתות

אתם יכולים להגדיר מסלולים כך שיתאימו לשמות ספציפיים של פרמטרים של כותרת ושאילתה, וגם לנוכחות של ערך כותרת (קידומת, סיומת או התאמה מדויקת).

התאמה של פרמטרים של שאילתות וכותרות היא לוגית מסוג AND – הבקשה צריכה להתאים לכל הפרמטרים של השאילתות ולכל מפתחות הכותרות (ולערכים, אם צוינו) כדי להתאים לנתיב הנתון.

לדוגמה, אם רוצים להפנות בקשות עם שם שדה כותרת וערך כותרת ספציפיים למקור שנקרא alternate-origin, צריך להגדיר את תנאי ההתאמה בתוך routeRules[].matchRules[].headerMatches[]:

name: prod-service
routing:
  hostRules:
  - hosts:
    - media.example.com
    pathMatcher: example_routes
  pathMatchers:
  - name: example_routes
    routeRules:
    - priority: 1
      origin: alternate-origin
      matchRules:
      - prefixMatch: "/videos/"
        headerMatches:
        - headerName: "x-device-name"
          exactMatch: "roku"

בדוגמה הזו, בקשות עם /videos/ בתחילת כתובת ה-URL והכותרת x-device-name: roku תואמות לנתיב הזה. בקשות שחסר בהן שם הכותרת הזה או שיש בהן ערך שונה לא תואמות למסלול הזה.

פרטים נוספים אפשר למצוא במפרט ה-API של HeaderMatch.

באופן דומה, כדי להתאים לפרמטרים של שאילתה, מציינים פרמטר אחד או יותר של queryParameterMatches באופן הבא:

name: prod-service
routing:
  hostRules:
  - hosts:
    - media.example.com
    pathMatcher: example_routes
  pathMatchers:
  - name: example_routes
    routeRules:
    - priority: 1
      origin: eu-live-origin-prod
      matchRules:
      - prefixMatch: "/videos/"
        queryParameterMatches:
        - name: "playback_type"
          exactMatch: "live"
        - name: "geo"
          exactMatch: "eu"

בדוגמה הזו, בקשת לקוח של https://cdn.example.com/videos/1234/abcd/xyz.m3u8?playback_type=live&geo=eu תואמת למסלול הזה.

פרטים נוספים אפשר למצוא במפרט ה-API של QueryParameterMatcher.

הגדרת מסלול ברירת מחדל (catch-all)

כברירת מחדל, Media CDN מחזיר שגיאת HTTP 404 (Not Found) אם בקשה לא תואמת לאף אחד מהמסלולים שהוגדרו.

כדי להגדיר נתיב כולל עבור pathMatcher (אוסף של נתיבים):

  • יוצרים routeRule עם העדיפות הכי נמוכה (המספר הכי גבוה) – לדוגמה, 999, שהיא העדיפות הכי נמוכה שאפשר להגדיר לניתוב.
  • מגדירים matchRule עם התאמה לפי קידומת של / (התאמה לכל נתיבי הבקשות).
  • מגדירים origin או urlRedirect בנתיב.

לדוגמה, כדי להגדיר נתיב כולל שמפנה את כל הבקשות שלא תואמות למקור ברירת מחדל בשם my-origin, יוצרים נתיב חדש עם priority: 999 ועם matchRules[].prefixMatch של / באופן הבא:

name: prod-service
routing:
  hostRules:
  - hosts:
    - cdn.example.com
    pathMatcher: example_routes
  pathMatchers:
  - name: example_routes
    routeRules:
    - priority: 999
      origin: my-origin
      matchRules:
      - prefixMatch: /

אפשר גם לשכתב את כתובת ה-URL לפני האחזור מהמקור, או להפנות לדף ברירת מחדל (כמו דף הנחיתה) במקום לשלוח את הבקשה "כמו שהיא" למקור.

סדר העדיפויות של המסלולים

לכל מסלול במערך של routeRules[] צריך להיות משויך priority.

צריך להגדיר עדיפות גבוהה יותר (מספר קטן יותר) למסלולים ספציפיים יותר. מסלול A שתואם לקידומת /stream/ עם עדיפות של 1, מונע ממסלול ספציפי יותר /stream/live/eu/ עם עדיפות של 5 להתאים לבקשות כלשהן.

  • המסלול עם העדיפות הכי גבוהה הוא '1', והמסלול עם העדיפות הכי נמוכה הוא '999'.
  • אי אפשר להגדיר שתי routeRules או יותר עם אותה עדיפות. העדיפות של כל כלל חייבת להיות מספר בין 1 ל-999, כולל.
  • הגדרה של נתיב catch-all מאפשרת לשלוח את כל הבקשות שלא תואמות למקור ברירת מחדל או להפנות אותן לדף נחיתה או לנקודת קצה.

בדוגמה הבאה אפשר לראות שהמסלול /live/us/ אף פעם לא יתאים כי המסלול /live/ נמצא בעדיפות גבוהה יותר:

routeRules:
- priority: 1
  description: "Live routes"
  matchRules:
  - prefixMatch: /live/
  routeAction:
    cdnPolicy:
      defaultTtl: 5s
- priority: 2
  description: "U.S based live streams"
  matchRules:
  # This would never be matched, as the /live/ prefixMatch at priority 1
  # would always take precedence.
  - prefixMatch: /live/us/
  routeAction:
    cdnPolicy:
      defaultTtl: 5s
- priority: 999
  description: "Catch-all route"
  matchRules:
  - prefixMatch: /

כדי לפתור את הבעיה הזו, אתם יכולים להגדיר עדיפות גבוהה יותר למסלול הספציפי יותר (הארוך יותר):

routeRules:
- priority: 1
  description: "U.S based live streams"
  matchRules:
  # The more specific (longer) match is at a higher priority, and now
  # matches requests as expected.
  - prefixMatch: /live/us/
  routeAction:
    cdnPolicy:
      defaultTtl: 5s
- priority: 2
  description: "Live routes"
  matchRules:
  - prefixMatch: /live/
  routeAction:
    cdnPolicy:
      defaultTtl: 5s
- priority: 999
  description: "Catch-all route"
  matchRules:
  - prefixMatch: /

כך המערכת יכולה להתאים בקשות בצורה נכונה למסלול הספציפי יותר. בקשה עם הקידומת /live/eu/ עדיין תעבור למסלול /live/ בעדיפות 2.

סינון לפי שיטה

כברירת מחדל, Media CDN מבצע פרוקסי רק לשיטות GET, HEAD ו-OPTIONS למקור, ומסנן את השיטות שיכולות לשנות את המקור.

אפשר לשנות את התנהגות ברירת המחדל הזו לכלל ניתוב ספציפי על ידי ציון השיטות שרוצים להעביר דרך ה-proxy למקור. בנוסף ל-GET, HEAD, ו-OPTIONS,‏ Media CDN תומך ב-PUT,‏ POST,‏ DELETE ו-PATCH.

‫Media CDN מבצע ניסיונות חוזרים או ניסיון מעבר לגיבוי רק לבקשות שמשתמשות בשיטות HTTP בטוחות יותר, כמו GET,‏ HEAD או OPTIONS.

כדי להגדיר תמיכה בקבוצה של שיטות לכלל ניתוב, מציינים קטע routeMethods עם ערך allowed_methods לכל שיטה.

routeRules:
- priority: 5
  description: "Video uploads"
  routeMethods:
    allowedMethods: ["PUT", "POST", "OPTIONS"]
  matchRules:
  - pathTemplateMatch: "/uploads/**.ts"
  origin: prod-video-storage
- priority: 10
  description: "Video serving"
  routeMethods:
    allowedMethods: ["GET", "HEAD"]
  matchRules:
  - pathTemplateMatch: "/videos/**.ts"
  origin: prod-video-storage

נירמול נתיבים

נורמליזציה של נתיבים מתארת איך Media CDN משלב כמה ייצוגים של כתובת URL לייצוג קנוני יחיד בתרחישים ספציפיים.

נרמול נתיבים יכול לשפר ישירות את שיעורי הפגיעה במטמון על ידי צמצום מספר כתובות ה-URL של הבקשות שמייצגות את אותו תוכן, ועל ידי צמצום שגיאות במקורות שמצפים לנתיבים מנורמלים.

בקשות נכנסות מנורמלות באופן הבא:

  • כמה לוכסנים עוקבים מאוחדים ללוכסן אחד. לדוגמה, נתיב כתובת ה-URL של /videos///12345/manifest.mpd עובר נירמול ל-/videos/12345/manifest.mpd.
  • פלחים של נתיבים עוברים נורמליזציה בהתאם לסעיף 6.2.2.3 ב-RFC 3986. לדוגמה, הנתיב /a/b/c/./../../g עובר נורמליזציה ל-/a/g על סמך האלגוריתם remove dot segments שמוגדר ב-RFC 3986. הנורמליזציה הזו מתבצעת לפני הבדיקה של המטמון או לפני העברת הבקשה למקור.
  • הבקשות לא עוברות נירמול של קידוד אחוזים. לדוגמה, כתובת URL עם תו קו נטוי (%2F) שמקודד באחוזים לא מפוענחת לצורה לא מקודדת.

כתובות ה-URL נשארות תלויות באותיות רישיות ולא עוברות נורמליזציה של האותיות הרישיות. כתובות URL רבות מכילות קידודים ב-Base64 שרגישים לאותיות רישיות, כולל כתובות URL עם אסימונים של בקשה חתומה.

שכתובים והפניות אוטומטיות

בקטעים הבאים מופיעות דוגמאות לאופן הכתיבה מחדש של בקשות ולהגדרת הפניות אוטומטיות.

שינוי כתובות URL של בקשות

‫Media CDN תומך בשכתוב של מארחים ונתיבים. הכתיבה מחדש משנה את כתובת ה-URL שנשלחת למקור, ומאפשרת לשנות את המארחים והנתיבים לפי הצורך. החלפות של מארח ונתיב מתבצעות ברמת המסלול, ומאפשרות לכם להגדיר אילו בקשות ספציפיות יוחלפו על סמך כל התאמה, כולל נתיב, פרמטר של שאילתה וכותרת של בקשה.

פרטים נוספים אפשר למצוא במפרט ה-API של RouteAction.UrlRewrite.

יש שלוש דרכים לשכתב בקשה:

שדה תיאור
urlRewrite.pathPrefixRewrite

האופרטור משנה את הנתיב, ומסיר את הקידומת שצוינה ב-prefixMatch שתאמה לבקשה.

אפשר לציין רק אחד מהמאפיינים pathPrefixRewrite או pathTemplateRewrite בכלל מסלול אחד.

urlRewrite.pathTemplateRewrite

אפשר להשתמש בפונקציה pathTemplateRewrite רק עם כלל התאמה pathTemplateMatch תואם באותו מסלול.

אפשר לציין רק אחד מהמאפיינים pathPrefixRewrite או pathTemplateRewrite בכלל מסלול אחד.

urlRewrite.hostRewrite הוא משכתב את המארח לפני שהבקשה נשלחת לשרת המקור.

הערות:

  • כתובות URL שנכתבו מחדש לא משנות את מפתח המטמון. מפתח המטמון מבוסס על כתובת ה-URL של הבקשה שנשלחת מהלקוח.
  • השיכתוב מתבצע אחרי התאמת המסלול ואימות הבקשה החתומה. המסלולים לא מוגדרים מחדש בהתאם לכלל התאמה אחר.

דוגמה: הסרת קידומת של נתיב

לדוגמה, כדי לשכתב כתובת URL של בקשת לקוח מ-/vod/videos/hls/1234/abc.ts ל-/videos/hls/1234/abc.ts (הסרת /vod מהנתיב), אפשר להשתמש בתכונה pathPrefixRewrite:

name: prod-service
routing:
  hostRules:
  - hosts:
    - cdn.example.com
    pathMatcher: example_routes
  pathMatchers:
  - name: example_routes
    routeRules:
    - priority: 1
      origin: my-origin
      matchRules:
      - prefixMatch: "/vod/videos/"
      routeAction:
        urlRewrite:
          pathPrefixRewrite: "/videos/"

הפעולה של pathPrefixRewrite היא החלפה של כל קידומת הנתיב שתואמת ל-matchRules[].prefixMatch בערך של pathPrefixRewrite.

כדי לשכתב שם מארח (לדוגמה, לשכתב את cdn.example.com ל-my-bucket.s3.us-west-2.amazonaws.com), אתם יכולים להגדיר את האפשרויות הבאות:

name: prod-service
routing:
  hostRules:
  - hosts:
    - cdn.example.com
    pathMatcher: example_routes
  pathMatchers:
  - name: example_routes
    routeRules:
    - priority: 1
      origin: my-origin
      matchRules:
      - prefixMatch: "/videos/"
      routeAction:
        urlRewrite:
          hostRewrite: "my-bucket.s3.us-west-2.amazonaws.com"

במקרה הזה, כתובת ה-URL של בקשת המקור תשתנה מ-cdn.example.com/videos/* ל-my-bucket.s3.us-west-2.amazonaws.com/videos/*. אפשר גם לשלב בין שינוי של המארח ושינוי של הנתיב במסלול אחד.

דוגמה: שימוש במשתנים לשכתוב כתובות URL

כדי להשתמש ב-pathTemplateMatch וב-pathTemplateRewrite כדי לשכתב חלקים מכתובת URL של בקשה נכנסת, אפשר לעיין בקטע בנושא לכידת משתנים.

בקשות להפניה מחדש

‫Media CDN תומך בשלושה סוגים של הפניות אוטומטיות:

  • הפניות אוטומטיות של מארחים, שמפנות אוטומטית רק את המארח (הדומיין), בלי לשנות את הנתיב ואת הפרמטרים של השאילתות.
  • הפניות נתיב, שמחליפות את הנתיב באופן מלא.
  • הפניות אוטומטיות של קידומת נתיב, שמחליפות רק את הקידומת התואמת.

ההפניות מוגדרות כברירת מחדל ל-HTTP 301 (Moved Permanently), אבל אפשר להגדיר אותן כך שיחזירו קודי סטטוס שונים של הפניות על בסיס כל מסלול.

ההגדרה הבאה היא דוגמה להפניה אוטומטית שמבוססת על קידומת, שבה משתמשים שמבקרים בכתובת https://cdn.example.com/on-demand/* מופנים לכתובת https://cdn.example.com/streaming/*.

name: prod-service
routing:
  hostRules:
  - hosts:
    - cdn.example.com
    pathMatcher: example_routes
  pathMatchers:
  - name: example_routes
    routeRules:
    - priority: 10
      matchRules:
      - prefixMatch: "/on-demand/"
      urlRedirect:
        # The prefix matched in matchRules.prefixMatch is replaced
        # by this value
        prefixRedirect: "/streaming/"
        redirectResponseCode: TEMPORARY_REDIRECT # corresponds to a HTTP 307

בדוגמה הזו, ההפניה האוטומטית משתנה להפניה זמנית, כדי למנוע מלקוחות (כמו דפדפנים) לשמור אותה במטמון. האפשרות הזו שימושית אם אתם מתכוונים לשנות את התקציב בקרוב.

הערכים הנתמכים של redirectResponseCode מפורטים בטבלה הבאה.

קוד תגובה להפניה אוטומטית קוד מצב HTTP
MOVED_PERMANENTLY_DEFAULT ‫HTTP 301 (הועבר לצמיתות)
FOUND ‫HTTP 302 (נמצא)
SEE_OTHER ‫HTTP 303 (See Other)
TEMPORARY_REDIRECT ‫HTTP 307 (הפניה זמנית לכתובת אחרת)
PERMANENT_REDIRECT ‫HTTP 308 (הפניה קבועה לכתובת אחרת)

הערות:

  • נתיב יכול להפנות תנועה למקור או להחזיר הפניה אוטומטית ללקוח. אי אפשר להגדיר את השדות origin ו-urlRedirect בו-זמנית.
  • במסלולים שמפנים ל-HTTPS צריך לצרף לפחות אישור SSL לשירות.

פרטים נוספים אפשר למצוא במפרט ה-API של RouteRule.UrlRedirect.

הפניה אוטומטית של כל הבקשות ל-HTTPS

כדי להפנות את כל הבקשות ל-HTTPS (במקום ל-HTTP), אפשר להגדיר כל אחד מהשירותים כך שיפנה את כל בקשות הלקוח ל-HTTPS באופן אוטומטי. ללקוחות שמתחברים באמצעות HTTP נשלח קוד סטטוס HTTP ‏301 (Permanent Redirect) עם הכותרת Location שמוגדרת לאותה כתובת URL באמצעות https:// במקום http://.

gcloud 

gcloud edge-cache services update SERVICE_NAME \
    --require-tls
 
Request issued for: [SERVICE_NAME]
Updated service [SERVICE_NAME].

הפקודה מחזירה תיאור של השירות, כאשר הערך של requireTls מוגדר עכשיו ל-true.

  name: SERVICE_NAME
  requireTls: true

אפשר גם להגדיר את הכותרת Strict-Transport-Security ככותרת תגובה כדי להנחות את הלקוחות להתחבר תמיד ישירות דרך HTTPS.

שימוש בשרתי קצה לאחסון של צד שלישי

‫Media CDN תומך בחיבור לנקודות קצה של HTTP שאפשר להגיע אליהן באופן ציבורי מחוץ ל- Google Cloud, כולל קטגוריות אחסון של AWS S3,‏ Azure Blob Storage וספקי אחסון אחרים. האפשרות הזו יכולה להיות שימושית אם יש לכם ארכיטקטורה מרובת עננים, או אם עדיין לא העברתם נתונים ל-Cloud Storage באמצעות Storage Transfer Service.

הגדרת מקור מינימלית שמגדירה קטגוריה באירוח וירטואלי ב-AWS S3:

name: MY_S3_ORIGIN
originAddress: BUCKET-NAME.s3.REGION.amazonaws.com

אם אתם לא משתמשים בשם של קטגוריה שתואם לשמות המארחים שהוגדרו למשאבי EdgeCacheService, אתם צריכים גם להגדיר שכתוב של מארח עבור מסלולים שמשויכים למקור הזה (או למקורות האלה). אחרת, הכותרת Host שמוגדרת על ידי בקשת הלקוח משמשת לאחזור מהמקור.

לדוגמה, כדי למפות את כל הבקשות עם קידומת הנתיב /legacy/ לקטגוריית המקור החיצונית, אפשר להגדיר גם hostRewrite וגם pathPrefixRewrite כדי להסיר את הקידומת הזו מהבקשה המקורית:

routeRules:
  - description: legacy backend
    matchRules:
    - prefixMatch: "/legacy/"
    routeAction:
      urlRewrite:
        hostRewrite: BUCKET-NAME.s3.REGION.amazonaws.com
        pathPrefixRewrite: /
      cdnPolicy:
        cacheMode: CACHE_ALL_STATIC
        defaultTtl: 3600s

מידע נוסף על הגדרת כותרת המארח בבקשות למקור מופיע במסמכי התיעוד בנושא כותרות של בקשות למקור.

שיתוף משאבים בין מקורות (CORS)

שיתוף משאבים בין מקורות (CORS) הוא גישה שמתמקדת בדפדפן כדי לבצע בקשות בין מקורות בצורה מאובטחת. מדיניות CORS מאפשרת להגדיר באופן אוטומטי כותרות CORS, כמו Access-Control-Allow-Origins, על בסיס מדיניות לכל מסלול.

הגדרת CORS

ב-Media CDN אפשר להגדיר מדיניות CORS במסלול עבור EdgeCacheService.

מדיניות CORS מגדירה את הכללים האלה באמצעות קבוצה משותפת של כותרות HTTP. אפשר להגדיר כותרות CORS נפוצות בתגובות, כמו Access-Control-Allow-Origin, Access-Control-Max-Age ו-Access-Control-Allow-Headers. הכותרות האלה מאפשרות לבצע קריאות ממקורות שונים לשירותי Media CDN שאולי מתארחים בדומיין (מקור) שונה מהקצה הקדמי של האתר, ועשויות למנוע בקשות ממקורות שונים שלא אישרתם באופן מפורש.

לדוגמה, player.example.com ו-api.example.com הם מקורות שונים (במובן של דפדפן), ואולי תרצו שאפליקציית הקצה הקדמי שלכם תשלח בקשות אל api.example.com כדי לאחזר את רשימת ההשמעה הבאה או לרענן רשימה של תוכן קשור. באופן דומה, יכול להיות שplayer.example.com יצטרך לפנות אל cdn.example.com כדי לאחזר פלייליסטים של סרטונים וקטעים של סרטונים: cdn.example.com צריך לציין שזה בסדר, ושהמערכת של player.example.com היא allowed origin, וגם לציין כללים אחרים (אילו כותרות מותרות, האם אפשר לכלול קובצי Cookie).

לדוגמה, אם רוצים לאפשר את stream.example.com כמקור ואת הכותרת X-Client-ID בבקשות CORS, אפשר להגדיר corsPolicy במסלול, באופן הבא:

corsPolicy: maxAge: 600 allowOrigins: ["stream.example.com"] allowHeaders:
["X-Client-ID"]

‫corsPolicy מוגדר ב-routing.pathMatchers[].routeRules[].routeAction.corsPolicy בתוך EdgeCacheService. כל routeRule יכול להגדיר corsPolicy שונה לפי הצורך, או לא להגדיר בכלל.

אם מגדירים ערך corsPolicy וגם מגדירים כותרת תגובה מותאמת אישית באמצעות השדות responseHeadersToAdd במסלול עם אותו שם, הערך corsPolicy מקבל עדיפות.

אם בתגובה של השרת המקורי מוגדרות כותרות HTTP, והגדרתם ערך corsPolicy, המערכת תשתמש בערכים של corsPolicy במקום זאת. הערכים לא מצומצמים או משולבים כדי למנוע שליחת ערכי כותרת לא תקינים ללקוח, או הגדרה לא מכוונת של מדיניות מתירה יותר מהמדיניות הרצויה.

המשתנה המיוחד {origin_request_header} מאוכלס בכותרת ה-HTTP‏ Origin בבקשת הלקוח. אפשר להגדיר את זה כערך של כותרת תגובה בהתאמה אישית במסלול, עבור הכותרת Access-Control-Allow-Origin.

פרטים נוספים מופיעים במפרט ה-API של RouteAction.CORSPolicy.

שדות של מדיניות CORS

בטבלה הבאה מתוארים השדות שמדיניות CORS מכילה.

שדה תיאור דוגמה
allowOrigins

מגדירה את כותרת התגובה Access-Control-Allow-Origins, שמציינת אילו מקורות יכולים לשלוח בקשות ממקורות שונים בסביבת דפדפן.

לדוגמה, אם תוכן הווידאו שלכם מוגש מ-https://video.example.com אבל הפורטל שפונה למשתמשים מוגש מ-https://stream.example.com, צריך להוסיף את https://stream.example.com כמקור מותר.

התנהגות של תו כללי: אם הערך של allowOrigins הוא *, Media CDN לא מחזיר את התו * באופן מילולי בכותרת Access-Control-Allow-Origin. במקום זאת, היא משקפת באופן דינמי את הערך של כותרת המקור מהבקשה.

 Access-Control-Allow-Origins: https://stream.example.com
maxAge

מגדירה את כותרת התגובה Access-Control-Max-Age, שמציינת כמה זמן, בשניות, לקוח דפדפן צריך לשמור במטמון את התגובה לבקשת קדם-הפעלה של CORS.

חלק מהדפדפנים מגבילים את הערך הזה לשעתיים או פחות, גם אם מצוין הערך המקסימלי (86,400 שניות).

 Access-Control-Max-Age: 7200
allowMethods

מגדירה את כותרת התגובה Access-Control-Allow-Methods, שמציינת אילו שיטות HTTP מורשות לגשת למשאב.

כברירת מחדל, Media CDN תומך רק בשיטות GET,‏ HEAD ו-OPTIONS. כדי להגדיר תמיכה בשיטות אחרות, אפשר לעיין במאמר בנושא שיטות של מסלולים.

 Access-Control-Allow-Methods: GET, OPTIONS, HEAD
allowHeaders

מגדירה את הכותרת Access-Control-Allow-Headers, שקובעת אילו כותרות אפשר לשלוח בבקשת CORS.

לרוב נדרש להגדיר את הכותרות האלה בנגני וידאו, שצריכים לגשת לכמה כותרות תגובה של תוכן וידאו כשמתבצעת בקשה חוצת-מקורות.

 Access-Control-Allow-Headers: Content-Type, If-Modified-Since, Range, User-Agent
exposeHeaders

הפונקציה מגדירה את כותרת התגובה Access-Control-Expose-Headers, שקובעת לאילו כותרות יש גישה ל-JavaScript בצד הלקוח.

לרוב נדרש לעשות את זה בנגני וידאו, שאולי יצטרכו לגשת לכותרות תגובה ספציפיות לתוכן וידאו כשמבקשים תוכן ממקורות שונים.

 Access-Control-Expose-Headers: Date, Cache-Status, Content-Type, Content-Length
allowCredentials

מגדירה את כותרת התגובה Access-Control-Allow-Credentials, שמאפשרת ל-JavaScript בצד הלקוח לבדוק את התגובה לבקשות עם פרטי כניסה כלולים.

אם הערך הוא false, הכותרת הזו לא נכללת.

 Access-Control-Allow-Credentials: true
disabled משבית את corsPolicy בלי להסיר אותו. בקשות לפני הטיסה OPTIONS מועברות באמצעות פרוקסי למקור. לא רלוונטי

דוגמה ל-corsPolicy

בדוגמה הבאה מוצגת הגדרת corsPolicy בסיסית:

routeRules:
- priority: 1
  matchRules:
  - prefixMatch: /stream/
  routeAction:
    cdnPolicy:
      defaultTtl: 3600s
    corsPolicy:
      allowOrigins:
      - "https://stream.example.com"
      - "https://stream-staging.example.com"
      maxAge: 86400s # some browsers might only honor up to 7200s or less
      allowMethods:
      - "GET"
      - "HEAD"
      - "OPTIONS"
      allowHeaders:
      - "Content-Type"
      - "If-Modified-Since"
      - "Range"
      - "User-Agent"
      exposeHeaders:
      - "Content-Type"
      - "Content-Length"
      - "Date"

פתרון בעיות שקשורות לניתוב

אם חלק מהבקשות לא מחזירות תוצאות תואמות או מחזירות שגיאות, כדאי לבדוק את הדברים הבאים:

  • במסלול צריך להיות מאפיין matchRule עם בדיוק אחד מהערכים prefixMatch,‏ fullPathMatch או pathTemplateMatch. אם לא תכללו אחד מהשדות האלה, ה-API יחזיר שגיאה.
  • מוודאים שpriority של כל מסלול מוגדר בצורה נכונה: למסלולים ספציפיים יותר (ארוכים יותר) צריך לתת עדיפות גבוהה יותר על פני מסלולים קצרים יותר ורחבים יותר.
  • כברירת מחדל, יש תמיכה רק בבקשות מסוג GET,‏ HEAD ו-OPTIONS. כדי להגדיר תמיכה בשיטות אחרות, אפשר לעיין במאמר בנושא ניתוב שיטות. השיטות שלא מופעלות עבור מסלול מסוים נדחות עם שגיאת HTTP 405 (Method Not Allowed).
  • בקשות HTTP GET עם גוף, או כל בקשה עם נתונים נוספים, נדחות עם שגיאת HTTP 400, כי אסור להשתמש בגופי בקשות בבקשות GET.
  • התאמה של פרמטרים של שאילתות וכותרות היא לוגית מסוג AND – הבקשה צריכה להתאים לכל המפתחות של הפרמטרים של השאילתות או הכותרות (ולערכים, אם צוינו) כדי להתאים לנתיב הנתון.

המאמרים הבאים