YouTubeVideoUploadService позволяет загружать видео непосредственно на YouTube через Google Ads API. Эти видео можно использовать для создания видеообъектов в различных типах объявлений, например в кампаниях с максимальной эффективностью или кампаниях для создания спроса.
Этот сервис упрощает процесс создания видеообъявлений, поскольку позволяет загружать видео на YouTube и связывать их с вашим аккаунтом.
Основные понятия
Прежде чем начать, важно понять, как происходит управление загрузкой видео и какие статусы могут быть у видео.
Сквозной рабочий процесс
Чтобы загрузить видеофайл и показывать его в объявлении, необходимо выполнить четыре последовательных шага:
| Шаг | Сервис и метод | Сводка |
|---|---|---|
| 1. Инициализация и загрузка видео | CreateYouTubeVideoUpload на YouTubeVideoUploadService |
Загрузите метаданные видео и двоичный файл, чтобы создать ресурс YouTubeVideoUpload (customers/{customer_id}/youTubeVideoUploads/{video_upload_id}). |
| 2. Статус обработки опроса | SearchStream на GoogleAdsService |
Запрос you_tube_video_upload до state = 'PROCESSED' и 11-символьный идентификатор YouTube video_id заполнены. |
| 3. Как создать видеообъект для многократного использования | MutateAssets на AssetService |
Создайте YoutubeVideoAsset (youtube_video_id = video_id), чтобы получить название ресурса объекта (customers/{customer_id}/assets/{asset_id}). |
| 4. Как связать объект с кампаниями или объявлениями | MutateAssetGroupAssets на AssetGroupAssetService или MutateAdGroupAds на AdGroupAdService |
Свяжите объект с кампанией с максимальной эффективностью AssetGroupAsset (field_type = YOUTUBE_VIDEO) или кампанией для создания спроса DemandGenVideoResponsiveAdInfo (videos[].asset). |
Владелец канала
При загрузке видео вы можете указать целевой канал YouTube, используя поле channel_id в ресурсе YouTubeVideoUpload:
- Канал, принадлежащий рекламодателю (бренду). Укажите
channel_idсуществующего канала YouTube, принадлежащего рекламодателю. Этот параметр поддерживается только при аутентификации пользователей и не может использоваться с сервисными аккаунтами. - Канал, управляемый Google. Если параметр
channel_idне указан, видео загружается на канал YouTube, управляемый Google и связанный с аккаунтом Google Рекламы.
Статусы загрузки
Жизненный цикл загруженного на YouTube видео отслеживается с помощью поля state.
Перечисление YouTubeVideoUploadState определяет следующие состояния:
| Штат | Описание |
|---|---|
PENDING |
Видео загружается. |
UPLOADED |
Видео загружено и обрабатывается YouTube. |
PROCESSED |
Видео обработано и готово к использованию. |
FAILED |
Не удалось загрузить или обработать файл. |
REJECTED |
Видео было отклонено из-за несоответствия требованиям или нарушения правил. |
UNAVAILABLE |
Статус видео недоступен. Возможно, оно было удалено с YouTube. |
Настройки конфиденциальности
В поле video_privacy можно указать, кто может смотреть загруженное видео. Перечисление YouTubeVideoPrivacy поддерживает:
PUBLIC: видео доступно всем пользователям YouTube. (Доступно только для брендированных каналов).UNLISTED– видео не показывается в результатах поиска, но его может посмотреть любой пользователь, у которого есть ссылка. Это вариант по умолчанию и единственный вариант для каналов, управляемых Google.
Раскрытие информации о контенте, созданном генеративным ИИ
Начиная с версии 26, в соответствии с такими нормативными актами, как закон ЕС об ИИ, рекламодатели могут сообщать, содержит ли загруженный видеоконтент синтетические медиафайлы или материалы, созданные искусственным интеллектом.
Поле video_content_metadata в YouTubeVideoUpload содержит VideoContentMetadata. Задайте вложенное поле generative_content_disclosure, используя перечисление YouTubeVideoUploadGenerativeContentDisclosure:
| Значение | Описание |
|---|---|
NON_GENERATIVE_CONTENT |
Рекламодатель указал, что видео не создано искусственным интеллектом. |
GENERATIVE_CONTENT |
Рекламодатель указал, что видео создано искусственным интеллектом. |
Как загрузить видео
Чтобы загрузить видео, необходимо использовать многокомпонентный запрос к методу CreateYouTubeVideoUpload. Запрос содержит как метаданные загрузки, так и сам видеофайл.
1. Запустите загрузку
Создайте объект CreateYouTubeVideoUploadRequest со следующими полями:
| Поле | Требования | Описание и ограничения |
|---|---|---|
customer_id |
Обязательно | Десятизначный идентификатор клиента Google Рекламы (без дефисов). |
you_tube_video_upload.video_title |
Обязательные (INPUT_ONLY, IMMUTABLE) |
Название загруженного видео на YouTube (до 100 символов; не может содержать < или >). |
you_tube_video_upload.video_description |
Необязательно (INPUT_ONLY, IMMUTABLE) |
Описание видео на YouTube (до 5000 символов; не может содержать < или >). |
you_tube_video_upload.channel_id |
Необязательно (IMMUTABLE) |
Идентификатор целевого канала YouTube, принадлежащего рекламодателю (24 символа, начинается с UC). Если не указать, видео будет загружено на канал, управляемый Google. |
you_tube_video_upload.video_privacy |
Необязательно (можно изменить на каналах брендов) | YouTubeVideoPrivacy (UNLISTED по умолчанию или PUBLIC для брендированных каналов, принадлежащих рекламодателю). |
you_tube_video_upload.video_content_metadata |
Необязательно (INPUT_ONLY, IMMUTABLE) |
Доступно с версии 26: VideoContentMetadata с атрибутом generative_content_disclosure, для которого задано значение YouTubeVideoUploadGenerativeContentDisclosure (NON_GENERATIVE_CONTENT или GENERATIVE_CONTENT). |
Если вы используете клиентскую библиотеку, вызовите метод CreateYouTubeVideoUpload, передав ему видеофайл. Загрузка видео будет выполнена автоматически.
Java
String videoUploadResourceName; try (YouTubeVideoUploadServiceClient youTubeVideoUploadServiceClient = googleAdsClient.getLatestVersion().createYouTubeVideoUploadServiceClient()) { YouTubeVideoUpload youTubeVideoUpload = YouTubeVideoUpload.newBuilder() .setVideoTitle("Test Video") .setVideoDescription("Test Video Description") .setVideoPrivacy(YouTubeVideoPrivacy.UNLISTED) .build(); CreateYouTubeVideoUploadRequest createUploadRequest = CreateYouTubeVideoUploadRequest.newBuilder() .setCustomerId(Long.toString(customerId)) .setYouTubeVideoUpload(youTubeVideoUpload) .build(); CreateYouTubeVideoUploadResponse response = youTubeVideoUploadServiceClient.createYouTubeVideoUpload( createUploadRequest, () -> new FileInputStream(videoFile), null); videoUploadResourceName = response.getResourceName(); System.out.printf("Created YouTube video upload: %s%n", videoUploadResourceName); }
C#
YouTubeVideoUploadServiceClient ytService = client.GetService( Services.V26.YouTubeVideoUploadService); CreateYouTubeVideoUploadRequest createUploadRequest = new CreateYouTubeVideoUploadRequest() { CustomerId = customerId.ToString(), YouTubeVideoUpload = new YouTubeVideoUpload() { VideoTitle = "Test Video", VideoDescription = "Test Video Description", VideoPrivacy = YouTubeVideoPrivacy.Unlisted } }; string videoUploadResourceName; using (FileStream stream = File.OpenRead(videoFilePath)) { ResumableUploadSession<CreateYouTubeVideoUploadRequest, CreateYouTubeVideoUploadResponse> session = ytService.CreateYouTubeVideoUpload(); CreateYouTubeVideoUploadResponse response = session.BeginUploadAsync(createUploadRequest, stream).Result; videoUploadResourceName = response.ResourceName; Console.WriteLine($"Created YouTube video upload: {videoUploadResourceName}"); }
PHP
$youTubeVideoUploadServiceClient = $googleAdsClient->getYouTubeVideoUploadServiceClient(); $youTubeVideoUpload = new YouTubeVideoUpload([ 'video_title' => 'Test Video', 'video_description' => 'Test Video Description', 'video_privacy' => YouTubeVideoPrivacy::UNLISTED ]); $createYouTubeVideoUploadRequest = CreateYouTubeVideoUploadRequest::build( $customerId, $youTubeVideoUpload ); /** @var ResumableUpload $resumableUpload */ $resumableUpload = $youTubeVideoUploadServiceClient->createYouTubeVideoUpload( $createYouTubeVideoUploadRequest ); $stream = Utils::streamFor(fopen($videoFilePath, 'rb')); /** @var CreateYouTubeVideoUploadResponse $response */ $response = $resumableUpload->startUpload($stream); $videoUploadResourceName = $response->getResourceName(); printf("Created YouTube video upload: '%s'%s", $videoUploadResourceName, PHP_EOL);
Python
yt_service: YouTubeVideoUploadServiceClient = client.get_service( "YouTubeVideoUploadService" ) create_upload_request: CreateYouTubeVideoUploadRequest = ( youtube_video_upload_service.CreateYouTubeVideoUploadRequest() ) create_upload_request.customer_id = customer_id create_upload_request.you_tube_video_upload.video_title = "Test Video" create_upload_request.you_tube_video_upload.video_description = ( "Test Video Description" ) create_upload_request.you_tube_video_upload.video_privacy = ( client.enums.YouTubeVideoPrivacyEnum.UNLISTED ) video_upload_resource_name: str with open(video_file_path, "rb") as stream: response: CreateYouTubeVideoUploadResponse = ( yt_service.create_you_tube_video_upload( stream=stream, request=create_upload_request, retry=None, ) ) video_upload_resource_name = response.resource_name print(f"Created YouTube video upload: {video_upload_resource_name}")
Ruby
video_upload = client.resource.you_tube_video_upload do |v| v.video_title = "Test Video" v.video_description = "Test Video Description" v.video_privacy = :UNLISTED end upload = client.service.you_tube_video_upload.create_you_tube_video_upload( customer_id: customer_id, you_tube_video_upload: video_upload, ) video_upload_resource_name = nil File.open(video_file_path, "rb") do |stream| response = upload.start( stream: stream, content_type: "application/octet-stream", ) video_upload_resource_name = response.resource_name puts "Created YouTube video upload: #{video_upload_resource_name}" end
Perl
This example is not yet available in Perl; you can take a look at the other languages.
curl
# # Use the --i curl parameter to capture response headers in the $RESPONSE # variable. FILE_SIZE=$(wc -c < "${VIDEO_FILE_NAME}" | tr -d '\r') RESPONSE=$(curl -i -f -v -s --request POST \ "https://googleads.googleapis.com/resumable/upload/v${API_VERSION}/customers/${CUSTOMER_ID}/youTubeVideoUploads:create" \ --header "Content-Type: application/json" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --header "X-Goog-Upload-Protocol: resumable" \ --header "X-Goog-Upload-Command: start" \ --header "X-Goog-Upload-Header-Content-Length: ${FILE_SIZE}" \ --data @- <<EOF { "customer_id": "${CUSTOMER_ID}", "you_tube_video_upload": { "video_title": "${VIDEO_TITLE}", "video_description": "${VIDEO_DESCRIPTION}", "video_privacy": "UNLISTED" } } EOF ) # Extract the value of the "x-goog-upload-url" header from the HTTP response. UPLOAD_URL=$(echo "${RESPONSE}" \ | grep -i '^x-goog-upload-url' \ | awk '{print $2}' \ | tr -d '\r') CHUNK_SIZE=$(echo "${RESPONSE}" \ | grep -i '^x-goog-upload-chunk-granularity' \ | awk '{print $2}' \ | tr -d '\r')
Если вы используете REST, в следующем разделе описано, как управлять загрузкой видео.
2. Загрузите видео.
При загрузке с помощью REST CreateYouTubeVideoUpload использует двухэтапный протокол возобновляемой загрузки:
- Начните сеанс загрузки. Отправьте исходный запрос
POSTконечной точке загрузкиCreateYouTubeVideoUpload(/upload/v26/customers/{customer_id}/youTubeVideoUploads:create) с параметромx-goog-upload-command: start(и при необходимостиx-goog-upload-header-content-length, чтобы указать размер файла). В ответе будет URL сеанса загрузки в заголовке HTTP-ответаx-goog-upload-url, а также метаданные, например ожидаемый размер фрагмента. - Передайте и завершите обработку байтов видео. Отправьте двоичные полезные данные видео в конечную точку
x-goog-upload-urlс помощьюx-goog-upload-command: upload, finalize. После завершения загрузки в ответе возвращается созданный объектresource_name(customers/{customer_id}/youTubeVideoUploads/{video_upload_id}).
Полное описание HTTP-заголовков, используемых в протоколе загрузки видео, приведено в следующем примере кода:
# Take the first ${CHUNK_SIZE} bytes of the video file and upload them. head -c ${CHUNK_SIZE} ${VIDEO_FILE_NAME} | curl -i -v -X PUT "${UPLOAD_URL}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --header "X-Goog-Upload-Offset: 0" \ --header "X-Goog-Upload-Command: upload" \ --header "Content-Length: ${CHUNK_SIZE}" \ --data-binary @- # Query the status of the upload. QUERY_RESPONSE=$(curl -i -s -X POST "${UPLOAD_URL}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --header "X-Goog-Upload-Command: query") # Extract the value of the "x-goog-upload-size-received" header from the HTTP # response. UPLOADED_BYTES=$(echo "${QUERY_RESPONSE}" \ | grep -i '^x-goog-upload-size-received' \ | awk '{print $2}' \ | tr -d '\r') echo "Uploaded ${UPLOADED_BYTES} bytes." REMAINING_BYTES=$((FILE_SIZE - UPLOADED_BYTES)) echo "${REMAINING_BYTES} bytes remaining to upload." FINALIZE_RESPONSE=$(tail -c ${REMAINING_BYTES} ${VIDEO_FILE_NAME} | curl -v -X PUT "${UPLOAD_URL}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --header "X-Goog-Upload-Offset: ${UPLOADED_BYTES}" \ --header "X-Goog-Upload-Command: upload, finalize" \ --data-binary @-) UPLOADED_VIDEO_RESOURCE_NAME=$(echo $FINALIZE_RESPONSE | jq -r '.resourceName')
3. Как получить статус загрузки видео
После начала загрузки видео запрашивайте статус его обработки, отправляя запросы GAQL к выбираемым полям ресурса you_tube_video_upload (resource_name, video_upload_id, channel_id, video_id, state и video_privacy), пока не получите значение state = 'PROCESSED' (поля INPUT_ONLY нельзя выбрать в GAQL):
Java
// Retrieve the metadata of the newly uploaded video. String query = String.format( "SELECT " + "you_tube_video_upload.resource_name, " + "you_tube_video_upload.video_id, " + "you_tube_video_upload.state " + "FROM you_tube_video_upload " + "WHERE you_tube_video_upload.resource_name = '%s'", videoUploadResourceName); try (GoogleAdsServiceClient googleAdsServiceClient = googleAdsClient.getLatestVersion().createGoogleAdsServiceClient()) { SearchGoogleAdsStreamRequest request = SearchGoogleAdsStreamRequest.newBuilder() .setCustomerId(Long.toString(customerId)) .setQuery(query) .build(); ServerStream<SearchGoogleAdsStreamResponse> stream = googleAdsServiceClient.searchStreamCallable().call(request); for (SearchGoogleAdsStreamResponse response : stream) { for (GoogleAdsRow googleAdsRow : response.getResultsList()) { YouTubeVideoUpload video = googleAdsRow.getYouTubeVideoUpload(); System.out.printf( "Video with ID %s was found in state %s.%n", video.getVideoId(), video.getState()); } } }
C#
// Retrieve the metadata of the newly uploaded video. string query = $@" SELECT you_tube_video_upload.resource_name, you_tube_video_upload.video_id, you_tube_video_upload.state FROM you_tube_video_upload WHERE you_tube_video_upload.resource_name = '{videoUploadResourceName}'"; GoogleAdsServiceClient gaService = client.GetService( Services.V26.GoogleAdsService); gaService.SearchStream(customerId.ToString(), query, delegate (SearchGoogleAdsStreamResponse resp) { foreach (GoogleAdsRow row in resp.Results) { Console.WriteLine( $"Video with ID {row.YouTubeVideoUpload.VideoId} was found in " + $"state {row.YouTubeVideoUpload.State}."); } } );
PHP
// Retrieve the metadata of the newly uploaded video. $query = sprintf( "SELECT you_tube_video_upload.resource_name, " . "you_tube_video_upload.video_id, " . "you_tube_video_upload.state " . "FROM you_tube_video_upload " . "WHERE you_tube_video_upload.resource_name = '%s'", $videoUploadResourceName ); $googleAdsServiceClient = $googleAdsClient->getGoogleAdsServiceClient(); $stream = $googleAdsServiceClient->searchStream( SearchGoogleAdsStreamRequest::build($customerId, $query) ); foreach ($stream->iterateAllElements() as $googleAdsRow) { /** @var GoogleAdsRow $googleAdsRow */ printf( "Video with ID '%s' was found in state '%s'.%s", $googleAdsRow->getYouTubeVideoUpload()->getVideoId(), YouTubeVideoUploadState::name($googleAdsRow->getYouTubeVideoUpload()->getState()), PHP_EOL ); }
Python
# Retrieve the metadata of the newly uploaded video. query: str = f""" SELECT you_tube_video_upload.resource_name, you_tube_video_upload.video_id, you_tube_video_upload.state FROM you_tube_video_upload WHERE you_tube_video_upload.resource_name = '{video_upload_resource_name}'""" ga_service: GoogleAdsServiceClient = client.get_service("GoogleAdsService") stream: Iterator[SearchGoogleAdsStreamResponse] = ga_service.search_stream( customer_id=customer_id, query=query ) for row in itertools.chain.from_iterable(batch.results for batch in stream): video = row.you_tube_video_upload print( f"Video with ID {row.you_tube_video_upload.video_id} was found in state {row.you_tube_video_upload.state}." )
Ruby
# Retrieve the metadata of the newly uploaded video. query = <<~EOQ SELECT you_tube_video_upload.resource_name, you_tube_video_upload.video_id, you_tube_video_upload.state FROM you_tube_video_upload WHERE you_tube_video_upload.resource_name = '#{video_upload_resource_name}' EOQ responses = client.service.google_ads.search_stream( customer_id: customer_id, query: query, ) responses.each do |batch| batch.results.each do |row| puts "Video with ID #{row.you_tube_video_upload.video_id} was found in " \ "state #{row.you_tube_video_upload.state}." end end
Perl
This example is not yet available in Perl; you can take a look at the other languages.
curl
curl -i -v -X POST \ "https://qa-prod-googleads.sandbox.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:search" \ --header "Content-Type: application/json" \ --header "Developer-Token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data @- <<EOF { "query": "SELECT you_tube_video_upload.resource_name, you_tube_video_upload.video_id, you_tube_video_upload.state FROM you_tube_video_upload WHERE you_tube_video_upload.resource_name = '$UPLOADED_VIDEO_RESOURCE_NAME'" } EOF
Управление загрузками
После загрузки видео вы можете использовать его в качестве видеообъекта.
Использовать загруженное видео
Когда видео перейдет в статус PROCESSED, вы сможете найти его 11-значный идентификатор видео на YouTube в поле video_id ресурса YouTubeVideoUpload.
Используйте этот video_id, чтобы создать YoutubeVideoAsset с помощью MutateAssets, и свяжите полученное название ресурса объекта (customers/{customer_id}/assets/{asset_id}) со своими кампаниями или объявлениями:
Создайте
YoutubeVideoAsset, передавyoutube_video_idвAssetService.MutateAssets:POST https://googleads.googleapis.com/v26/customers/{customer_id}/assets:mutate { "operations": [ { "create": { "name": "Product Launch Video", "youtubeVideoAsset": { "youtubeVideoId": "dQw4w9WgXcQ" } } } ] }Свяжите
AssetсAssetGroupилиAdGroupAd:Кампания с максимальной эффективностью. Создайте
AssetGroupAssetс помощьюAssetGroupAssetService.MutateAssetGroupAssets, задав дляfield_typeзначениеYOUTUBE_VIDEO:POST https://googleads.googleapis.com/v26/customers/{customer_id}/assetGroupAssets:mutate { "operations": [ { "create": { "assetGroup": "customers/{customer_id}/assetGroups/{asset_group_id}", "asset": "customers/{customer_id}/assets/{asset_id}", "fieldType": "YOUTUBE_VIDEO" } } ] }Кампании для создания спроса. При вызове
AdGroupAdService.MutateAdGroupAdsукажитеcustomers/{customer_id}/assets/{asset_id}в спискеvideosобъектаDemandGenVideoResponsiveAdInfo.POST https://googleads.googleapis.com/v26/customers/{customer_id}/adGroupAds:mutate { "operations": [ { "create": { "adGroup": "customers/{customer_id}/adGroups/{ad_group_id}", "status": "PAUSED", "ad": { "name": "Demand Gen Video Ad", "finalUrls": ["https://www.example.com"], "demandGenVideoResponsiveAd": { "videos": [ { "asset": "customers/{customer_id}/assets/{asset_id}" } ], "logoImages": [ { "asset": "customers/{customer_id}/assets/{logo_asset_id}" } ], "headlines": [ { "text": "Example Headline" } ], "longHeadlines": [ { "text": "Example Long Headline" } ], "descriptions": [ { "text": "Example Description" } ], "businessName": { "text": "Example Business" } } } } } ] }
Запросите существующие объекты
YOUTUBE_VIDEO, используяGoogleAdsService.SearchStream:SELECT asset.id, asset.resource_name, asset.name, asset.type, asset.youtube_video_asset.youtube_video_id, asset.youtube_video_asset.youtube_video_title FROM asset WHERE asset.type = 'YOUTUBE_VIDEO' AND asset.youtube_video_asset.youtube_video_id = '{video_id}'
Обновить метаданные
Чтобы изменить настройки конфиденциальности видео, загруженного через этот API, используйте метод UpdateYouTubeVideoUpload, задав для параметра update_mask значение "video_privacy". После создания можно изменить только поле video_privacy (PUBLIC или UNLISTED для видео, загруженных на принадлежащий рекламодателю брендированный канал). Поля video_title, video_description, channel_id и video_content_metadata изменять нельзя.
Удалить загрузки
Если вам нужно удалить видео, загруженные с помощью Google Ads API, передайте их имена ресурсов customers/{customer_id}/youTubeVideoUploads/{video_upload_id} в поле resource_names метода RemoveYouTubeVideoUpload. Видео будет удалено из библиотеки объектов Google Рекламы и с YouTube.