ניהול נכסי יצירה

הערה: ממשק YouTube Content ID API מיועד לשימוש של שותפי תוכן של YouTube, והוא אינו נגיש לכל המפתחים או לכל משתמשי YouTube. אם אינכם רואים את YouTube Content ID API כאחד מהשירותים המפורטים בGoogle API Console, מומלץ לעיין במרכז העזרה של YouTube כדי לקבל מידע נוסף על תוכנית השותפים של YouTube.

הערה: המידע במדריך הזה מתייחס באופן ספציפי לנכסי יצירה.

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

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

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

מסמך זה מספק סקירה כללית של מודל הנכס מסוג יצירה ב-YouTube. בנוסף, מוסבר בו איך שני סוגי נכסי היצירה משמשים בשיטות API של Content ID ב-YouTube.

הסבר על מודל הנכס מסוג יצירה מוזיקלית

מודל הנכסים של YouTube מגדיר שתי ייצוגים שונים של נכסי יצירה:

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

    ניתן לשייך פרטי שותפות ביצירה להקלטות אודיו רבות.

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

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

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

התרשים הבא ממחיש את המודל הזה. בתרשים:

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

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

שני סוגים של מזהי נכסים

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

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

אם תביטו בתרשים בקטע הקודם, תוכלו לראות שהקלטות האודיו והצפיות ביצירה מסומנות במספרים (SR1, CV1 וכו'). המספרים משקפים את היחסים ביחס של 1:1 בין הקלטות אודיו לבין הצפיות ביצירה. לכן, אם רוצים לאחזר את הקבוצה הקנונית של המידע על היצירה בהקלטת אודיו מסוימת, צריך להשתמש ב-viewId ליצירה הזו.

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

שימוש במזהי נכסים בשיטות API

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

  1. צריך להפעיל את השיטה assets.insert כדי ליצור נכס של יצירה מוזיקלית. תגובת ה-API היא משאב asset שבו המאפיין id הוא shareId.

  2. כדי להגדיר נתוני בעלות לגבי פרטי השותפות ביצירה, צריך לבצע קריאה ל-method ownership.update. מגדירים את הפרמטר assetId של השיטה לערך shareId שהתקבל בשלב 1.

  3. כדי להגדיר נתוני מדיניות של פרטי השותפות ביצירה, צריך להפעיל את השיטה assetMatchPolicy.update. המדיניות חלה על סרטונים שמכילים את היצירה שהוגשה לגביהם תלונה על הפרת זכויות יוצרים. מגדירים את הפרמטר assetId של השיטה לערך shareId שהתקבל בשלב 1.

  4. צריך להפעיל את השיטה assetRelationships.insert כדי לזהות הקלטות אודיו שמכילות את היצירה המוזיקלית. במשאב assetRelationship שברצונך להוסיף, צריך להגדיר את המאפיין parentAssetId כמזהה הנכס של הקלטת האודיו. מגדירים את המאפיין childAssetId ל-shareId שהתקבל בשלב 1.

  5. אם שומרים מיפוי של viewIds ל-shareIds, אפשר לאחזר את viewId על ידי קריאה לשיטה assetRelationships.list והגדרת הפרמטר assetId למזהה הנכס של הקלטת האודיו. קשר אחד בקבוצת התוצאות יזהה את מזהה הנכס של הקלטת האודיו בתור parentAssetId. באותו קשר, childAssetId מזהה את viewId שממופה אל shareId שהושג בשלב 1.

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

assets.get/assets.list

השיטות assets.get ו-assets.list מאחזרות מידע על נכס או רשימת נכסים. שתי שיטות ההעברה תומכות באותה קבוצה של פרמטרים של בקשה.

שלושה מהפרמטרים האלה – fetchMatchPolicy, fetchMetadata ו-fetchOwnership – משתמשים בערכים effective ו-mine כדי לציין אם רוצים לאחזר את קבוצת הנתונים הקנונית של הנכס או אם רוצים לאחזר נתונים שסיפקתם לגבי הנכס. הערכים האלה הם העתק של מודל הנכסים הישן של YouTube ביצירה, שמתייחס לצפייה ביצירה ולאחוזי השותפות ביצירה כישות אחת.

עם זאת, הערכים עדיין נתמכים במודל הדו-שכבתי, והתוכן של תגובת ה-API תלוי גם בערך הפרמטר וגם בשאלה אם הבקשות מספקות shareIds או viewIds. שימו לב שהשיטה assets.get משתמשת בפרמטר assetId כדי לציין את מזהה הנכס, ואילו השיטה assets.list משתמשת בפרמטר id.

ברשימה שבהמשך מוסבר איך ערכי הפרמטרים של בקשות משפיעים על התוכן של תגובות ה-API בשתי השיטות האלה.

  • fetchMatchPolicy
    • אם מזהה הנכס (הפרמטר id או assetId) מציין shareId:
      • אם הפרמטר fetchMatchPolicy הוא mine, תגובת ה-API תכלול את המדיניות שלפיה בעל התוכן מאשר את בקשת ה-API שהוגדרה עבור פרטי השותפות ביצירה.
      • אם הפרמטר fetchMatchPolicy הוא effective, ה-API מחזיר את השגיאה 400.
    • אם במזהה הנכס מצוין viewId:
      • אם הפרמטר fetchMatchPolicy הוא mine, ובעל התוכן שמאשר את הבקשה הוא הבעלים של נכס שותפות אחד בלבד ביצירה שמקושר למזהה התצוגה המפורטת, ה-API יחזיר את מדיניות ההתאמה שהוגדרה עבור אותו שיתוף ביצירה.
      • אם הפרמטר fetchMatchPolicy הוא mine, ובעל התוכן שמאשר את הבקשה יש מספר שיתופים של יצירה שמקושרים למזהה התצוגה המפורטת, ה-API יחזיר שגיאת 400.
      • אם הפרמטר fetchMatchPolicy הוא effective, ה-API מחזיר את מדיניות ההתאמה הקנונית עבור תצוגת היצירה. מדיניות ההתאמה הזו משקללת את מדיניות ההתאמה של כל שיתופי הפעולה ביצירה שמקושרים אל viewId, ללא קשר לבעלי התוכן שהשיתופים האלה בבעלותם.
  • fetchMetadata
    • אם במזהה הנכס מצוין shareId:
      • אם הפרמטר fetchMetadata הוא mine, תגובת ה-API מכילה את המטא-נתונים של הנכס שבעלי התוכן מאשרים את בקשת ה-API שהוגדרה עבור השותפות ביצירה.
      • אם הפרמטר fetchMetadata הוא effective, ה-API מחזיר את השגיאה 400.
    • אם במזהה הנכס מצוין viewId:
      • אם הפרמטר fetchMetadata הוא mine, ובעל התוכן שמאשר את הבקשה יש רק נכס שותפות אחד ביצירה שמקושר למזהה התצוגה המפורטת, ה-API יחזיר את המטא-נתונים שהוגדרו עבור פרטי השותפות ביצירה.
      • אם הפרמטר fetchMetadata הוא mine, ובעל התוכן שמאשר את הבקשה יש מספר שיתופים של יצירה שמקושרים למזהה התצוגה המפורטת, ה-API יחזיר שגיאת 400.
      • אם הפרמטר fetchMetadata הוא effective, ה-API מחזיר את הקבוצה הקנונית של המטא-נתונים של תצוגת היצירה. המטא-נתונים האלה משקפים את המטא-נתונים של הנכסים שסופקו לכל שיתופי הפעולה ביצירה שמקושרים אל viewId, בלי קשר לבעלים של השיתופים האלה.
  • fetchOwnership
    • אם במזהה הנכס מצוין shareId:
      • אם הפרמטר fetchOwnership הוא mine, תגובת ה-API מכילה את נתוני הבעלות שבעלי התוכן מאשר את בקשת ה-API שהוגדרה עבור השותפות ביצירה.
      • אם הפרמטר fetchOwnership הוא effective, ה-API מחזיר את השגיאה 400.
    • אם במזהה הנכס מצוין viewId:
      • אם הפרמטר fetchOwnership הוא mine, ובעל התוכן שמאשר את הבקשה יש רק נכס אחד של שותפות ביצירה שמקושר למזהה התצוגה המפורטת, ה-API יחזיר את נתוני הבעלות שהוגדרו לאותה שותפות ביצירה.
      • אם הפרמטר fetchOwnership הוא mine, ובעל התוכן שמאשר את הבקשה יש מספר שיתופים של יצירה שמקושרים למזהה התצוגה המפורטת, ה-API יחזיר שגיאת 400.
      • אם הפרמטר fetchOwnership הוא effective, ה-API מחזיר את נתוני הבעלות הקנוניים עבור תצוגת היצירה. הנתונים האלה מביאים בחשבון את נתוני הבעלות של כל שיתופי הפעולה ביצירה שמקושרים אל viewId, בלי קשר לבעלי התוכן שהשיתופים האלה בבעלותם.
  • fetchOwnershipConflicts
    • אם במזהה הנכס מצוין shareId, ה-API יחזיר את תגובת השגיאה 400.
    • אם במזהה הנכס מצוין viewId, ה-API יחזיר רשימה של מחלוקות בנושא בעלות המשויכות לתצוגת היצירה.

assets.insert

השיטה הזו יוצרת משאב asset, ומערכת YouTube מקצה מזהה לזיהוי ייחודי של המשאב. המזהה הזה, שמוחזר כערך המאפיין id בתגובת ה-API, הוא shareId.

הערה: חשוב לזכור שהנכסים shareIds ו-viewIds משמשים רק לנכסי יצירה. בסוגים אחרים של נכסים לא נעשה שימוש במודל דו-שכבתי לניהול נתוני נכסים.

assets.update ו-Asset.patch

השיטות האלה מעדכנות את המטא-נתונים של נכס. בשתי הבקשות, הפרמטר assetId מזהה את הנכס שמתעדכן. בנוסף, בשתי הבקשות, גוף הבקשה הוא משאב asset שבו ערך המאפיין id חייב להתאים לערך הפרמטר assetId.

  • אם בפרמטר assetId ובמאפיין id צוין shareId, בקשת ה-API מעדכנת את פרטי השותפות ביצירה שצוינו.
  • אם הפרמטר assetId והמאפיין id מציינים viewId, ובבעל התוכן שמאשר את הבקשה הוא הבעלים של נכס שותפות אחד בלבד ביצירה שמקושרת לאותו viewId, בקשת ה-API מעדכנת את פרטי השותפות ביצירה.
  • אם בפרמטר assetId ובמאפיין id צוין viewId, ובעל התוכן שמאשר את הבקשה יש מספר ממשקי יצירה המקושרים לאותו viewId, בקשת ה-API תחזיר שגיאת 400.

assetMatchPolicy.get

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

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

assetMatchPolicy.update ו-AssetMatchPolicy.patch

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

  • אם בפרמטר assetId מצוין shareId, בקשת ה-API מעדכנת את מדיניות ההתאמה של פרטי השותפות ביצירה.
  • אם בפרמטר assetId מצוין viewId, ובעל התוכן שמאשר את הבקשה יש רק נכס אחד של שיתוף ביצירה שמקושר לאותו viewId, בקשת ה-API מעדכנת את מדיניות ההתאמה עבור פרטי השותפות ביצירה.
  • אם בפרמטר assetId מצוין viewId, ובעל התוכן שמאשר את הבקשה יש מספר ממשקי יצירה שמקושרים לאותו viewId, בקשת ה-API תחזיר את השגיאה 400.

assetRelationships.list

השיטה הזו מחזירה רשימה של קשרי גומלין בנכס שצוין. הפרמטר assetId של הבקשה מזהה את הנכס.

  • אם בפרמטר assetId מצוין shareId, תגובת ה-API תכלול רשימה של נכסים מקושרים של הקלטות אודיו. הרשימה עשויה להכיל מספר פריטים. בכל משאב assetRelationship, מזהה הנכס של הקלטת האודיו הוא parentAssetId, וה-shareId הוא childAssetId.
  • אם הפרמטר assetId מציין viewId, תגובת ה-API מזהה את הקלטת האודיו שמקושרת לאותו viewId. התשובה כוללת משאב אחד לכל היותר.
  • אם הפרמטר assetId מזהה נכס של הקלטת אודיו, תגובת ה-API יכולה לכלול כמה קשרי גומלין.
    • אם מזהה הנכס של הקלטת האודיו הוא parentAssetId במשאב assetRelationship שהוחזר, childAssetId מזהה את תצוגת היצירה (viewId) המקושרת להקלטת האודיו הזו. לכל הקלטת אודיו יש קשר אחד בלבד כזה.
    • אם מזהה הנכס של הקלטת האודיו הוא childAssetId, parentAssetId מציין סרטון שמכיל את הקלטת האודיו, למשל סרטון מוזיקה או סרטון מוזיקה עם תמונה סטטית. לכל הקלטת אודיו יכולים להיות כמה קשרים כאלה.

assetRelationships.insert

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

במשאב assetRelationship שבגוף הבקשה, מגדירים את המאפיין parentAssetId כמזהה הנכס של הקלטת האודיו. מגדירים את המאפיין childAssetId לערך shareId.

assetSearch.list

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

  • אם המשאב assetSearch מזהה יצירה, ערך המאפיין id יהיה shareId.

assetShares.list

השיטה הזו מחזירה מיפוי של תצוגות של יצירה מוזיקלית ביחס לפרטי שותפות ביצירה. הפרמטר assetId של הבקשה יכול לציין viewId או shareId.

  • אם בפרמטר assetId מצוין viewId, תגובת ה-API תכלול רשימה של assetShare משאבים. כל משאב מציין פרטי שותפות ביצירה שמקושרים לתצוגה המפורטת של היצירה שצוינה, ונמצא בבעלותו של בעל התוכן שאישר את הבקשה.

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

  • אם בפרמטר assetId מצוין shareId, תגובת ה-API תכלול רשימה של assetShare משאבים. כל משאב מזהה תצוגת יצירה המשויכת לפרטי השותפות שצוינו ביצירה. התשובה תכלול משאב אחד לכל הקלטת אודיו שאליה מקושר פרטי השותפות ביצירה. (כל הקלטת קול מקושרת לתצוגה אחת של יצירה מוזיקלית בלבד).

claimSearch.list

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

  • אם בבקשת ה-API צוין shareId, ה-API יחזיר קוד תגובה 400.

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

metadataHistory.list

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

  • אם בבקשת ה-API צוין shareId, ה-API מחזיר את קבוצת המטא-נתונים העדכנית ביותר עבור פרטי השותפות ביצירה.

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

ownership.get

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

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

owner.update ו-Ownership.patch

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

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

ownershipHistory.list

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

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

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