El YouTubeVideoUploadService
te permite subir videos directamente a YouTube a través de la API de Google Ads. Luego, estos
videos se pueden usar para crear recursos de video en varios tipos de anuncios, como
las campañas de máximo rendimiento o
las campañas de generación de demanda.
Este servicio optimiza el flujo de trabajo de creación de anuncios de video, ya que controla el proceso de carga de YouTube y garantiza que los videos estén asociados correctamente con tu cuenta.
Conceptos clave
Antes de comenzar, es importante comprender cómo se administran las cargas de videos y los diferentes estados por los que pueden pasar.
Propiedad del canal
Cuando subes un video, puedes especificar el canal de YouTube de destino con
el channel_id campo en el YouTubeVideoUpload
recurso:
- Canal propiedad del anunciante (de marca): Proporciona el
channel_idde un canal de YouTube existente que sea propiedad del anunciante. Esto solo se admite con el flujo de autenticación de usuarios; no se puede usar con cuentas de servicio. - Canal administrado por Google: Si se omite
channel_id, el video se sube a un canal de YouTube administrado por Google asociado con la cuenta de Google Ads.
Estados de carga
El ciclo de vida de una carga de video de YouTube se realiza un seguimiento con el campo state.
La YouTubeVideoUploadState
enumeración define los siguientes estados:
| Estado | Descripción |
|---|---|
PENDING |
Se está subiendo el video. |
UPLOADED |
El video se subió correctamente y YouTube lo está procesando. |
PROCESSED |
El video se procesó correctamente y está listo para usarse. |
FAILED |
No se pudo completar la carga o el procesamiento. |
REJECTED |
Se rechazó el video por motivos de validación o de política. |
UNAVAILABLE |
El estado del video no está disponible. Es posible que se haya quitado de YouTube. |
Configuración de privacidad
El campo video_privacy controla quién puede ver el video subido. La
YouTubeVideoPrivacy
enumeración admite lo siguiente:
PUBLIC: El video está disponible para cualquier persona en YouTube. (Solo se permite para canales de marca).UNLISTED: No se puede buscar el video, pero cualquier persona con el vínculo puede verlo. Esta es la opción predeterminada y única para los canales administrados por Google.
Cómo subir un video
Para subir un video, debes usar una solicitud de varias partes al método CreateYouTubeVideoUpload. La solicitud contiene los metadatos de la carga y el archivo de video.
1. Inicia la carga
Crea un CreateYouTubeVideoUploadRequest
en el que se especifique lo siguiente:
customer_id: Es tu ID de cliente de Google Ads.you_tube_video_upload: Un objetoYouTubeVideoUploadconvideo_title,video_descriptiony, de manera opcional,channel_idyvideo_privacy.
Si usas una biblioteca cliente, llama al
CreateYouTubeVideoUpload
método y pasa tu archivo de video. La carga de video se controlará de forma
interna.
Java
This example is not yet available in Java; you can take a look at the other languages.
C#
YouTubeVideoUploadServiceClient ytService = client.GetService( Services.V25.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
This example is not yet available in PHP; you can take a look at the other languages.
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
This example is not yet available in Ruby; you can take a look at the other languages.
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 "developer-token: ${DEVELOPER_TOKEN}" \ --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')
Si usas REST, en la siguiente sección, se describe cómo administrar la carga de videos.
2. Sube el video
Cuando envías una solicitud REST al
CreateYouTubeVideoUpload
método, la respuesta contiene la URL que se usará para subir los bytes del video
en el x-goog-upload-url encabezado de respuesta HTTP, junto con otros metadatos, como
el tamaño esperado de cada fragmento para las cargas fragmentadas.
También puedes declarar el tamaño del video que vas a subir inicialmente, cuando comiences el proceso, con el encabezado de la solicitud HTTP x-goog-upload-header-content-length.
Para obtener una descripción completa de los encabezados HTTP que se usan en el protocolo de carga de videos, consulta el siguiente ejemplo de código:
# 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. Recupera el estado de carga del video
Después de iniciar la carga de un video, puedes recuperar su estado consultando el
you_tube_video_upload recurso con GAQL:
Java
This example is not yet available in Java; you can take a look at the other languages.
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.V25.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
This example is not yet available in PHP; you can take a look at the other languages.
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
This example is not yet available in Ruby; you can take a look at the other languages.
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
Administrar cargas de archivos
Una vez que se completa la carga de un video, puedes usarlo como un recurso de video.
Usa el video subido
Después de que un video alcanza el estado PROCESSED, puedes encontrar su ID de video de YouTube en el campo video_id del recurso YouTubeVideoUpload.
Usa este video_id para crear un YoutubeVideoAsset con
MutateAssets o vincularlo directamente a los tipos de anuncios que admiten videos de YouTube
haciendo referencia al ID del video.
Actualizar metadatos
Puedes actualizar los metadatos de un video subido a través de esta API con el método UpdateYouTubeVideoUpload. Solo se pueden actualizar los campos video_title, video_description y video_privacy.
Quitar cargas
Si necesitas borrar videos subidos con la API de Google Ads, usa el método RemoveYouTubeVideoUpload. Esto quitará el video de la biblioteca de recursos de Google Ads y de YouTube.