מידע על מסמכי מדיה ומאגרי נתונים

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

סקירה כללית

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

מאגר הנתונים מכיל אוסף של מסמכים שהעליתם. כשיוצרים מאגר נתונים, מציינים שהוא יכיל מסמכי מדיה. מאגרי נתונים של מדיה אפשר לצרף רק לאפליקציות מדיה, ולא לסוגים אחרים של אפליקציות כמו חיפוש מותאם אישית והמלצות. מאגרי נתונים מיוצגים ב-API על ידי המשאב DataStore.

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

הנתונים שאתם מעלים למאגר הנתונים צריכים להיות בפורמט ספציפי של סכימת JSON. הנתונים שמופיעים בסכימה הזו צריכים להיות בטבלה ב-BigQuery, בקובץ או בקבוצת קבצים ב-Cloud Storage, או באובייקט JSON שאפשר להעלות ישירות באמצעות מסוף Google Cloud .

סכימה מוגדרת מראש של Google לעומת סכימה מותאמת אישית

יש שתי אפשרויות לסכימת נתוני המדיה:

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

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

בשתי האפשרויות, אפשר להוסיף שדות לסכימה אחרי ייבוא הנתונים הראשוני. עם זאת, כשמייבאים נתונים בפעם הראשונה באמצעות סכימת Google המוגדרת מראש, השמות והסוגים של שדות הנתונים חייבים להיות זהים לאלה שמופיעים בטבלאות Document fields.

מאפיינים מרכזיים

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

מאפייני מפתח הם קבוצה מיוחדת וקבועה של מאפיינים בסכימה של Google. מאפייני המפתח מזהים מידע חשוב שמשמש להבנת המשמעויות הסמנטיות של הנתונים.

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

סכימת JSON מוגדרת מראש של Google ל-Document

כשמשתמשים במדיה, אפשר להשתמש בסכימת ה-JSON המוגדרת מראש של Google למדיה.

המסמכים מועלים עם ייצוג נתונים בפורמט JSON או Struct. חשוב לוודא ש-JSON או Struct של המסמך תואמים לסכימת ה-JSON הבאה. הסכימה של JSON משתמשת ב-JSON Schema 2020-12 לאימות. מידע נוסף על JSON Schema זמין גם במסמכי המפרט של JSON Schema באתר json-schema.org.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
    },
    "description": {
      "type": "string",
    },
    "media_type": {
      "type": "string",
    },
    "language_code": {
      "type": "string",
    },
    "categories": {
      "type": "array",
      "items": {
        "type": "string",
      }
    },
    "uri": {
      "type": "string",
    },
    "images": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "uri": {
            "type": "string",
          },
          "name": {
            "type": "string",
          }
        },
      }
    },
    "in_languages": {
      "type": "array",
      "items": {
        "type": "string",
      }
    },
    "country_of_origin": {
      "type": "string",
    },
    "transcript": {
      "type": "string",
    },
    "content_index": {
      "type": "integer",
    },
    "persons": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
          },
          "role": {
            "type": "string",
          },
          "custom_role": {
            "type": "string",
          },
          "rank": {
            "type": "integer",
          },
          "uri": {
            "type": "string",
          }
        },
        "required": ["name", "role"],
      }
    },
    "organizations": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
          },
          "role": {
            "type": "string",
          },
          "custom_role": {
            "type": "string",
          },
          "rank": {
            "type": "integer",
          },
          "uri": {
            "type": "string",
          }
        },
        "required": ["name", "role"],
      }
    },
    "hash_tags": {
      "type": "array",
      "items": {
        "type": "string",
      }
    },
    "filter_tags": {
      "type": "array",
      "items": {
        "type": "string",
      }
    },
    "duration": {
      "type": "string",
    },
    "content_rating": {
      "type": "array",
      "items": {
        "type": "string",
      }
    },
    "aggregate_ratings": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "rating_source": {
            "type": "string",
          },
          "rating_score": {
            "type": "number",
          },
          "rating_count": {
            "type": "integer",
          }
        },
        "required": ["rating_source"],
      }
    },
    "available_time": {
      "type": "datetime",
    },
    "expire_time": {
      "type": "datetime",
    },
    "live_event_start_time": {
      "type": "datetime",
    },
    "live_event_end_time": {
      "type": "datetime",
    },
    "production_year": {
      "type": "integer",
    }
  },
  "required": ["title", "categories", "uri", "available_time"],
}

