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

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

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

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

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

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

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

  • ‫regionCode: מורה ל-API להחזיר רשימה של סרטונים לאזור שצוין. ערך הפרמטר הוא קוד מדינה מסוג ISO 3166-1 alpha-2. אתם יכולים להשתמש ב-method‏ 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: בודקים את סטטוס הסרטון

    מפעילים את השיטה 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

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

הגדרת גישה (הוספה)

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

POST /youtube/v3/videos?part=snippet,status,brandPartner
{
  "snippet": {
    "title": "Video Title",
    "description": "Video Description",
    "categoryId": "22"
  },
  "status": {
    "privacyStatus": "private"
  },
  "brandPartner": {
    "channelHandle": "@brandchannel"
  }
}

רק ה-channelId שנפתרו יוחזרו בתגובה.

עדכון או הסרה של הרשאת גישה (עדכון)

כדי לעדכן את הגישה לערוץ מותג אחר, או כדי להסיר את הגישה, צריך להפעיל את ה-method‏ videos.update עם brandPartner בפרמטר part.

כדי להחליף את הגישה, צריך לציין את הערך החדש של channelId או channelHandle בגוף הבקשה:

PUT /youtube/v3/videos?part=brandPartner
{
  "id": "VIDEO_ID",
  "brandPartner": {
    "channelId": "UC_SOME_BRAND_CHANNEL_ID"
  }
}

כדי להסיר את הגישה, שולחים בקשה עם brandPartner בפרמטר part, אבל עם אובייקט brandPartner ריק בגוף הבקשה:

PUT /youtube/v3/videos?part=brandPartner
{
  "id": "VIDEO_ID",
  "brandPartner": {}
}

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

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

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

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

מחיקת סרטון

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

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

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

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

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

    מבצעים קריאה ל-method‏ 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: מאחזרים את המזהים שמסבירים למה הסרטון דווח

    שולחים בקשה מורשית ל-method‏ 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: מסמנים את הסרטון כתוכן פוגעני

    שולחים בקשה מורשית ל-method‏ 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