Carrega uma miniatura de vídeo personalizada para o YouTube e a define para um vídeo. Veja um exemplo.
Este método oferece suporte ao envio de mídia. Os arquivos enviados devem estar de acordo com estas restrições:
- Tamanho máximo do arquivo: 2 MB
- Tipos de MIME de mídia aceitos:
image/jpeg,image/png,application/octet-stream
Solicitação
Solicitação HTTP
POST https://www.googleapis.com/youtube/v3/thumbnails/set
Autorização
Esta solicitação requer autorização com pelo menos um dos seguintes escopos (saiba mais sobre autenticação e autorização).
| Escopo |
|---|
https://www.googleapis.com/auth/youtubepartner |
https://www.googleapis.com/auth/youtube.upload |
https://www.googleapis.com/auth/youtube |
Parâmetros
A tabela a seguir lista os parâmetros que esta consulta suporta. Todos os parâmetros listados são os parâmetros de consulta.
| Parâmetros | ||
|---|---|---|
| Parâmetros obrigatórios | ||
videoId |
stringO parâmetro videoId especifica o ID de um vídeo do YouTube para o qual a miniatura de vídeo personalizada é fornecida. |
|
Corpo de solicitação
Não forneça um corpo de solicitação ao chamar este método.
Resposta
Se for bem sucedido, este método retorna um corpo de resposta com a seguinte estrutura:
{
"kind": "youtube#thumbnailSetResponse",
"etag": etag,
"items": [
thumbnails resource
]
}
Propriedades
A tabela a seguir define as propriedades que aparecem neste recurso:
| Propriedades | |
|---|---|
kind |
stringO tipo do recurso da API. O valor será youtube#thumbnailSetResponse. |
etag |
etagA Etag deste recurso. |
items[] |
listA lista de miniaturas. |
Exemplos
Observação: os exemplos de código a seguir não representam todas as linguagens de programação suportadas. Consulte a documentação bibliotecas clientes para uma lista das linguagens suportadas.
Java
Este exemplo usa a biblioteca cliente Java.
/*
* Copyright (c) 2013 Google Inc.
*
* Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
* in compliance with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software distributed under the License
* is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
* or implied. See the License for the specific language governing permissions and limitations under
* the License.
*/
package com.google.api.services.samples.youtube.cmdline.data;
import com.google.api.client.auth.oauth2.Credential;
import com.google.api.client.googleapis.json.GoogleJsonResponseException;
import com.google.api.client.googleapis.media.MediaHttpUploader;
import com.google.api.client.googleapis.media.MediaHttpUploaderProgressListener;
import com.google.api.client.http.InputStreamContent;
import com.google.api.services.samples.youtube.cmdline.Auth;
import com.google.api.services.youtube.YouTube;
import com.google.api.services.youtube.YouTube.Thumbnails.Set;
import com.google.api.services.youtube.model.ThumbnailSetResponse;
import com.google.common.collect.Lists;
import java.io.*;
import java.util.List;
/**
* This sample uses MediaHttpUploader to upload an image and then calls the
* API's youtube.thumbnails.set method to set the image as the custom thumbnail
* for a video.
*
* @author Ibrahim Ulukaya
*/
public class UploadThumbnail {
/**
* Define a global instance of a Youtube object, which will be used
* to make YouTube Data API requests.
*/
private static YouTube youtube;
/**
* Define a global variable that specifies the MIME type of the image
* being uploaded.
*/
private static final String IMAGE_FILE_FORMAT = "image/png";
/**
* Prompt the user to specify a video ID and the path for a thumbnail
* image. Then call the API to set the image as the thumbnail for the video.
*
* @param args command line args (not used).
*/
public static void main(String[] args) {
// This OAuth 2.0 access scope allows for full read/write access to the
// authenticated user's account.
List<String> scopes = Lists.newArrayList("https://www.googleapis.com/auth/youtube");
try {
// Authorize the request.
Credential credential = Auth.authorize(scopes, "uploadthumbnail");
// This object is used to make YouTube Data API requests.
youtube = new YouTube.Builder(Auth.HTTP_TRANSPORT, Auth.JSON_FACTORY, credential).setApplicationName(
"youtube-cmdline-uploadthumbnail-sample").build();
// Prompt the user to enter the video ID of the video being updated.
String videoId = getVideoIdFromUser();
System.out.println("You chose " + videoId + " to upload a thumbnail.");
// Prompt the user to specify the location of the thumbnail image.
File imageFile = getImageFromUser();
System.out.println("You chose " + imageFile + " to upload.");
// Create an object that contains the thumbnail image file's
// contents.
InputStreamContent mediaContent = new InputStreamContent(
IMAGE_FILE_FORMAT, new BufferedInputStream(new FileInputStream(imageFile)));
mediaContent.setLength(imageFile.length());
// Create an API request that specifies that the mediaContent
// object is the thumbnail of the specified video.
Set thumbnailSet = youtube.thumbnails().set(videoId, mediaContent);
// Set the upload type and add an event listener.
MediaHttpUploader uploader = thumbnailSet.getMediaHttpUploader();
// Indicate whether direct media upload is enabled. A value of
// "True" indicates that direct media upload is enabled and that
// the entire media content will be uploaded in a single request.
// A value of "False," which is the default, indicates that the
// request will use the resumable media upload protocol, which
// supports the ability to resume an upload operation after a
// network interruption or other transmission failure, saving
// time and bandwidth in the event of network failures.
uploader.setDirectUploadEnabled(false);
// Set the upload state for the thumbnail image.
MediaHttpUploaderProgressListener progressListener = new MediaHttpUploaderProgressListener() {
@Override
public void progressChanged(MediaHttpUploader uploader) throws IOException {
switch (uploader.getUploadState()) {
// This value is set before the initiation request is
// sent.
case INITIATION_STARTED:
System.out.println("Initiation Started");
break;
// This value is set after the initiation request
// completes.
case INITIATION_COMPLETE:
System.out.println("Initiation Completed");
break;
// This value is set after a media file chunk is
// uploaded.
case MEDIA_IN_PROGRESS:
System.out.println("Upload in progress");
System.out.println("Upload percentage: " + uploader.getProgress());
break;
// This value is set after the entire media file has
// been successfully uploaded.
case MEDIA_COMPLETE:
System.out.println("Upload Completed!");
break;
// This value indicates that the upload process has
// not started yet.
case NOT_STARTED:
System.out.println("Upload Not Started!");
break;
}
}
};
uploader.setProgressListener(progressListener);
// Upload the image and set it as the specified video's thumbnail.
ThumbnailSetResponse setResponse = thumbnailSet.execute();
// Print the URL for the updated video's thumbnail image.
System.out.println("\n================== Uploaded Thumbnail ==================\n");
System.out.println(" - Url: " + setResponse.getItems().get(0).getDefault().getUrl());
} catch (GoogleJsonResponseException e) {
System.err.println("GoogleJsonResponseException code: " + e.getDetails().getCode() + " : "
+ e.getDetails().getMessage());
e.printStackTrace();
} catch (IOException e) {
System.err.println("IOException: " + e.getMessage());
e.printStackTrace();
}
}
/*
* Prompts the user to enter a YouTube video ID and return the user input.
*/
private static String getVideoIdFromUser() throws IOException {
String inputVideoId = "";
System.out.print("Please enter a video Id to update: ");
BufferedReader bReader = new BufferedReader(new InputStreamReader(System.in));
inputVideoId = bReader.readLine();
if (inputVideoId.length() < 1) {
// Exit if the user does not specify a video ID.
System.out.print("Video Id can't be empty!");
System.exit(1);
}
return inputVideoId;
}
/*
* Prompt the user to enter the path for the thumbnail image being uploaded.
*/
private static File getImageFromUser() throws IOException {
String path = "";
System.out.print("Please enter the path of the image file to upload: ");
BufferedReader bReader = new BufferedReader(new InputStreamReader(System.in));
path = bReader.readLine();
if (path.length() < 1) {
// Exit if the user does not provide a path to the image file.
System.out.print("Path can not be empty!");
System.exit(1);
}
return new File(path);
}
}
PHP
Este exemplo de código demonstra como enviar uma miniatura de vídeo personalizada para o YouTube e defini-la para um vídeo.
O exemplo de código abaixo chama o método youtube.thumbnails.set da API com o parâmetro videoId definido para um ID de vídeo a ser usado como imagem personalizada de miniatura no vídeo. Para o envio da imagem, o programa utiliza a classe Google_MediaFileUpload com o parâmetro resumable upload definido como true para enviar a imagem por partes, assim as próximas tentativas retomam o envio a partir do ponto mais próximo em que a tentativa anterior falhou. Esse recurso é útil para programas que precisam enviar arquivos muito pesados.
Este exemplo usa a biblioteca cliente PHP.
<?php
/**
* This sample uploads and sets a custom thumbnail for a video.
*
* 1. It uploads an image using the "Google_MediaFileUpload" class.
* 2. It sets the uploaded image as a custom thumbnail to the video by
* calling the API's "youtube.thumbnails.set" method
*
* @author Ibrahim Ulukaya
*/
/**
* Library Requirements
*
* 1. Install composer (https://getcomposer.org)
* 2. On the command line, change to this directory (api-samples/php)
* 3. Require the google/apiclient library
* $ composer require google/apiclient:~2.0
*/
if (!file_exists(__DIR__ . '/vendor/autoload.php')) {
throw new \Exception('please run "composer require google/apiclient:~2.0" in "' . __DIR__ .'"');
}
require_once __DIR__ . '/vendor/autoload.php';
session_start();
/*
* You can acquire an OAuth 2.0 client ID and client secret from the
* Google API Console <https://console.cloud.google.com/>
* For more information about using OAuth 2.0 to access Google APIs, please see:
* <https://developers.google.com/youtube/v3/guides/authentication>
* Please ensure that you have enabled the YouTube Data API for your project.
*/
$OAUTH2_CLIENT_ID = 'REPLACE_ME';
$OAUTH2_CLIENT_SECRET = 'REPLACE_ME';
$client = new Google_Client();
$client->setClientId($OAUTH2_CLIENT_ID);
$client->setClientSecret($OAUTH2_CLIENT_SECRET);
$client->setScopes('https://www.googleapis.com/auth/youtube');
$redirect = filter_var('http://' . $_SERVER['HTTP_HOST'] . $_SERVER['PHP_SELF'],
FILTER_SANITIZE_URL);
$client->setRedirectUri($redirect);
// Define an object that will be used to make all API requests.
$youtube = new Google_Service_YouTube($client);
// Check if an auth token exists for the required scopes
$tokenSessionKey = 'token-' . $client->prepareScopes();
if (isset($_GET['code'])) {
if (strval($_SESSION['state']) !== strval($_GET['state'])) {
die('The session state did not match.');
}
$client->authenticate($_GET['code']);
$_SESSION[$tokenSessionKey] = $client->getAccessToken();
header('Location: ' . $redirect);
}
if (isset($_SESSION[$tokenSessionKey])) {
$client->setAccessToken($_SESSION[$tokenSessionKey]);
}
// Check to ensure that the access token was successfully acquired.
if ($client->getAccessToken()) {
$htmlBody = '';
try{
// REPLACE this value with the video ID of the video being updated.
$videoId = "VIDEO_ID";
// REPLACE this value with the path to the image file you are uploading.
$imagePath = "/path/to/file.png";
// Specify the size of each chunk of data, in bytes. Set a higher value for
// reliable connection as fewer chunks lead to faster uploads. Set a lower
// value for better recovery on less reliable connections.
$chunkSizeBytes = 1 * 1024 * 1024;
// Setting the defer flag to true tells the client to return a request which can be called
// with ->execute(); instead of making the API call immediately.
$client->setDefer(true);
// Create a request for the API's thumbnails.set method to upload the image and associate
// it with the appropriate video.
$setRequest = $youtube->thumbnails->set($videoId);
// Create a MediaFileUpload object for resumable uploads.
$media = new Google_Http_MediaFileUpload(
$client,
$setRequest,
'image/png',
null,
true,
$chunkSizeBytes
);
$media->setFileSize(filesize($imagePath));
// Read the media file and upload it chunk by chunk.
$status = false;
$handle = fopen($imagePath, "rb");
while (!$status && !feof($handle)) {
$chunk = fread($handle, $chunkSizeBytes);
$status = $media->nextChunk($chunk);
}
fclose($handle);
// If you want to make other calls after the file upload, set setDefer back to false
$client->setDefer(false);
$thumbnailUrl = $status['items'][0]['default']['url'];
$htmlBody .= "<h3>Thumbnail Uploaded</h3><ul>";
$htmlBody .= sprintf('<li>%s (%s)</li>',
$videoId,
$thumbnailUrl);
$htmlBody .= sprintf('<img src="%s">', $thumbnailUrl);
$htmlBody .= '</ul>';
} catch (Google_Service_Exception $e) {
$htmlBody .= sprintf('<p>A service error occurred: <code>%s</code></p>',
htmlspecialchars($e->getMessage()));
} catch (Google_Exception $e) {
$htmlBody .= sprintf('<p>An client error occurred: <code>%s</code></p>',
htmlspecialchars($e->getMessage()));
}
$_SESSION[$tokenSessionKey] = $client->getAccessToken();
} elseif ($OAUTH2_CLIENT_ID == 'REPLACE_ME') {
$htmlBody = <<<END
<h3>Client Credentials Required</h3>
<p>
You need to set <code>\$OAUTH2_CLIENT_ID</code> and
<code>\$OAUTH2_CLIENT_ID</code> before proceeding.
<p>
END;
} else {
// If the user hasn't authorized the app, initiate the OAuth flow
$state = mt_rand();
$client->setState($state);
$_SESSION['state'] = $state;
$authUrl = $client->createAuthUrl();
$htmlBody = <<<END
<h3>Authorization Required</h3>
<p>You need to <a href="$authUrl">authorize access</a> before proceeding.<p>
END;
}
?>
<!doctype html>
<html>
<head>
<title>Claim Uploaded</title>
</head>
<body>
<?=$htmlBody?>
</body>
</html>
Python
O exemplo de código abaixo chama o método thumbnails.set da API para fazer upload de uma imagem e defini-la como a imagem em miniatura de um vídeo. A solicitação deve ser autorizada pelo canal que possui o vídeo.
Este exemplo usa a biblioteca cliente Python.
#!/usr/bin/python
import httplib2
import os
import sys
from apiclient.discovery import build
from apiclient.errors import HttpError
from oauth2client.client import flow_from_clientsecrets
from oauth2client.file import Storage
from oauth2client.tools import argparser, run_flow
# The CLIENT_SECRETS_FILE variable specifies the name of a file that contains
# the OAuth 2.0 information for this application, including its client_id and
# client_secret. You can acquire an OAuth 2.0 client ID and client secret from
# the Google API Console at
# https://console.cloud.google.com/.
# Please ensure that you have enabled the YouTube Data API for your project.
# For more information about using OAuth2 to access the YouTube Data API, see:
# https://developers.google.com/youtube/v3/guides/authentication
# For more information about the client_secrets.json file format, see:
# https://developers.google.com/api-client-library/python/guide/aaa_client_secrets
CLIENT_SECRETS_FILE = "client_secrets.json"
# This OAuth 2.0 access scope allows for full read/write access to the
# authenticated user's account.
YOUTUBE_READ_WRITE_SCOPE = "https://www.googleapis.com/auth/youtube"
YOUTUBE_API_SERVICE_NAME = "youtube"
YOUTUBE_API_VERSION = "v3"
# This variable defines a message to display if the CLIENT_SECRETS_FILE is
# missing.
MISSING_CLIENT_SECRETS_MESSAGE = """
WARNING: Please configure OAuth 2.0
To make this sample run you will need to populate the client_secrets.json file
found at:
%s
with information from the API Console
https://console.cloud.google.com/
For more information about the client_secrets.json file format, please visit:
https://developers.google.com/api-client-library/python/guide/aaa_client_secrets
""" % os.path.abspath(os.path.join(os.path.dirname(__file__),
CLIENT_SECRETS_FILE))
def get_authenticated_service(args):
flow = flow_from_clientsecrets(CLIENT_SECRETS_FILE,
scope=YOUTUBE_READ_WRITE_SCOPE,
message=MISSING_CLIENT_SECRETS_MESSAGE)
storage = Storage("%s-oauth2.json" % sys.argv[0])
credentials = storage.get()
if credentials is None or credentials.invalid:
credentials = run_flow(flow, storage, args)
return build(YOUTUBE_API_SERVICE_NAME, YOUTUBE_API_VERSION,
http=credentials.authorize(httplib2.Http()))
# Call the API's thumbnails.set method to upload the thumbnail image and
# associate it with the appropriate video.
def upload_thumbnail(youtube, video_id, file):
youtube.thumbnails().set(
videoId=video_id,
media_body=file
).execute()
if __name__ == "__main__":
# The "videoid" option specifies the YouTube video ID that uniquely
# identifies the video for which the thumbnail image is being updated.
argparser.add_argument("--video-id", required=True,
help="ID of video whose thumbnail you're updating.")
# The "file" option specifies the path to the thumbnail image file.
argparser.add_argument("--file", required=True,
help="Path to thumbnail image file.")
args = argparser.parse_args()
if not os.path.exists(args.file):
exit("Please specify a valid file using the --file= parameter.")
youtube = get_authenticated_service(args)
try:
upload_thumbnail(youtube, args.video_id, args.file)
except HttpError, e:
print "An HTTP error %d occurred:\n%s" % (e.resp.status, e.content)
else:
print "The custom thumbnail was successfully set."
Erros
A tabela abaixo identifica as mensagens de erro que a API pode retornar em resposta a uma chamada para este método. Consulte a documentação mensagem de erro para mais detalhes.
| Tipo de erro | Detalhe do erro | Descrição |
|---|---|---|
badRequest |
mediaBodyRequired |
A solicitação não inclui o conteúdo da imagem. |
forbidden |
forbidden |
A miniatura não pode ser configurada para o vídeo especificado. A solicitação pode não es devidamente autorizada. |
forbidden |
forbidden |
O usuário autenticado não tem permissões para carregar e configurar miniaturas de vídeo personalizadas. |
notFound |
videoNotFound |
O vídeo no qual você está tentando inserir uma imagem em miniatura não pode ser encontrado. Verifique o valor do parâmetro videoId da solicitação para garantir que ele esteja correto. |