אובייקט JSON לדוגמה Document

בדוגמה הבאה מוצג אובייקט JSON Document.

{
  "title": "Test document title",
  "description": "Test document description",
  "media_type": "sports-game",
  "in_languages": [
    "en-US"
  ],
  "language_code": "en-US",
  "categories": [
    "sports > clip",
    "sports > highlight"
  ],
  "uri": "http://www.example.com",
  "images": [
    {
      "uri": "http://example.com/img1",
      "name": "image_1"
    }
  ],
  "country_of_origin": "US",
  "content_index": 0,
  "transcript": "Test document transcript",
  "persons": [
    {
      "name": "sports person",
      "role": "player",
      "rank": 0,
      "uri": "http://example.com/person"
    },
  ],
  "organizations": [
    {
      "name": "sports team",
      "role": "team",
      "rank": 0,
      "uri": "http://example.com/team"
    },
  ],
  "hash_tags": [
    "tag1"
  ],
  "filter_tags": [
    "filter_tag"
  ],
  "duration": "100s",
  "production_year": 1900,
  "content_rating": [
    "PG-13"
  ],
  "aggregate_ratings": [
    {
      "rating_source": "imdb",
      "rating_score": 4.5,
      "rating_count": 1250
    }
  ],
  "available_time": "2022-08-26T23:00:17Z"
}

שדות מסמך

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

Document שדות אובייקט

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

שם השדה	הערות
name	השם המלא והייחודי של המשאב של המסמך. חובה לכל שיטות התשלום Document, למעט create ו-import. במהלך הייבוא, השם נוצר באופן אוטומטי ולא צריך לספק אותו באופן ידני.
id	מזהה המסמך שבו נעשה שימוש במסד הנתונים הפנימי שלכם. השדה ID חייב להיות ייחודי בכל מאגר הנתונים. אותו ערך משמש כשמתעדים אירוע של משתמש, והוא גם מוחזר על ידי השיטות recommend ו-search.
schemaId	חובה. המזהה של הסכימה שנמצאת באותו מאגר נתונים. צריך להגדיר אותו כ-default_schema, שנוצר אוטומטית כשיוצרים את מאגר הנתונים שמוגדר כברירת מחדל.
parentDocumentId	המזהה של מסמך האב. במסמכים ברמה העליונה (root), הערך של parent_document_id יכול להיות ריק או להצביע על עצמו. במסמכי צאצא, התג parent_document_id צריך להפנות למסמך בסיס תקין.

שדות של נכסים

השדות הבאים מוגדרים באמצעות פורמט סכימת ה-JSON המוגדר מראש עבור מדיה.

מידע נוסף על מאפייני JSON זמין במאמר properties באתר json-schema.org.

בטבלה הבאה מוגדרים שדות שטוחים

