הטמעה: סרטונים

בדוגמאות הבאות אפשר לראות איך משתמשים ב-YouTube Data API (גרסה 3) כדי לבצע פונקציות שקשורות לסרטונים.

אחזור של סרטונים שהועלו לערוץ

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

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

כדי לאחזר את רשימת הסרטונים הפופולריים ביותר, קוראים לשיטה videos.list ומגדירים את הערך של הפרמטר chart ל-mostPopular. בטבלה mostPopular מופיעים סרטונים פופולריים של מוזיקה, סרטים ומשחקים.

אחר כך, אפשר להגדיר את הפרמטרים הבאים:

  • ‫regionCode: מנחה את ה-API להחזיר רשימה של סרטונים באזור שצוין. ערך הפרמטר הוא קוד מדינה לפי תקן ISO 3166-1 alpha-2. אפשר להשתמש בשיטה i18nRegions.list כדי לאחזר רשימה של קודי אזורים ש-YouTube תומך בהם.
  • ‫videoCategoryId: מזהה את קטגוריית הסרטונים שצריך לאחזר את הסרטונים הכי פופולריים שלה. אפשר להשתמש ב-method‏ videoCategories.list כדי לאחזר רשימה של מזהי קטגוריות ש-YouTube תומך בהן.

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

https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.videos.list?
        part=snippet
        &chart=mostPopular
        &regionCode=es
        &videoCategoryId=17

אחזור של סטטיסטיקת סרטונים בקבוצה

בדוגמה הזו מאחזרים נתונים סטטיסטיים של רשימת סרטונים באמצעות השיטה videos.batchGetStats.

כדי להשתמש בשיטה הזו, צריך להגדיר את הפרמטר id של הבקשה לרשימה של מזהי סרטונים ב-YouTube שמופרדים באמצעות פסיקים, שלגביהם רוצים לאחזר נתונים סטטיסטיים. מגדירים את הערך של הפרמטר part לרשימה מופרדת בפסיקים של חלקי המשאב videoStat שרוצים שהתשובה תכלול. החלקים הנתמכים הם snippet,‏ statistics,‏ contentDetails ו-id.

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

הבקשה הבאה מאחזרת נתונים סטטיסטיים לגבי מזהי הסרטונים VIDEO_ID_1 ו-VIDEO_ID_2:

https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.videos.batchGetStats?
        part=snippet,statistics
        &id=VIDEO_ID_1,VIDEO_ID_2

העלאת סרטון

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

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

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

  • בדוגמה של JavaScript להעלאת סרטון נעשה שימוש ב-CORS (שיתוף משאבים בין מקורות) כדי להדגים איך להעלות קובץ סרטון דרך דף אינטרנט. ספריית ההעלאה של CORS שמשמשת את API גרסה 3 תומכת באופן טבעי בהעלאה שניתן להשהות ולהמשיך. בנוסף, בדוגמה מוצג איך לבדוק את הסטטוס של סרטון שהועלה על ידי אחזור החלק processingDetails של משאב video, וגם איך לטפל בשינויים בסטטוס של הסרטון שהועלה.

בדיקת הסטטוס של סרטון שהועלה

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

  • שלב 1: מעלים את הסרטון

    קוראים לשיטה videos.insert כדי להעלות את הסרטון. אם הבקשה מצליחה, תגובת ה-API תכיל משאב video שמזהה את מזהה הסרטון הייחודי של הסרטון שהועלה.

  • שלב 2: בדיקת הסטטוס של הסרטון

    מפעילים את ה-method videos.list כדי לבדוק את סטטוס הסרטון. מגדירים את הערך של הפרמטר id למזהה הסרטון שהתקבל בשלב 1. מגדירים את הערך של הפרמטר part ל-processingDetails.

    אם הטיפול בבקשה יסתיים בהצלחה, תגובת ה-API תכיל משאב video. צריך לבדוק את הערך של המאפיין processingDetails.processingStatus כדי לדעת אם מערכת YouTube עדיין מעבדת את הסרטון. הערך של המאפיין ישתנה ממצב processing למצב אחר, כמו succeeded או failed, כשמערכת YouTube תסיים לעבד את הסרטון.

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

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

    https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.videos.list?
        part=snippet,processingDetails
        &id=VIDEO_ID

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

