Videos: insert

Wszystkie filmy przesłane za pomocą punktu końcowego videos.insert pochodzące z niezweryfikowanych projektów API utworzonych po 28 lipca 2020 r. będą dostępne tylko w trybie oglądania prywatnego. Aby to ograniczenie zostało zdjęte, każdy projekt API musi przejść kontrolę w celu potwierdzenia zgodności z Warunkami korzystania z usługi. Więcej informacji znajdziesz w historii wersji interfejsów API.

Przesyła film do YouTube i opcjonalnie ustawia jego metadane.

Ta metoda obsługuje przesyłanie multimediów. Przesłane pliki muszą być zgodne z tymi ograniczeniami:

  • Maksymalny rozmiar pliku: 256 GB
  • Akceptowane typy MIME multimediów: video/*, application/octet-stream

Wpływ na limit: wywołanie tej metody ma koszt limitu wynoszący 1600 jednostek.

Typowe zastosowania

Żądanie

Żądanie HTTP

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

Autoryzacja

To żądanie wymaga autoryzacji przy użyciu co najmniej 1 z tych zakresów (więcej informacji o uwierzytelnianiu i autoryzacji).

Zakres
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

Parametry

W tabeli poniżej znajdziesz listę parametrów obsługiwanych przez to zapytanie. Wszystkie wymienione parametry są parametrami zapytania.

Parametry
Parametry wymagane
part string
Parametr part służy w tej operacji do 2 celów. Określa właściwości, które zostaną ustawione podczas operacji zapisu, a także właściwości, które będą uwzględnione w odpowiedzi interfejsu API.

Uwaga: nie wszystkie części zawierają właściwości, które można ustawić podczas wstawiania lub aktualizowania filmu. Na przykład obiekt statistics zawiera statystyki obliczane przez YouTube dla filmu i nie zawiera wartości, które możesz ustawić lub zmodyfikować. Jeśli wartość parametru określa part, który nie zawiera wartości, które można zmienić, ten part będzie nadal uwzględniany w odpowiedzi interfejsu API.

Następująca lista zawiera nazwy part, które możesz uwzględnić w wartości parametru:
  • contentDetails
  • fileDetails
  • id
  • liveStreamingDetails
  • localizations
  • paidProductPlacementDetails
  • player
  • processingDetails
  • recordingDetails
  • snippet
  • statistics
  • status
  • suggestions
  • topicDetails
Parametry opcjonalne
notifySubscribers boolean
Parametr notifySubscribers wskazuje, czy YouTube ma wysłać powiadomienie o nowym filmie do użytkowników, którzy subskrybują kanał. Wartość parametru True wskazuje, że subskrybenci będą otrzymywać powiadomienia o nowo przesłanych filmach. Właściciel kanału, który przesyła wiele filmów, może jednak ustawić wartość False, aby uniknąć wysyłania powiadomień o każdym nowym filmie do subskrybentów kanału. Wartością domyślną jest True.
onBehalfOfContentOwner string
Tego parametru można używać tylko w prawidłowo autoryzowanym żądaniu. Uwaga: ten parametr jest przeznaczony wyłącznie dla partnerów treści YouTube.

Parametr onBehalfOfContentOwner wskazuje, że dane uwierzytelniające do autoryzacji żądania identyfikują użytkownika systemu CMS YouTube, który działa w imieniu właściciela treści określonego w wartości parametru. Ten parametr jest przeznaczony dla partnerów treści w YouTube, którzy są właścicielami wielu kanałów YouTube i nimi zarządzają. Umożliwia ona właścicielom treści jednorazową weryfikację i uzyskanie dostępu do wszystkich danych o filmach i kanałach bez konieczności podawania danych uwierzytelniających dla każdego kanału. Konto CMS, za pomocą którego użytkownik się uwierzytelnia, musi być powiązane z określonym właścicielem treści w YouTube.
onBehalfOfContentOwnerChannel string
Tego parametru można używać tylko w prawidłowo autoryzowanym żądaniu. Tego parametru można używać tylko w prawidłowo autoryzowanym żądaniu. Uwaga: ten parametr jest przeznaczony wyłącznie dla partnerów treści w YouTube.

Parametr onBehalfOfContentOwnerChannel określa identyfikator kanału YouTube, do którego dodawany jest film. Ten parametr jest wymagany, gdy żądanie określa wartość parametru onBehalfOfContentOwner, i może być używany tylko w połączeniu z tym parametrem. Dodatkowo żądanie musi być autoryzowane za pomocą konta CMS połączonego z właścicielem treści określonym w parametrze onBehalfOfContentOwner. Na koniec kanał określony przez wartość parametru onBehalfOfContentOwnerChannel musi być powiązany z właścicielem treści określonym przez parametr onBehalfOfContentOwner.

Ten parametr jest przeznaczony dla partnerów treści w YouTube, którzy są właścicielami wielu kanałów YouTube i nimi zarządzają. Umożliwia właścicielom treści jednorazowe uwierzytelnianie się i wykonywanie działań w imieniu kanału określonego w wartości parametru bez konieczności podawania danych uwierzytelniających dla każdego osobnego kanału.

Treść żądania

W treści żądania podaj zasób wideo. W przypadku tego zasobu:

  • Możesz ustawić wartości tych właściwości:

    • 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

Odpowiedź

Jeśli operacja się powiedzie, metoda zwróci w treści odpowiedzi zasob filmowy.

Przykłady

Uwaga: poniższe przykłady kodu mogą nie odzwierciedlać wszystkich obsługiwanych języków programowania. Listę obsługiwanych języków znajdziesz w dokumentacji bibliotek klienta.

Przeczytaj

Ten przykładowy kod wywołuje metodę videos.insert interfejsu API, aby przesłać film na kanał powiązany z żądaniem.

W tym przykładzie używana jest biblioteka klienta 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)
}

.NET

Poniższy przykładowy kod wywołuje metodę videos.insert interfejsu API, która umożliwia przesłanie filmu do kanału powiązanego z żądaniem.

W tym przykładzie użyto biblioteki klienta.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

Ten przykład wywołuje metodę videos.insert interfejsu API, aby przesłać film na kanał powiązany z żądaniem.

W tym przykładzie użyto biblioteki klienta 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

Błędy

W tabeli poniżej znajdziesz komunikaty o błędach, które interfejs API może zwrócić w odpowiedzi na wywołanie tej metody. Więcej informacji znajdziesz w dokumentacji dotyczącej komunikatów o błędach.

Typ błędu Szczegóły błędu Opis
badRequest (400) defaultLanguageNotSet Prośba próbuje dodać zlokalizowane szczegóły filmu bez określenia domyślnego języka tych szczegółów.
badRequest (400) invalidCategoryId Właściwość snippet.categoryId określa nieprawidłowy identyfikator kategorii. Aby pobrać obsługiwane kategorie, użyj metody videoCategories.list.
badRequest (400) invalidDescription Metadane żądania zawierają nieprawidłowy opis filmu.
badRequest (400) invalidFilename Nazwa pliku wideo określona w nagłówku Slug jest nieprawidłowa.
badRequest (400) invalidPublishAt Metadane żądania podają nieprawidłowy zaplanowany czas publikacji.
badRequest (400) invalidRecordingDetails Obiekt recordingDetails w metadanych żądania zawiera nieprawidłowe szczegóły nagrywania.
badRequest (400) invalidTags Metadane żądania zawierają nieprawidłowe słowa kluczowe filmu.
badRequest (400) invalidTitle Metadane żądania zawierają nieprawidłowy lub pusty tytuł filmu.
badRequest (400) invalidVideoGameRating Metadane żądania podają nieprawidłową ocenę gry wideo.
badRequest (400) invalidVideoMetadata Metadane żądania są nieprawidłowe.
badRequest (400) mediaBodyRequired Prośba nie zawiera treści wideo.
badRequest (400) uploadLimitExceeded Użytkownik przekroczył limit liczby filmów, które może przesłać.
forbidden (403) forbidden
forbidden (403) forbiddenLicenseSetting W ramach żądania zostanie podjęta próba ustawienia nieprawidłowej licencji na film.
forbidden (403) forbiddenPrivacySetting Żądanie próbuje ustawić nieprawidłowe ustawienie prywatności filmu.

Wypróbuj

Użyj interfejsu APIs Explorer, aby wywołać ten interfejs API i wyświetlić żądanie i odpowiedź interfejsu API.