שם השדה	הערות
title	מחרוזת – חובה כותרת המסמך ממסד הנתונים. מחרוזת מקודדת ב-UTF-8. מוגבל ל-1,000 תווים.
categories	מחרוזת – חובה קטגוריות של מסמכים. המאפיין הזה חוזר על עצמו כדי לתמוך במסמך אחד ששייך לכמה קטגוריות מקבילות. כדי לקבל תוצאות באיכות גבוהה יותר, כדאי להשתמש בנתיב המלא של הקטגוריה. כדי לייצג את הנתיב המלא של קטגוריה, משתמשים בסמל > כדי להפריד בין רמות בהיררכיה. אם > הוא חלק משם הקטגוריה, מחליפים אותו בתו או בתווים אחרים. לדוגמה: "categories": [ "sports > highlight" ] מסמך יכול להכיל עד 250 קטגוריות. כל קטגוריה היא מחרוזת בקידוד UTF-8 עם מגבלה של 5,000 תווים.
uri	מחרוזת – חובה ה-URI של המסמך. מגבלת אורך של 5,000 תווים.
description	מחרוזת – מומלץ מאוד תיאור המסמך. מגבלת אורך של 5,000 תווים.
media_type	מחרוזת – חובה למלא את השדה הזה לסרטים ולתוכניות קטגוריה ברמה העליונה. סוגים נתמכים: movie,‏ show, concert,‏ event,‏ live-event, broadcast,‏ tv-series,‏ episode, video-game,‏ clip,‏ vlog, audio,‏ audio-book,‏ music, album,‏ articles,‏ news, radio,‏ podcast,‏ book ו-sports-game. לערכים movie ו-show יש משמעות מיוחדת. הם גורמים להעשרת המסמכים באופן שמשפר את הדירוג ועוזר למשתמשים שמחפשים כותרות למצוא תוכן חלופי שעשוי לעניין אותם.
language_code	מחרוזת – אופציונלי השפה של שם הפריט, התיאור ומאפיינים אחרים מסוג מחרוזת. צריך להשתמש בתגי שפה שמוגדרים על ידי BCP 47. השדה הזה נמצא בשימוש בחיפוש מסמכים. אם לא מגדירים ערך, ברירת המחדל היא en-US. לדוגמה, "language_code": "en-US". במקרה של מדיה, כמו סרטים, שיש לה מטא-נתונים בכמה שפות, צריך להתייחס לכל גרסה בשפה אחרת כמסמך נפרד. לכל גרסה יש כותרת, תיאור, קטגוריות ושדות מאפיינים אחרים משלה בשפה הרלוונטית. כדי להבחין בין גרסאות בשפות שונות, משתמשים במאפיין language_code. המאפיין הזה מאפשר גם לסנן את תוצאות החיפוש בצד השרת, כך שרק תוכן מדיה בשפה הרלוונטית יוחזר עבור שאילתה.
duration	מחרוזת – נדרש לאפליקציות עם המלצות למדיה שבהן היעד העסקי הוא שיעור קליקים (CTR) או משך צפייה לכל סשן. משך הזמן של תוכן המדיה. משך הזמן צריך להיות מקודד כמחרוזת. הקידוד צריך להיות זהה לקידוד של מחרוזת ה-JSON google::protobuf::Duration. לדוגמה: ‎"5s", "1m"
available_time	תאריך ושעה – חובה השעה שבה התוכן זמין למשתמשי הקצה. השדה הזה מציין את עדכניות התוכן עבור משתמשי הקצה. חותמת הזמן צריכה להיות בפורמט RFC 3339. לדוגמה: "2022-08-26T23:00:17Z" כדי לסנן לפי זמינות, אפשר לעיין במאמרים סינון המלצות וסינון מסמכים זמינים.
expire_time	תאריך ושעה – אופציונלי הזמן שבו הגישה לתוכן תפוג עבור משתמשי הקצה. השדה הזה מציין את עדכניות התוכן עבור משתמשי הקצה. חותמת הזמן צריכה להיות בפורמט RFC 3339. לדוגמה: "2032-12-31T23:00:17Z" כדי להחריג מסמכים שתוקפם פג מהתוצאות, אפשר לעיין במאמרים בנושא סינון המלצות וסינון חיפוש מדיה.
live_event_start_time	תאריך ושעה – אופציונלי השעה שבה האירוע בשידור חי מתחיל. חותמת הזמן צריכה להיות בפורמט RFC 3339. לדוגמה: "2020-12-31T23:00:17Z"
live_event_end_time	תאריך ושעה – אופציונלי השעה שבה האירוע החי מסתיים. חותמת הזמן צריכה להיות בפורמט RFC 3339. לדוגמה: "2024-01-28T23:00:17Z"
in_languages	מחרוזת – אופציונלי – חוזר השפה של תוכן המדיה. צריך להשתמש בתגי שפה שמוגדרים על ידי BCP 47. לדוגמה: "in_languages": [ "en-US"]
country_of_origin	מחרוזת – אופציונלי מדינת המקור של מסמך המדיה. אורך מוגבל של 128 תווים. לדוגמה: "country_of_origin": "US"
transcript	מחרוזת – אופציונלי תמליל של מסמך המדיה.
content_index	מספר שלם – אופציונלי אינדקס התוכן של מסמך המדיה. אפשר להשתמש בשדה של אינדקס התוכן כדי לסדר את המסמכים ביחס למסמכים אחרים. לדוגמה, אפשר להשתמש במספר הפרק כמדד לתוכן. אינדקס התוכן צריך להיות מספר שלם לא שלילי. לדוגמה: "content_index": 0
filter_tags	מחרוזת – אופציונלי – חוזר מסננים את התגים של המסמך. אפשר להזין לכל היותר 250 ערכים לכל מסמך, עם מגבלת אורך של 1,000 תווים. אחרת, מוחזרת שגיאת INVALID_ARGUMENT. אפשר להשתמש בתגיות האלה כדי לסנן את תוצאות החיפוש וההמלצות. כדי לסנן את תוצאות ההמלצות, מעבירים את התגים כחלק מהתג RecommendRequest.filter. התגים משמשים רק לסינון התוצאות שמוחזרות. הערכים של התגים לא משפיעים על התוצאות שמוחזרות על ידי מודלי החיפוש וההמלצות. לדוגמה: "filter_tags": [ "grade_level", "season"]
hash_tags	מחרוזת – אופציונלי – חוזר האשטאגים למסמך. אפשר להזין עד 100 ערכים לכל מסמך, עם מגבלת אורך של 5,000 תווים. לדוגמה: "hash_tags": [ "soccer", "world cup"]
production_year	מספר שלם – אופציונלי השנה שבה המדיה נוצרה.
content_rating	מחרוזת – אופציונלי – חוזר סיווג התוכן, שמשמש למערכות של אזהרות לגבי תוכן ולסינון תוכן על סמך הקהל. אפשר להזין עד 100 ערכים לכל מסמך, והאורך המקסימלי הוא 128 תווים. אפשר להשתמש בתג הזה כדי לסנן את תוצאות ההמלצות על ידי העברת התג כחלק מהתג RecommendRequest.filter. לדוגמה: content_rating: ["PG-13"]

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