עדכון סרטון

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

  • שלב 1: מאחזרים את מזהה הסרטון

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

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

  • שלב 2: עדכון סרטון

    קוראים לשיטה videos.update כדי לעדכן סרטון ספציפי. מגדירים את הערך של הפרמטר part ל-recordingDetails. (הערך של הפרמטר תלוי בשדות המטא-נתונים של הסרטון שמעדכנים).

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

    בדוגמה הבאה של משאב אפשר לראות שהסרטון צולם ב-30 באוקטובר 2013 בבוסטון:

    {
  "id": "VIDEO_ID",
  "recordingDetails": {
    "location": {
      "latitude": "42.3464",
      "longitude": "-71.0975"
    }
    "recordingDate": "2013-10-30T23:15:00.000Z"
  }
}

    כדי להשלים את הבקשה ב-APIs Explorer, צריך להגדיר את הערך של המאפיין id.

    https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.videos.update?
        part=snippet

העלאה של תמונה ממוזערת מותאמת אישית והגדרתה לסרטון

אפשר להשתמש בשיטה thumbnails.set של v3 API כדי להעלות תמונה ממוזערת מותאמת אישית ולהגדיר אותה לסרטון. בבקשה, הערך של הפרמטר videoId מזהה את הסרטון שבו תשתמשו בתמונה הממוזערת.

אי אפשר לבדוק את השאילתה הזו באמצעות API Explorer כי הוא לא תומך בהעלאה של קובצי מדיה, שנדרשת לשיטה הזו.

דוגמאות קוד קשורות: PHP, ‏ Python

מחיקת סרטון

בדוגמה הזו מוסבר איך למחוק סרטון. הדוגמה כוללת את השלבים הבאים:

  • שלב 1: מאחזרים את מזהה הסרטון

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

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

  • שלב 2: מחיקת סרטון

    מפעילים את שיטת videos.delete כדי למחוק סרטון ספציפי. בבקשה, הפרמטר id מציין את מזהה הסרטון שרוצים למחוק. הבקשה צריכה להיות מאושרת באמצעות OAuth 2.0. אם אתם בודקים את השאילתה הזו ב-APIs Explorer, תצטרכו להחליף את הערך של הפרמטר id במזהה סרטון תקין.

    https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.videos.delete?
        id=VIDEO_ID

דיווח על סרטון פוגע

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

  • שלב 1: אחזור מזהים שמסבירים למה הסרטון מדווח

    שולחים בקשה מורשית לשיטה videoAbuseReportReasons.list כדי לאחזר רשימה של סיבות תקפות לסימון סרטון. בדוגמה של משאב videoAbuseReportReason שמופיעה בהמשך יש מידע על סימון סרטון שמכיל ספאם או תוכן מטעה.

    {
  "kind": "youtube#videoAbuseReportReason",
  "etag": "\"tbWC5XrSXxe1WOAx6MK9z4hHSU8/Or2VqBIilpHU7j__oPzUFCvGVBw\"",
  "id": "S",
  "snippet": {
    "label": "Spam or misleading",
    "secondaryReasons": [
      {
        "id": "27",
        "label": "Spam or mass advertising"
      },
      {
        "id": "28",
        "label": "Misleading thumbnail"
      },
      {
        "id": "29",
        "label": "Malware or phishing"
      },
      {
        "id": "30",
        "label": "Pharmaceutical drugs for sale"
      },
      {
        "id": "31",
        "label": "Other misleading info"
      }
    ]
  }
}

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

  • שלב 2: דיווח על הסרטון בגלל תוכן פוגע

    שולחים בקשה מורשית לשיטה videos.reportAbuse כדי לדווח על הסרטון. גוף הבקשה הוא אובייקט JSON שמזהה את הסרטון שמסומן ואת הסיבה לסימון. כמו שצוין בשלב 1, עבור סוגים מסוימים של סיבות, יש תמיכה בסיבה משנית, ומומלץ מאוד לציין אותה.

    המאפיין videoId של אובייקט ה-JSON מזהה את הסרטון שמסומן.

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

    {
  "videoId": "VIDEO_ID",
  "reasonId": "S",
  "secondaryReasonId": "28",
  "comments": "Testing the video flagging feature.",
  "language": "en"
}

    צריך לאשר את הבקשה videos.reportAbuse באמצעות OAuth 2.0. הקישור שלמטה טוען את אובייקט ה-JSON שלמעלה בכלי APIs Explorer. כדי לבדוק את השאילתה, צריך להחליף את ערך המאפיין videoId במזהה סרטון תקין. חשוב לזכור ששליחת הבקשה הזו תגרום לסימון הסרטון.

    https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.videos.reportAbuse