דף זה תורגם על ידי Cloud Translation API.

Videos: insert

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

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

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

גודל הקובץ המקסימלי: 256GB
סוגי MIME קבילים של מדיה: video/*, application/octet-stream

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

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

בקשה

בקשת HTTP

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

אישור

בקשה זו מחייבת הרשאה עם לפחות אחד מההיקפים הבאים (מידע נוסף על אימות והרשאה).

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

פרמטרים

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

פרמטרים
הפרמטרים הנדרשים
`part`	`string` הפרמטר `part` משרת שתי מטרות בפעולה זו. היא מזהה את המאפיינים שפעולת הכתיבה תגדיר, וגם את המאפיינים שייכללו בתגובת ה-API. לתשומת ליבך, לא כל החלקים מכילים מאפיינים שאפשר להגדיר כשמוסיפים סרטון או מעדכנים אותו. לדוגמה, האובייקט `statistics` כולל נתונים סטטיסטיים שהמערכת של YouTube מחשבת עבור סרטון, והוא לא מכיל ערכים שאתם יכולים להגדיר או לשנות. אם ערך הפרמטר מציין `part` שלא מכיל ערכים שניתנים לשינוי, `part` עדיין ייכלל בתגובת ה-API. הרשימה הבאה מכילה את שמות `part` שאפשר לכלול בערך הפרמטר: `contentDetails` `fileDetails` `id` `liveStreamingDetails` `localizations` `player` `processingDetails` `recordingDetails` `snippet` `statistics` `status` `suggestions` `topicDetails`
פרמטרים אופציונליים
`notifySubscribers`	`boolean` הפרמטר `notifySubscribers` מציין אם צריך לשלוח מ-YouTube התראה לגבי הסרטון החדש למשתמשים שנרשמו כמנויים לערוץ של הסרטון. ערך פרמטר של `True` מציין שהמנויים יקבלו התראה על סרטונים חדשים שיועלו. עם זאת, ייתכן שבעלים של ערוץ שמעלה סרטונים רבים יעדיף להגדיר את הערך ל-`False` כדי להימנע משליחת התראה על כל סרטון חדש למנויים של הערוץ. ערך ברירת המחדל הוא `True`.
`onBehalfOfContentOwner`	`string` ניתן להשתמש בפרמטר הזה רק במסגרת בקשה מורשית תקינה. הערה: הפרמטר הזה מיועד אך ורק לשותפי תוכן של YouTube. הפרמטר `onBehalfOfContentOwner` מציין שפרטי הכניסה של ההרשאה של הבקשה מזהים משתמש YouTube CMS שפועל בשם בעלי התוכן שצוין בערך הפרמטר. הפרמטר הזה מיועד לשותפי תוכן של YouTube שהם הבעלים והמנהלים של ערוצי YouTube רבים ושונים. היא מאפשרת לבעלי תוכן לבצע אימות פעם אחת ולקבל גישה לכל נתוני הסרטונים והערוץ, בלי שיצטרכו לספק פרטי כניסה לאימות עבור כל ערוץ בנפרד. חשבון ה-CMS שאיתו המשתמש מבצע אימות חייב להיות מקושר לבעלי התוכן שצוינו ב-YouTube.
`onBehalfOfContentOwnerChannel`	`string` ניתן להשתמש בפרמטר הזה רק במסגרת בקשה מורשית תקינה. ניתן להשתמש בפרמטר הזה רק במסגרת בקשה מורשית כראוי. הערה: הפרמטר הזה מיועד אך ורק לשותפי תוכן של YouTube. הפרמטר `onBehalfOfContentOwnerChannel` מציין את מזהה ערוץ YouTube של הערוץ שאליו מוסיפים את הסרטון. הפרמטר הזה נדרש כאשר בקשה מציינת ערך לפרמטר `onBehalfOfContentOwner`, ואפשר להשתמש בו רק בשילוב עם הפרמטר הזה. בנוסף, יש לאשר את הבקשה באמצעות חשבון CMS שמקושר לבעלי התוכן בפרמטר `onBehalfOfContentOwner`. לבסוף, הערוץ שצוין בערך הפרמטר `onBehalfOfContentOwnerChannel` חייב להיות מקושר לבעלי התוכן שהפרמטר `onBehalfOfContentOwner` מציין. הפרמטר הזה מיועד לשותפי תוכן של YouTube, שבבעלותם ומנהלים רבים ערוצי YouTube שונים. היא מאפשרת לבעלי תוכן לבצע אימות פעם אחת ולבצע פעולות בשם הערוץ שצוין בערך הפרמטר, בלי שיצטרכו לספק פרטי כניסה לאימות עבור כל ערוץ נפרד.

גוף הבקשה

יש לספק משאב וידאו בגוף הבקשה. במשאב הזה:

ניתן להגדיר ערכים למאפיינים הבאים:
- snippet.title
- snippet.description
- snippet.tags[]
- snippet.categoryId
- snippet.defaultLanguage
- localizations.(key)
- localizations.(key).title
- localizations.(key).description
- status.embeddable
- status.license
- status.privacyStatus
- status.publicStatsViewable
- status.publishAt
- status.selfDeclaredMadeForKids
- recordingDetails.locationDescription (הוצא משימוש)
- recordingDetails.location.latitude (הוצא משימוש)
- recordingDetails.location.longitude (הוצא משימוש)
- recordingDetails.recordingDate

תשובה

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

דוגמאות

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

Go

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

בדוגמה הזו נשתמש בספריית הלקוח של Go.

package main

import (
	"flag"
	"fmt"
	"log"
	"os"
	"strings"

	"google.golang.org/api/youtube/v3"
)

var (
	filename    = flag.String("filename", "", "Name of video file to upload")
	title       = flag.String("title", "Test Title", "Video title")
	description = flag.String("description", "Test Description", "Video description")
	category    = flag.String("category", "22", "Video category")
	keywords    = flag.String("keywords", "", "Comma separated list of video keywords")
	privacy     = flag.String("privacy", "unlisted", "Video privacy status")
)

func main() {
	flag.Parse()

	if *filename == "" {
		log.Fatalf("You must provide a filename of a video file to upload")
	}

	client := getClient(youtube.YoutubeUploadScope)

	service, err := youtube.New(client)
	if err != nil {
		log.Fatalf("Error creating YouTube client: %v", err)
	}

	upload := &youtube.Video{
		Snippet: &youtube.VideoSnippet{
			Title:       *title,
			Description: *description,
			CategoryId:  *category,
		},
		Status: &youtube.VideoStatus{PrivacyStatus: *privacy},
	}

	// The API returns a 400 Bad Request response if tags is an empty string.
	if strings.Trim(*keywords, "") != "" {
		upload.Snippet.Tags = strings.Split(*keywords, ",")
	}

	call := service.Videos.Insert("snippet,status", upload)

	file, err := os.Open(*filename)
	defer file.Close()
	if err != nil {
		log.Fatalf("Error opening %v: %v", *filename, err)
	}

	response, err := call.Media(file).Do()
	handleError(err, "")
	fmt.Printf("Upload successful! Video ID: %v\n", response.Id)
}
upload_video.go

‎.NET

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

בדוגמה הזו נשתמש בספריית הלקוח.NET.

using System;
using System.IO;
using System.Reflection;
using System.Threading;
using System.Threading.Tasks;

using Google.Apis.Auth.OAuth2;
using Google.Apis.Services;
using Google.Apis.Upload;
using Google.Apis.Util.Store;
using Google.Apis.YouTube.v3;
using Google.Apis.YouTube.v3.Data;

namespace Google.Apis.YouTube.Samples
{
  /// <summary>
  /// YouTube Data API v3 sample: upload a video.
  /// Relies on the Google APIs Client Library for .NET, v1.7.0 or higher.
  /// See https://developers.google.com/api-client-library/dotnet/get_started
  /// </summary>
  internal class UploadVideo
  {
    [STAThread]
    static void Main(string[] args)
    {
      Console.WriteLine("YouTube Data API: Upload Video");
      Console.WriteLine("==============================");

      try
      {
        new UploadVideo().Run().Wait();
      }
      catch (AggregateException ex)
      {
        foreach (var e in ex.InnerExceptions)
        {
          Console.WriteLine("Error: " + e.Message);
        }
      }

      Console.WriteLine("Press any key to continue...");
      Console.ReadKey();
    }

    private async Task Run()
    {
      UserCredential credential;
      using (var stream = new FileStream("client_secrets.json", FileMode.Open, FileAccess.Read))
      {
        credential = await GoogleWebAuthorizationBroker.AuthorizeAsync(
            GoogleClientSecrets.Load(stream).Secrets,
            // This OAuth 2.0 access scope allows an application to upload files to the
            // authenticated user's YouTube channel, but doesn't allow other types of access.
            new[] { YouTubeService.Scope.YoutubeUpload },
            "user",
            CancellationToken.None
        );
      }

      var youtubeService = new YouTubeService(new BaseClientService.Initializer()
      {
        HttpClientInitializer = credential,
        ApplicationName = Assembly.GetExecutingAssembly().GetName().Name
      });

      var video = new Video();
      video.Snippet = new VideoSnippet();
      video.Snippet.Title = "Default Video Title";
      video.Snippet.Description = "Default Video Description";
      video.Snippet.Tags = new string[] { "tag1", "tag2" };
      video.Snippet.CategoryId = "22"; // See https://developers.google.com/youtube/v3/docs/videoCategories/list
      video.Status = new VideoStatus();
      video.Status.PrivacyStatus = "unlisted"; // or "private" or "public"
      var filePath = @"REPLACE_ME.mp4"; // Replace with path to actual movie file.

      using (var fileStream = new FileStream(filePath, FileMode.Open))
      {
        var videosInsertRequest = youtubeService.Videos.Insert(video, "snippet,status", fileStream, "video/*");
        videosInsertRequest.ProgressChanged += videosInsertRequest_ProgressChanged;
        videosInsertRequest.ResponseReceived += videosInsertRequest_ResponseReceived;

        await videosInsertRequest.UploadAsync();
      }
    }

    void videosInsertRequest_ProgressChanged(Google.Apis.Upload.IUploadProgress progress)
    {
      switch (progress.Status)
      {
        case UploadStatus.Uploading:
          Console.WriteLine("{0} bytes sent.", progress.BytesSent);
          break;

        case UploadStatus.Failed:
          Console.WriteLine("An error prevented the upload from completing.\n{0}", progress.Exception);
          break;
      }
    }

    void videosInsertRequest_ResponseReceived(Video video)
    {
      Console.WriteLine("Video id '{0}' was successfully uploaded.", video.Id);
    }
  }
}
UploadVideo.cs

Ruby

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

בדוגמה הזו נשתמש בספריית הלקוח של Ruby.

#!/usr/bin/ruby

require 'rubygems'
gem 'google-api-client', '>0.7'
require 'google/api_client'
require 'google/api_client/client_secrets'
require 'google/api_client/auth/file_storage'
require 'google/api_client/auth/installed_app'
require 'trollop'

# A limited OAuth 2 access scope that allows for uploading files, but not other
# types of account access.
YOUTUBE_UPLOAD_SCOPE = 'https://www.googleapis.com/auth/youtube.upload'
YOUTUBE_API_SERVICE_NAME = 'youtube'
YOUTUBE_API_VERSION = 'v3'

def get_authenticated_service
  client = Google::APIClient.new(
    :application_name => $PROGRAM_NAME,
    :application_version => '1.0.0'
  )
  youtube = client.discovered_api(YOUTUBE_API_SERVICE_NAME, YOUTUBE_API_VERSION)

  file_storage = Google::APIClient::FileStorage.new("#{$PROGRAM_NAME}-oauth2.json")
  if file_storage.authorization.nil?
    client_secrets = Google::APIClient::ClientSecrets.load
    flow = Google::APIClient::InstalledAppFlow.new(
      :client_id => client_secrets.client_id,
      :client_secret => client_secrets.client_secret,
      :scope => [YOUTUBE_UPLOAD_SCOPE]
    )
    client.authorization = flow.authorize(file_storage)
  else
    client.authorization = file_storage.authorization
  end

  return client, youtube
end

def main
  opts = Trollop::options do
    opt :file, 'Video file to upload', :type => String
    opt :title, 'Video title', :default => 'Test Title', :type => String
    opt :description, 'Video description',
          :default => 'Test Description', :type => String
    opt :category_id, 'Numeric video category. See https://developers.google.com/youtube/v3/docs/videoCategories/list',
          :default => 22, :type => :int
    opt :keywords, 'Video keywords, comma-separated',
          :default => '', :type => String
    opt :privacy_status, 'Video privacy status: public, private, or unlisted',
          :default => 'public', :type => String
  end

  if opts[:file].nil? or not File.file?(opts[:file])
    Trollop::die :file, 'does not exist'
  end

  client, youtube = get_authenticated_service

  begin
    body = {
      :snippet => {
        :title => opts[:title],
        :description => opts[:description],
        :tags => opts[:keywords].split(','),
        :categoryId => opts[:category_id],
      },
      :status => {
        :privacyStatus => opts[:privacy_status]
      }
    }

    videos_insert_response = client.execute!(
      :api_method => youtube.videos.insert,
      :body_object => body,
      :media => Google::APIClient::UploadIO.new(opts[:file], 'video/*'),
      :parameters => {
        :uploadType => 'resumable',
        :part => body.keys.join(',')
      }
    )

    videos_insert_response.resumable_upload.send_all(client)

    puts "Video id '#{videos_insert_response.data.id}' was successfully uploaded."
  rescue Google::APIClient::TransmissionError => e
    puts e.result.body
  end
end

main
upload_video.rb

שגיאות

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

סוג השגיאה	פרטי השגיאה	תיאור
`badRequest (400)`	`defaultLanguageNotSet`	הבקשה מנסה להוסיף פרטי סרטון שמותאמים לשוק המקומי, בלי לציין את שפת ברירת המחדל של פרטי הסרטון.
`badRequest (400)`	`invalidCategoryId`	המאפיין `snippet.categoryId` מציין מזהה קטגוריה לא חוקי. אפשר להשתמש בשיטה `videoCategories.list` כדי לאחזר קטגוריות נתמכות.
`badRequest (400)`	`invalidDescription`	המטא-נתונים של הבקשה מציינים תיאור סרטון לא חוקי.
`badRequest (400)`	`invalidFilename`	שם הקובץ של הסרטון שצוין בכותרת `Slug` לא תקין.
`badRequest (400)`	`invalidPublishAt`	המטא-נתונים של הבקשה מציינים זמן פרסום מתוזמן לא חוקי.
`badRequest (400)`	`invalidRecordingDetails`	האובייקט `recordingDetails` במטא-נתונים של הבקשה מציין פרטי הקלטה לא חוקיים.
`badRequest (400)`	`invalidTags`	המטא-נתונים של הבקשה מציינים מילות מפתח לא חוקיות בסרטון.
`badRequest (400)`	`invalidTitle`	המטא-נתונים של הבקשה מציינים שם סרטון ריק או לא חוקי.
`badRequest (400)`	`invalidVideoGameRating`	המטא-נתונים של הבקשה מציינים סיווג לא חוקי של משחק וידאו.
`badRequest (400)`	`invalidVideoMetadata`	המטא-נתונים של הבקשה לא חוקיים.
`badRequest (400)`	`mediaBodyRequired`	הבקשה לא כוללת את תוכן הסרטון.
`badRequest (400)`	`uploadLimitExceeded`	המשתמש חרג ממספר הסרטונים שהוא יכול להעלות.
`forbidden (403)`	`forbidden`
`forbidden (403)`	`forbiddenLicenseSetting`	הבקשה מנסה להגדיר רישיון לא תקף לסרטון.
`forbidden (403)`	`forbiddenPrivacySetting`	הבקשה מנסה לקבוע הגדרת פרטיות לא חוקית לסרטון.

רוצה לנסות?

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