שם השדה	הערות
images	אובייקט – אופציונלי – ניתן לחזרה מאפיין מפתח ברמת הבסיס שמשמש לאגד מאפיינים שקשורים לתמונה.
images.uri	מחרוזת – אופציונלי ה-URI של התמונה. מגבלת אורך של 5,000 תווים.
images.name	מחרוזת – אופציונלי שם התמונה. אורך מוגבל של 128 תווים.
persons	אובייקט – אופציונלי – ניתן לחזרה נכס מפתח בסיסי להוספת מאפיינים שקשורים לאדם. לדוגמה: "persons":[{"name":"sports person","role":"player","rank":0,"uri":"http://example.com/person"}]
persons.name	מחרוזת – חובה שם האדם.
persons.role	מחרוזת – חובה התפקיד של האדם בפריט המדיה. ערכים נתמכים: director, actor, player, team, league, editor, author, character, contributor, creator, editor, funder, producer, provider, publisher, sponsor, translator, music-by, channel, custom-role אם אף אחד מהערכים הנתמכים לא חל על role, צריך להגדיר את role כ-custom-role ולספק את הערך בשדה custom_role.
persons.custom_role	מחרוזת – אופציונלי הערך custom_role מוגדר אם ורק אם הערך role מוגדר כ-custom-role. הערך חייב להיות מחרוזת בקידוד UTF-8 באורך של עד 128 תווים. הערך צריך להתאים לתבנית: [a-zA-Z0-9][a-zA-Z0-9_]*.
persons.rank	מספר שלם – אופציונלי משמש לדירוג תפקידים. לדוגמה, עבור השחקן הראשי, role = "actor", rank = 1
persons.uri	מחרוזת – אופציונלי ה-URI של האדם.
organizations	אובייקט – אופציונלי – ניתן לחזרה נכס מפתח הבסיס להכללת הנכסים שקשורים ל-organization. לדוגמה: "organizations ":[{"name":"sports team","role":"team","rank":0,"uri":"http://example.com/team"}]
organizations.name	מחרוזת – חובה שם הארגון.
organizations.role	מחרוזת – חובה התפקיד של הארגון בפריט המדיה. ערכים נתמכים: director, actor, player, team, league, editor, author, character, contributor, creator, editor, funder, producer, provider, publisher, sponsor, translator, music-by, channel, custom-role אם אף אחד מהערכים הנתמכים לא חל על role, צריך להגדיר את role כ-custom-role ולספק את הערך בשדה custom_role.
organizations.custom_role	מחרוזת – אופציונלי הערך custom_role מוגדר אם ורק אם הערך role מוגדר כ-custom-role. הערך חייב להיות מחרוזת בקידוד UTF-8 באורך של עד 128 תווים. הערך צריך להתאים לתבנית: [a-zA-Z0-9][a-zA-Z0-9_]*.
organizations.rank	מחרוזת – אופציונלי משמש לדירוג תפקידים. לדוגמה, עבור בעל האתר הראשון: role = "publisher", rank = 1
organizations.uri	מחרוזת – אופציונלי ה-URI של הארגון.
aggregate_ratings	אובייקט – אופציונלי – ניתן לחזרה נכס מפתח בסיסי לאריזה של הנכסים הקשורים aggregate_rating.
aggregate_ratings.rating_source	מחרוזת – חובה המקור של הדירוג. לדוגמה, imdb או rotten_tomatoes. הערך חייב להיות מחרוזת בקידוד UTF-8 באורך של עד 128 תווים. הערך צריך להתאים לתבנית: [a-zA-Z0-9][a-zA-Z0-9_]*.
aggregate_ratings.rating_score	כפול – חובה הדירוג המצטבר. הדירוג צריך להיות מנורמל לטווח [1, 5].
aggregate_ratings.rating_count	מספר שלם – אופציונלי מספר הביקורות הספציפיות. הערך לא יכול להיות שלילי.

