YouTube에 맞춤 동영상 미리보기 이미지를 업로드하고 이를 동영상에 설정합니다. 예를 참조하세요.
이 메소드는 업로드한 미디어를 지원합니다. 업로드한 파일은 다음 제한사항을 따라야 합니다.
- 최대 파일 크기: 2MB
- 허용된 미디어 MIME 유형:
image/jpeg
,image/png
,application/octet-stream
요청
HTTP 요청
POST https://www.googleapis.com/youtube/v3/thumbnails/set
인증
이 요청에는 다음 범위 중 최소 하나를 사용하여 인증이 필요합니다. (인증 및 승인에 대해 자세히 알아보기)
범위 |
---|
https://www.googleapis.com/auth/youtubepartner |
https://www.googleapis.com/auth/youtube.upload |
https://www.googleapis.com/auth/youtube |
매개변수
아래 표는 이 쿼리가 지원하는 매개변수 목록입니다. 나열된 모든 매개변수는 쿼리 매개변수입니다.
매개변수 이름 | ||
---|---|---|
필수 매개변수 | ||
videoId |
string videoId 매개변수는 맞춤 동영상 미리보기 이미지가 제공되는 YouTube 동영상 ID를 지정합니다. |
|
선택적 매개변수 | ||
onBehalfOfContentOwner |
string 이 매개변수는 제대로 인증된 요청에서만 사용할 수 있습니다. 참고: 이 매개변수는 YouTube 콘텐츠 파트너 전용입니다. onBehalfOfContentOwner 매개변수는 요청의 승인 사용자 인증 정보가 매개변수 값에 지정된 콘텐츠 소유자를 대신하는 YouTube CMS 사용자를 확인함을 나타냅니다. 이 매개변수는 다양한 여러 YouTube 채널을 소유하고 관리하는 YouTube 콘텐츠 파트너 전용입니다. 이 매개변수로 콘텐츠 소유자는 각 개별 채널에 승인 사용자 인증 정보를 제공할 필요 없이 한 번 인증하여 모든 동영상 및 채널 데이터에 액세스할 수 있습니다. 사용자가 인증할 CMS 계정은 지정된 YouTube 콘텐츠 소유자에게 연결되어야 합니다. |
요청 본문
이 메소드를 호출할 때 요청 본문을 제공하지 마세요.
응답
성공하는 경우 이 메소드는 다음 구조로 응답 본문을 반환합니다.
{ "kind": "youtube#thumbnailSetResponse", "etag": etag, "items": [ thumbnails resource ] }
속성
다음 표는 이 리소스에 표시되는 속성을 정의합니다.
속성 이름 | |
---|---|
kind |
string API 리소스의 유형입니다. 값은 youtube#thumbnailSetResponse 가 됩니다. |
etag |
etag 이 리소스의 Etag입니다. |
items[] |
list 미리보기 이미지의 목록입니다. |
예
참고: 아래의 코드 샘플은 지원되는 일부 프로그래밍 언어를 나타냅니다. 지원되는 언어 목록을 보려면 클라이언트 라이브러리 문서를 참조하세요.
PHP
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
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."
오류
아래 표에서는 이 메소드에 대한 호출에 응답하기 위해 API가 반환할 수 있는 오류 메시지를 식별합니다. 자세한 내용은 오류 메시지 설명서를 참조하세요.
오류 유형 | 오류 세부정보 | 설명 |
---|---|---|
badRequest |
mediaBodyRequired |
요청에 이미지 콘텐츠가 포함되어 있지 않습니다. |
forbidden |
forbidden |
지정된 동영상에 미리보기 이미지를 설정할 수 없습니다. 요청이 제대로 인증되지 않았을 수 있습니다. |
forbidden |
forbidden |
인증된 사용자에게 맞춤 동영상 미리보기 이미지를 업로드하고 설정할 수 있는 권한이 없습니다. |
notFound |
videoNotFound |
미리보기 이미지를 삽입하려는 동영상을 찾을 수 없습니다. 요청 videoId 매개변수 값이 올바른지 확인하세요. |