Captions: insert

העלאת רצועת כתוביות.

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

  • גודל קובץ מקסימלי: 100MB
  • סוגי MIME מקובלים של מדיה: text/xml, ‏ application/octet-stream, ‏ */*

השפעה על המכסה: לקריאה לשיטה הזו יש עלות מכסה של 400 יחידות.

תרחישים נפוצים לדוגמה

בקשה

בקשת HTTP

POST https://www.googleapis.com/upload/youtube/v3/captions

אישור

הבקשה הזו דורשת הרשאה עם לפחות אחד מההיקפים הבאים. למידע נוסף על אימות והרשאה, קראו את המאמר הטמעת הרשאה של OAuth 2.0.

היקף
https://www.googleapis.com/auth/youtube.force-ssl
https://www.googleapis.com/auth/youtubepartner

פרמטרים

בטבלה הבאה מפורטים הפרמטרים שהשאילתה הזו תומכת בהם. כל הפרמטרים שמפורטים הם פרמטרים של שאילתות.

פרמטרים
פרמטרים נדרשים
part string
הפרמטר part מציין את חלקי המשאב caption שתגובת ה-API תכלול. מגדירים את ערך הפרמטר כ-snippet.

הרשימה הבאה מכילה את השמות של part שאפשר לכלול בערך הפרמטר:
  • id
  • snippet
פרמטרים אופציונליים
onBehalfOfContentOwner string
אפשר להשתמש בפרמטר הזה רק בבקשה מורשית.

הערה: הפרמטר הזה מיועד אך ורק לשותפי תוכן של YouTube.

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

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

גוף הבקשה

מספקים משאב caption בגוף הבקשה. במשאב הזה:

חובה לציין ערך למאפיינים הבאים:

  • snippet.videoId
  • snippet.language
  • snippet.name

אפשר להגדיר ערכים למאפיינים הבאים:

  • snippet.videoId
  • snippet.language
  • snippet.name
  • snippet.isDraft

תשובה

אם הפעולה בוצעה ללא שגיאות, ה-method מחזיר משאב caption בגוף התגובה.

שגיאות

בטבלה הבאה מפורטות הודעות השגיאה שיכולות להופיע בתגובה לקריאה לשיטה הזו. פרטים נוספים זמינים במאמר YouTube Data API – שגיאות.

סוג השגיאה פרטי השגיאה תיאור
badRequest (400) contentRequired הבקשה לא מכילה את התוכן של טראק הכתוביות.
conflict (409) captionExists כבר יש לסרטון שצוין רצועת כתוביות עם snippet.language ו-snippet.name שצוינו. לסרטון יכולות להיות כמה רצועות באותה שפה, אבל לכל רצועה צריך להיות שם שונה.

יש כמה דרכים לתקן את השגיאה. אפשר למחוק את הטראק הקיים ולהוסיף טראק חדש, או לשנות את השם של הטראק החדש לפני שמוסיפים אותו.
forbidden (403) forbidden ההרשאות שמשויכות לבקשה לא מספיקות כדי להעלות את הטראק של הכתוביות. יכול להיות שהבקשה לא אושרה כראוי.
invalidValue (400) invalidMetadata הבקשה מכילה ערכים לא חוקיים של מטא-נתונים, שמונעים את יצירת הטראק. מוודאים שהבקשה מציינת ערכים תקינים למאפיינים snippet.language,‏ snippet.name ו-snippet.videoId. אפשר לכלול גם את המאפיין snippet.isDraft, אבל הוא לא נדרש.
notFound (404) videoNotFound לא נמצא הסרטון שזוהה באמצעות הפרמטר videoId.
invalidValue (400) nameTooLong השדה snippet.name שצוין בבקשה ארוך מדי. האורך המקסימלי הנתמך הוא 150 תווים.

נסה בעצמך!

משתמשים ב-APIs Explorer כדי לקרוא ל-API הזה ולראות את הבקשה ואת התשובה של ה-API.