רמות המסמך

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

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

סוגים ברמת המסמך

יש שני סוגים של רמות מסמך:

• הורה מסמכי האב הם מה שחיפוש מבוסס סוכנים

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

• ילד/ה. מסמכי צאצא הם גרסאות של מסמך ההורה של קבוצה. ילדים יכולים להיות רק מסמכים בודדים. לדוגמה, אם מסמך האב הוא "תוכנית טלוויזיה לדוגמה", מסמכי הבן יכולים להיות "פרק 1" ו "פרק 2". יכול להיות שיהיה קשה להגדיר ולתחזק את סוג הרמה הזה, ולכן לא מומלץ להשתמש בו.

מידע על היררכיית מאגר הנתונים

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

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

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

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

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

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

סכימת BigQuery למדיה

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

[
  {
    "name": "id",
    "mode": "REQUIRED",
    "type": "STRING",
    "fields": []
  },
  {
    "name": "schemaId",
    "mode": "REQUIRED",
    "type": "STRING",
    "fields": []
  },
  {
    "name": "parentDocumentId",
    "mode": "NULLABLE",
    "type": "STRING",
    "fields": []
  },
  {
    "name": "jsonData",
    "mode": "NULLABLE",
    "type": "STRING",
    "fields": []
  }
]

סכימה מותאמת אישית

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

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

