Videos: insert

ویدیویی را در YouTube بارگذاری می‌کند و به‌طور اختیاری فراداده ویدیو را تنظیم می‌کند.

این روش از بارگذاری رسانه پشتیبانی می‌کند. فایل‌های بارگذاری‌شده باید با این محدودیت‌ها مطابقت داشته باشند:

  • حداکثر اندازه فایل: ۲۵۶ گیگابایت
  • انواع MIME رسانه پذیرفته‌شده: video/*، application/octet-stream

تأثیر سهمیه: ۱۰۰ تماس در روز. فراخوانی این روش دارای هزینه سهمیه ۱ واحد در دسته سهمیه «بارگذاری‌های ویدیو» است.

موارد استفاده رایج

درخواست

درخواست 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 همچنان در پاسخ میانای برنامه‌سازی کاربردی گنجانده خواهد شد.

فهرست زیر حاوی نام‌های part است که می‌توانید در مقدار پارامتر بگنجانید:
  • brandPartner
  • contentDetails
  • fileDetails
  • id
  • liveStreamingDetails
  • localizations
  • paidProductPlacementDetails
  • player
  • processingDetails
  • recordingDetails
  • snippet
  • statistics
  • status
  • suggestions
  • topicDetails
پارامترهای اختیاری
notifySubscribers boolean
پارامتر notifySubscribers نشان می‌دهد که آیا YouTube باید اعلانی درباره ویدیو جدید به کاربرانی که در کانال ویدیو مشترک شده‌اند ارسال کند یا نه. مقدار پارامتر True نشان می‌دهد که مشترکین از ویدیوهای تازه بارگذاری‌شده مطلع خواهند شد. بااین‌حال، مالک کانالی که ویدیوهای زیادی بارگذاری می‌کند ممکن است ترجیح دهد مقدار را روی False تنظیم کند تا برای هر ویدیو جدید به مشترکان کانال اعلان ارسال نشود. مقدار پیش‌فرض True است.
onBehalfOfContentOwner string
این پارامتر فقط در درخواست‌های مجاز قابل‌استفاده است. توجه: این پارامتر منحصراً برای شرکای محتوای YouTube درنظر گرفته شده است.

پارامتر onBehalfOfContentOwner نشان می‌دهد که اطلاعات کاربری مجوز درخواست، کاربر CMS YouTube را شناسایی می‌کند که از طرف مالک محتوای مشخص‌شده در مقدار پارامتر عمل می‌کند. این پارامتر برای شرکای محتوای 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: اگر مقداری برای این دارایی مشخص نکنید، وضعیت حریم خصوصی ویدیو بارگذاری‌شده به‌طور پیش‌فرض روی public تنظیم می‌شود. برخی‌از بارگذاری‌ها ممکن است براساس تنظیمات حساب محتواساز، به‌طور پیش‌فرض روی private تنظیم شوند، همان‌طور که در مرکز راهنمایی YouTube توضیح داده شده است. ویدیوهای بارگذاری‌شده از پروژه‌های API تأییدنشده به حالت مشاهده خصوصی محدود نمی‌شوند.
    • status.publicStatsViewable
    • status.publishAt
    • status.selfDeclaredMadeForKids
    • status.containsSyntheticMedia
    • recordingDetails.recordingDate

پاسخ

درصورت موفقیت، این روش منبع ویدیو را در بدنه پاسخ برمی‌گرداند.

مثال‌ها

توجه: نمونه‌های کد زیر ممکن است نشان‌دهنده همه زبان‌های برنامه‌نویسی پشتیبانی‌شده نباشد. برای اطلاع از فهرست زبان‌های پشتیبانی‌شده، به مستندات کتابخانه‌های مشتری مراجعه کنید.

رفتن

این نمونه کد روش videos.insert API را برای بارگذاری ویدیو در کانال مرتبط با درخواست فراخوانی می‌کند.

این مثال از کتابخانه Go client استفاده می‌کند.

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)
}

دات نت

نمونه کد زیر روش videos.insert میانای برنامه‌سازی کاربردی را برای بارگذاری ویدیو در کانال مرتبط با درخواست فراخوانی می‌کند.

این مثال از کتابخانه کارخواه 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);
    }
  }
}

Ruby

این نمونه روش videos.insert میانای برنامه‌سازی کاربردی را برای بارگذاری ویدیو در کانال مرتبط با درخواست فراخوانی می‌کند.

این مثال از کتابخانه کارخواه 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

خطاها

جدول زیر پیام‌های خطایی را که ممکن است 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 استفاده کنید.