Videos: insert

همه ویدیوهای آپلود شده از طریق videos.insert endpoint از پروژه‌های API تأیید نشده ایجاد شده پس از ۲۸ ژوئیه ۲۰۲۰ به حالت مشاهده خصوصی محدود می‌شوند. برای برداشتن این محدودیت، هر پروژه API باید تحت بازرسی قرار گیرد تا مطابقت با شرایط خدمات را تأیید کند. لطفاً برای جزئیات بیشتر به تاریخچه ویرایش API مراجعه کنید.

یک ویدیو را در YouTube آپلود می کند و به صورت اختیاری ابرداده ویدیو را تنظیم می کند.

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

• حداکثر حجم فایل: 256 گیگابایت
• انواع MIME رسانه پذیرفته شده: video/* ، application/octet-stream

تاثیر سهمیه ای: فراخوانی به این روش هزینه سهمیه ای 1600 واحدی دارد.

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

درخواست کنید

درخواست 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 paidProductPlacementDetails 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
  • status.containsSyntheticMedia
  • recordingDetails.recordingDate

پاسخ

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

نمونه ها

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

برو

این نمونه کد روش 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

دات نت

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

این مثال از کتابخانه سرویس گیرنده دات نت استفاده می کند.

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

روبی

این نمونه روش 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 استفاده کنید.