שם מאפיין המפתח הנדרש	הערות
title	מחרוזת – חובה כותרת המסמך ממסד הנתונים. מחרוזת מקודדת ב-UTF-8. מוגבל ל-1,000 תווים.
uri	מחרוזת – חובה ה-URI של המסמך. מגבלת אורך של 5,000 תווים.
categories	מחרוזת – חובה קטגוריות של מסמכים. המאפיין הזה חוזר על עצמו כדי לתמוך במסמך אחד ששייך לכמה קטגוריות מקבילות. כדי לקבל תוצאות באיכות גבוהה יותר, כדאי להשתמש בנתיב המלא של הקטגוריה. כדי לייצג את הנתיב המלא של קטגוריה, משתמשים בסמל > כדי להפריד בין רמות בהיררכיה. אם > הוא חלק משם הקטגוריה, מחליפים אותו בתו או בתווים אחרים. לדוגמה: "categories": [ "sports > highlight" ] מסמך יכול להכיל עד 250 קטגוריות. כל קטגוריה היא מחרוזת בקידוד UTF-8 עם מגבלה של 5,000 תווים.
media_available_time	תאריך ושעה – חובה השעה שבה התוכן זמין למשתמשי הקצה. השדה הזה מציין את עדכניות התוכן עבור משתמשי הקצה. חותמת הזמן צריכה להיות בפורמט RFC 3339. לדוגמה: "2022-08-26T23:00:17Z" כדי לסנן לפי זמינות, אפשר לעיין במאמרים סינון המלצות וסינון מסמכים זמינים.
media_duration	מחרוזת – נדרש לאפליקציות עם המלצות למדיה שבהן היעד העסקי הוא שיעור קליקים (CTR) או משך צפייה לכל סשן. משך הזמן של תוכן המדיה. משך הזמן צריך להיות מקודד כמחרוזת. הקידוד צריך להיות זהה לקידוד של מחרוזת ה-JSON google::protobuf::Duration. לדוגמה: ‎"5s", "1m" השדה הזה חשוב לאפליקציות של המלצות למדיה, שבהן היעד העסקי הוא להגדיל את שיעור ההמרה (CVR) או את משך הצפייה לכל מבקר.

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

אלה מאפייני המפתח:

