Videos: insert

Tutti i video caricati tramite l'endpoint videos.insert da progetti API non verificati creati dopo il 28 luglio 2020 saranno limitati alla modalità di visualizzazione privata. Per rimuovere questa limitazione, ogni progetto API deve essere sottoposto a un controllo per verificare la conformità ai Termini di servizio. Per maggiori dettagli, consulta la Cronologia delle revisioni dell'API.

Carica un video su YouTube e, facoltativamente, ne imposta i metadati.

Questo metodo supporta il caricamento di contenuti multimediali. I file caricati devono rispettare questi vincoli:

• Dimensioni massime del file:256 GB
• Tipi MIME multimediali accettati: video/*, application/octet-stream

Impatto sulla quota: una chiamata a questo metodo ha un costo per la quota di 1600 unità.

Casi d'uso comuni

Richiesta

Richiesta HTTP

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

Autorizzazione

Questa richiesta richiede l'autorizzazione con almeno uno dei seguenti ambiti (scopri di più su autenticazione e autorizzazione).

Ambito
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

Parametri

La tabella seguente elenca i parametri supportati da questa query. Tutti i parametri elencati sono parametri di query.

Parametri
Parametri obbligatori
part	string Il parametro part ha due scopi in questa operazione. Identifica le proprietà che verranno impostate dall'operazione di scrittura, nonché quelle che saranno incluse nella risposta dell'API. Tieni presente che non tutte le parti contengono proprietà che possono essere impostate durante l'inserimento o l'aggiornamento di un video. Ad esempio, l'oggetto statistics include le statistiche calcolate da YouTube per un video e non contiene valori che puoi impostare o modificare. Se il valore del parametro specifica un part che non contiene valori mutabili, questo part verrà comunque incluso nella risposta dell'API. Il seguente elenco contiene i nomi part che puoi includere nel valore del parametro: contentDetails fileDetails id liveStreamingDetails localizations paidProductPlacementDetails player processingDetails recordingDetails snippet statistics status suggestions topicDetails
Parametri facoltativi
notifySubscribers	boolean Il parametro notifySubscribers indica se YouTube deve inviare una notifica relativa al nuovo video agli utenti iscritti al canale del video. Un valore del parametro pari a True indica che gli iscritti riceveranno una notifica per i video appena caricati. Tuttavia, un proprietario di un canale che carica molti video potrebbe preferire impostare il valore su False per evitare di inviare una notifica per ogni nuovo video agli iscritti del canale. Il valore predefinito è True.
onBehalfOfContentOwner	string Questo parametro può essere utilizzato solo in una richiesta autorizzata. Nota:questo parametro è destinato esclusivamente ai partner di contenuti di YouTube. Il parametro onBehalfOfContentOwner indica che le credenziali di autorizzazione della richiesta identificano un utente di YouTube CMS che agisce per conto del proprietario dei contenuti specificato nel valore del parametro. Questo parametro è destinato ai partner di contenuti di YouTube che possiedono e gestiscono molti canali YouTube diversi. Consente ai proprietari dei contenuti di eseguire l'autenticazione una sola volta e di accedere a tutti i dati dei loro video e del loro canale, senza dover fornire le credenziali di autenticazione per ogni singolo canale. L'account CMS con cui l'utente esegue l'autenticazione deve essere collegato al proprietario dei contenuti di YouTube specificato.
onBehalfOfContentOwnerChannel	string Questo parametro può essere utilizzato solo in una richiesta autorizzata opportunamente. Questo parametro può essere utilizzato solo in una richiesta autorizzata in modo appropriato. Nota: questo parametro è destinato esclusivamente ai partner di contenuti di YouTube. Il parametro onBehalfOfContentOwnerChannel specifica l'ID canale YouTube del canale a cui viene aggiunto un video. Questo parametro è obbligatorio quando una richiesta specifica un valore per il parametro onBehalfOfContentOwner e può essere utilizzato solo in combinazione con questo parametro. Inoltre, la richiesta deve essere autorizzata utilizzando un account CMS collegato al proprietario dei contenuti specificato dal parametro onBehalfOfContentOwner. Infine, il canale specificato dal valore del parametro onBehalfOfContentOwnerChannel deve essere collegato al proprietario dei contenuti specificato dal parametro onBehalfOfContentOwner. Questo parametro è destinato ai partner di contenuti di YouTube che possiedono e gestiscono molti canali YouTube diversi. Consente ai proprietari di contenuti di autenticarsi una volta ed eseguire azioni per conto del canale specificato nel valore del parametro, senza dover fornire le credenziali di autenticazione per ogni canale separato.

Corpo della richiesta

Fornisci una risorsa video nel corpo della richiesta. Per questa risorsa:

• Puoi impostare i valori per le seguenti proprietà:

  • 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

Risposta

In caso di esito positivo, questo metodo restituisce una risorsa video nel corpo della risposta.

Esempi

Nota:i seguenti esempi di codice potrebbero non rappresentare tutti i linguaggi di programmazione supportati. Per un elenco delle lingue supportate, consulta la documentazione delle librerie client.

Vai

Questo esempio di codice chiama il metodo videos.insert dell'API per caricare un video sul canale associato alla richiesta.

Questo esempio utilizza la libreria client 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

Il seguente esempio di codice chiama il metodo videos.insert dell'API per caricare un video sul canale associato alla richiesta.

Questo esempio utilizza la libreria client.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

Questo esempio chiama il metodo videos.insert dell'API per caricare un video sul canale associato alla richiesta.

In questo esempio viene utilizzata la libreria client 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

Errori

La seguente tabella identifica i messaggi di errore che l'API potrebbe restituire in risposta a una chiamata a questo metodo. Per ulteriori dettagli, consulta la documentazione relativa al messaggio di errore.

Tipo di errore	Dettaglio errore	Descrizione
badRequest (400)	defaultLanguageNotSet	La richiesta tenta di aggiungere dettagli del video localizzati senza specificare la lingua predefinita dei dettagli del video.
badRequest (400)	invalidCategoryId	La proprietà snippet.categoryId specifica un ID categoria non valido. Utilizza il metodo videoCategories.list per recuperare le categorie supportate.
badRequest (400)	invalidDescription	I metadati della richiesta specificano una descrizione del video non valida.
badRequest (400)	invalidFilename	Il nome del file del video specificato nell'intestazione Slug non è valido.
badRequest (400)	invalidPublishAt	I metadati della richiesta specificano un'ora di pubblicazione pianificata non valida.
badRequest (400)	invalidRecordingDetails	L'oggetto recordingDetails nei metadati della richiesta specifica dettagli di registrazione non validi.
badRequest (400)	invalidTags	I metadati della richiesta specificano parole chiave video non valide.
badRequest (400)	invalidTitle	I metadati della richiesta specificano un titolo del video non valido o vuoto.
badRequest (400)	invalidVideoGameRating	I metadati della richiesta specificano una classificazione del videogioco non valida.
badRequest (400)	invalidVideoMetadata	I metadati della richiesta non sono validi.
badRequest (400)	mediaBodyRequired	La richiesta non include i contenuti video.
badRequest (400)	uploadLimitExceeded	L'utente ha superato il numero di video che può caricare.
forbidden (403)	forbidden
forbidden (403)	forbiddenLicenseSetting	La richiesta tenta di impostare una licenza non valida per il video.
forbidden (403)	forbiddenPrivacySetting	La richiesta tenta di impostare un'impostazione della privacy non valida per il video.

Prova

Usa APIs Explorer per chiamare questa API e visualizzare la richiesta e la risposta dell'API.