YouTube Reporting API - System-Managed Reports

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

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

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

אחזור דוחות

בשלבים הבאים מוסבר איך לאחזר דוחות שמנוהלים על ידי המערכת דרך ה-API.

שלב 1: אחזור פרטי הכניסה להרשאה

כל הבקשות של YouTube Reporting API צריכות להיות מאושרות. במדריך ההרשאות מוסבר איך להשתמש בפרוטוקול OAuth 2.0 כדי לאחזר אסימוני הרשאה.

בקשות של YouTube Reporting API משתמשות בהיקפי ההרשאות הבאים:

רמות
https://www.googleapis.com/auth/yt-analytics.readonly עיון בדוחות YouTube Analytics עבור התוכן שלך ב-YouTube. היקף ההרשאות הזה נותן גישה למדדים של פעילות המשתמשים, כמו ספירת צפיות וספירות של דירוגים.
https://www.googleapis.com/auth/yt-analytics-monetary.readonly הצג דוחות כספיים של YouTube Analytics עבור התוכן שלך ב-YouTube. ההיקף הזה נותן גישה למדדים של פעילות המשתמשים ולמדדים של ההכנסות המשוערות ושל ביצועי המודעות.

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

צריך להפעיל את השיטה jobs.list כדי לאחזר רשימה של משימות המנוהלות על ידי המערכת. מגדירים את הפרמטר includeSystemManaged לערך true.

המאפיין reportTypeId בכל משאב Job שמוחזר מזהה את סוג הדוח בניהול המערכת שמשויך למשימה הזו. לאפליקציה שלך נדרש ערך המאפיין id מאותו משאב בשלב הבא.

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

שלב 3: אחזור כתובת ה-URL להורדת הדוח

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

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

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

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

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

תגובת ה-API כוללת רשימה של Report משאבים שרלוונטיים למשימה הזו. כל משאב מתייחס לדוח שמכיל נתונים מתקופה ייחודית.

  • המאפיינים startTime ו-endTime של המשאב מזהים את תקופת הזמן שמתייחסת לנתוני הדוח.
  • המאפיין downloadUrl של המשאב מזהה את כתובת ה-URL שממנה ניתן לאחזר את הדוח.

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

שלב 4: הורדת הדוח

שולחים בקשת HTTP GET אל downloadUrl שהתקבלה בשלב 4 כדי לאחזר את הדוח.

עיבוד דוחות

שיטות מומלצות

אפליקציות שמשתמשות ב-YouTube Reporting API צריכות תמיד לפעול לפי השיטות הבאות:

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

  • רשמו לעצמכם את הדוחות שהורדתם כדי לא לעבד את אותו דוח שוב ושוב. הרשימה הבאה מציעה כמה דרכים לעשות זאת.

    • כשמבצעים קריאה ל-method reports.list, צריך להשתמש בפרמטר createdAfter כדי לאחזר רק דוחות שנוצרו לאחר תאריך מסוים. (יש להשמיט את הפרמטר createdAfter בפעם הראשונה שמאחזרים דוחות).

      בכל פעם שמאחזרים ומעבדים דוחות בהצלחה, חשוב לשמור את חותמת הזמן שתואמת לתאריך ולשעה שבהם נוצר הדוח העדכני ביותר. לאחר מכן, צריך לעדכן את ערך הפרמטר createdAfter בכל קריאה עוקבת ל-method reports.list, כדי להבטיח בכל פעם שמאחזרים דוחות חדשים, כולל דוחות חדשים עם נתונים שמולאו חוסרים (backfill).

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

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

      אפשר להשתמש במזהה הדוח כדי לזהות דוחות שעדיין צריך להוריד ולייבא. עם זאת, אם לשני דוחות חדשים יש אותם ערכי נכס startTime ו-endTime, ייבא את הדוח רק עם הערך החדש יותר של createTime.

מאפייני הדוח

דוחות API הם קובצי גרסאות .csv (ערכים המופרדים באמצעות פסיקים) בעלי המאפיינים הבאים:

  • כל דוח מכיל נתונים מתקופה ייחודית שנמשכת 00:00 (שעון החוף המערבי) בתאריך ההתחלה של הדוח ועד השעה 23:59 (שעון החוף המערבי) בתאריך הסיום של הדוח.

  • נתוני הדוח לא ממוינים.