שם מאפיין המפתח	הערות
description	מחרוזת – מומלץ מאוד תיאור המסמך. מגבלת אורך של 5,000 תווים.
image	אובייקט – אופציונלי – ניתן לחזרה מאפיין מפתח ברמת הבסיס שמשמש לאגד מאפיינים שקשורים לתמונה.
image_name	מחרוזת – אופציונלי שם התמונה. אורך מוגבל של 128 תווים.
image_uri	מחרוזת – אופציונלי ה-URI של התמונה. מגבלת אורך של 5,000 תווים.
language_code	מחרוזת – אופציונלי השפה של שם הפריט, התיאור ומאפיינים אחרים מסוג מחרוזת. צריך להשתמש בתגי שפה שמוגדרים על ידי BCP 47. במקרה של המלצות למסמכים, המערכת מתעלמת מהשדה הזה ומזהה את שפת הטקסט באופן אוטומטי. המסמך יכול לכלול טקסט בשפות שונות, אבל שכפול מסמכים כדי לספק טקסט בשפות שונות עלול לגרום לירידה בביצועים. השדה הזה נמצא בשימוש בחיפוש מסמכים. אם לא מגדירים ערך, ברירת המחדל היא en-US. לדוגמה, "language_code": "en-US". במקרה של מדיה, כמו סרטים, שיש לה מטא-נתונים בכמה שפות, צריך להתייחס לכל גרסה בשפה אחרת כמסמך נפרד. לכל גרסה יש כותרת, תיאור, קטגוריות ושדות מאפיינים אחרים משלה בשפה הרלוונטית. כדי להבחין בין גרסאות בשפות שונות, משתמשים במאפיין language_code. המאפיין הזה מאפשר גם לסנן את תוצאות החיפוש בצד השרת, כך שרק תוכן מדיה בשפה הרלוונטית יוחזר עבור שאילתה.
media_aggregated_rating	אובייקט – אופציונלי – ניתן לחזרה נכס מפתח בסיסי לאריזה של הנכסים הקשורים aggregate_rating.
media_aggregated_rating_count	מספר שלם – אופציונלי מספר הביקורות הספציפיות. הערך לא יכול להיות שלילי.
media_aggregated_rating_score	כפול – חובה הדירוג המצטבר. הדירוג צריך להיות מנורמל לטווח [1, 5].
media_aggregated_rating_source	מחרוזת – חובה המקור של הדירוג. לדוגמה, imdb או rotten_tomatoes. הערך חייב להיות מחרוזת בקידוד UTF-8 באורך של עד 128 תווים. הערך צריך להתאים לתבנית: [a-zA-Z0-9][a-zA-Z0-9_]*.
media_content_index	מספר שלם – אופציונלי אינדקס התוכן של מסמך המדיה. אפשר להשתמש בשדה של אינדקס התוכן כדי לסדר את המסמכים ביחס למסמכים אחרים. לדוגמה, אפשר להשתמש במספר הפרק כמדד לתוכן. אינדקס התוכן צריך להיות מספר שלם לא שלילי. לדוגמה: "content_index": 0
media_content_rating	מחרוזת – אופציונלי – חוזר סיווג התוכן, שמשמש למערכות של אזהרות לגבי תוכן ולסינון תוכן על סמך הקהל. אפשר להזין עד 100 ערכים לכל מסמך, והאורך המקסימלי הוא 128 תווים. אפשר להשתמש בתג הזה כדי לסנן את תוצאות ההמלצות על ידי העברת התג כחלק מהתג RecommendRequest.filter. לדוגמה: content_rating: ["PG-13"]
media_country_of_origin	מחרוזת – אופציונלי מדינת המקור של מסמך המדיה. אורך מוגבל של 128 תווים. לדוגמה: "country_of_origin": "US"
media_expire_time	תאריך ושעה – אופציונלי הזמן שבו הגישה לתוכן תפוג עבור משתמשי הקצה. השדה הזה מציין את עדכניות התוכן עבור משתמשי הקצה. חותמת הזמן צריכה להיות בפורמט RFC 3339. לדוגמה: "2032-12-31T23:00:17Z" כדי להחריג מסמכים שתוקפם פג מהתוצאות, אפשר לעיין במאמרים בנושא סינון המלצות וסינון חיפוש מדיה.
live_event_start_time	תאריך ושעה – אופציונלי השעה שבה האירוע בשידור חי מתחיל. חותמת הזמן צריכה להיות בפורמט RFC 3339. לדוגמה: "2020-12-31T23:00:17Z"
live_event_end_time	תאריך ושעה – אופציונלי השעה שבה האירוע החי מסתיים. חותמת הזמן צריכה להיות בפורמט RFC 3339. לדוגמה: "2024-01-28T23:00:17Z"
media_filter_tag	מחרוזת – אופציונלי – חוזר מסננים את התגים של המסמך. אפשר להזין לכל היותר 250 ערכים לכל מסמך, עם מגבלת אורך של 1,000 תווים. אחרת, מוחזרת שגיאת INVALID_ARGUMENT. אפשר להשתמש בתג הזה כדי לסנן את תוצאות ההמלצות על ידי העברת התג כחלק מהתג RecommendRequest.filter. לדוגמה: "filter_tags": [ "filter_tag"]
media_hash_tag	מחרוזת – אופציונלי – חוזר האשטאגים למסמך. אפשר להזין עד 100 ערכים לכל מסמך, עם מגבלת אורך של 5,000 תווים. לדוגמה: "hash_tags": [ "soccer", "world cup"]
media_in_language	מחרוזת – אופציונלי – חוזר השפה של תוכן המדיה. צריך להשתמש בתגי שפה שמוגדרים על ידי BCP 47. לדוגמה: "in_languages": [ "en-US"]
media_organization	אובייקט – אופציונלי – ניתן לחזרה נכס מפתח הבסיס להכללת הנכסים שקשורים ל-organization. לדוגמה: "organizations ":[{"name":"sports team","role":"team","rank":0,"uri":"http://example.com/team"}]
media_organization_custom_role	מחרוזת – אופציונלי הערך custom_role מוגדר אם ורק אם הערך role מוגדר כ-custom-role. הערך חייב להיות מחרוזת בקידוד UTF-8 באורך של עד 128 תווים. הערך צריך להתאים לתבנית: [a-zA-Z0-9][a-zA-Z0-9_]*.
media_organization_name	מחרוזת – חובה שם הארגון.
media_organization_rank	מחרוזת – אופציונלי משמש לדירוג תפקידים. לדוגמה, עבור בעל תוכן דיגיטלי ראשון: role = "publisher", rank = 1.
media_organization_role	מחרוזת – חובה התפקיד של הארגון בפריט המדיה. ערכים נתמכים: director, actor, player, team, league, editor, author, character, contributor, creator, editor, funder, producer, provider, publisher, sponsor, translator, music-by, channel, custom-role אם אף אחד מהערכים הנתמכים לא חל על role, צריך להגדיר את role כ-custom-role ולספק את הערך בשדה custom_role.
media_organization_uri	מחרוזת – אופציונלי ה-URI של הארגון.
media_person	אובייקט – אופציונלי – ניתן לחזרה נכס מפתח בסיסי להוספת מאפיינים שקשורים לאדם. לדוגמה: "persons":[{"name":"sports person","role":"player","rank":0,"uri":"http://example.com/person"}]
media_person_custom_role	מחרוזת – אופציונלי הערך custom_role מוגדר אם ורק אם הערך role מוגדר כ-custom-role. הערך חייב להיות מחרוזת בקידוד UTF-8 באורך של עד 128 תווים. הערך צריך להתאים לתבנית: [a-zA-Z0-9][a-zA-Z0-9_]*.
media_person_name	מחרוזת – חובה שם האדם.
media_person_rank	מספר שלם – אופציונלי משמש לדירוג תפקידים. לדוגמה, עבור השחקן הראשי, role = "actor", rank = 1
media_person_role	מחרוזת – חובה התפקיד של האדם בפריט המדיה. ערכים נתמכים: director, actor, player, team, league, editor, author, character, contributor, creator, editor, funder, producer, provider, publisher, sponsor, translator, music-by, channel, custom-role אם אף אחד מהערכים הנתמכים לא חל על role, צריך להגדיר את role כ-custom-role ולספק את הערך בשדה custom_role.
media_person_uri	מחרוזת – אופציונלי ה-URI של האדם.
media_production_year	מספר שלם – אופציונלי השנה שבה המדיה הופקה.
media_transcript	מחרוזת – אופציונלי תמליל של מסמך המדיה.
media_type	מחרוזת – חובה למלא את השדה הזה לסרטים ולתוכניות קטגוריה ברמה העליונה. סוגים נתמכים: movie,‏ show, concert,‏ event,‏ live-event, broadcast,‏ tv-series,‏ episode, video-game,‏ clip,‏ vlog, audio,‏ audio-book,‏ music, album,‏ articles,‏ news, radio,‏ podcast,‏ book ו-sports-game. לערכים movie ו-show יש משמעות מיוחדת. הם גורמים להעשרת המסמכים באופן שמשפר את הדירוג ועוזר למשתמשים שמחפשים כותרות למצוא תוכן חלופי שעשוי לעניין אותם.

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