דף זה תורגם על ידי 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` מציין שפרטי הכניסה להרשאה של הבקשה מזהים משתמש CMS ב-YouTube שפועל בשם בעלי התוכן שצוין בערך הפרמטר. הפרמטר הזה מיועד לשותפי תוכן של YouTube שבבעלותם ובניהולם של ערוצי YouTube רבים. היא מאפשרת לבעלי התוכן לבצע אימות פעם אחת ולקבל גישה לכל נתוני הסרטונים והערוצים שלהם, ללא צורך לספק פרטי כניסה לאימות עבור כל ערוץ בנפרד. חשבון במערכת ניהול התוכן שהמשתמש מאמת באמצעותו חייב להיות מקושר לבעלי התוכן שצוינו ב-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 כדי להעלות סרטון לערוץ שמשויך לבקשה.

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

#!/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 ואת התשובה.