Participe da nossa transmissão ao vivo no Discord no servidor da comunidade de publicidade e medição do Google e no YouTube em 26 de fevereiro às 10h (horário de Brasília)! Vamos falar sobre os novos recursos adicionados à v23.1 da API Google Ads.

Enviar vídeos

O YouTubeVideoUploadService permite enviar vídeos diretamente para o YouTube usando a API Google Ads. Esses vídeos podem ser usados como recursos em vários tipos de anúncios, como campanhas Performance Max ou campanhas Geração de demanda.

Esse serviço simplifica o fluxo de trabalho de criação de anúncios em vídeo ao lidar com o processo de upload do YouTube, garantindo que os vídeos sejam associados corretamente à sua conta.

Principais conceitos

Antes de começar, é importante entender como os envios de vídeo são gerenciados e os diferentes estados que eles podem passar.

Propriedade do canal

Ao enviar um vídeo, você pode especificar o canal de destino do YouTube usando o campo channel_id no recurso YouTubeVideoUpload:

Canal do anunciante (marca):forneça o channel_id de um canal do YouTube pertencente ao anunciante. Ao fazer upload para um canal da marca, você tem mais controle sobre a privacidade e a visibilidade do vídeo.
Canal gerenciado pelo Google:se channel_id for omitido, o vídeo será enviado a um canal do YouTube gerenciado pelo Google associado à conta do Google Ads.

Estados de upload

O ciclo de vida de um envio de vídeo do YouTube é rastreado pelo campo state. O enum YouTubeVideoUploadState define os seguintes estados:

Estado	Descrição
`PENDING`	O vídeo está sendo enviado.
`UPLOADED`	O vídeo foi enviado e está sendo processado pelo YouTube.
`PROCESSED`	O vídeo foi processado e está pronto para uso.
`FAILED`	O upload ou o processamento falhou e não pode ser concluído.
`REJECTED`	O vídeo foi rejeitado por motivos de validação ou política.
`UNAVAILABLE`	O estado do vídeo não está disponível. Talvez ele tenha sido removido do YouTube.

Configurações de privacidade

O campo video_privacy controla quem pode ver o vídeo enviado. O enum YouTubeVideoPrivacy é compatível com:

PUBLIC: o vídeo está disponível para qualquer pessoa no YouTube. (Permitido apenas para canais de marca).
UNLISTED: o vídeo não pode ser pesquisado, mas pode ser assistido por qualquer pessoa com o link. Essa é a opção padrão e única para canais gerenciados pelo Google.

Enviar um vídeo

Para fazer upload de um vídeo, use uma solicitação de várias partes para o método CreateYouTubeVideoUpload. A solicitação contém os metadados do envio e o arquivo de vídeo.

1. Iniciar o upload

Crie um CreateYouTubeVideoUploadRequest especificando:

customer_id: seu ID de cliente do Google Ads.
you_tube_video_upload: um objeto YouTubeVideoUpload com video_title, video_description e, opcionalmente, channel_id e video_privacy.

Se você estiver usando uma biblioteca de cliente, chame o método CreateYouTubeVideoUpload e transmita seu arquivo de vídeo. O upload será processado internamente.

Java

This example is not yet available in Java; you can take a look at the other languages.

C#

This example is not yet available in C#; you can take a look at the other languages.

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,
        )
    )
    print(f"Created YouTube video upload: {response.resource_name}")upload_video.py

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')upload_video.sh

Se você estiver usando REST, a seção a seguir descreve como gerenciar o envio de vídeo.

2. Envie o vídeo.

Quando você envia uma solicitação REST para o método CreateYouTubeVideoUpload, a resposta contém o URL a ser usado para fazer upload dos bytes de vídeo no cabeçalho de resposta HTTP x-goog-upload-url, além de outros metadados, como o tamanho esperado de cada parte para uploads em partes.

Você também pode declarar o tamanho do vídeo que vai enviar inicialmente ao iniciar o processo com o cabeçalho de solicitação HTTP x-goog-upload-header-content-length.

Para uma descrição completa dos cabeçalhos HTTP usados no protocolo de upload de vídeo, consulte o exemplo de código a seguir:

# 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')upload_video.sh

3. Recuperar o estado de upload do vídeo

Depois de iniciar o envio de um vídeo, você pode recuperar o estado dele consultando o recurso you_tube_video_upload com GAQL:

Java

This example is not yet available in Java; you can take a look at the other languages.

C#

This example is not yet available in C#; you can take a look at the other languages.

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}."
    )upload_video.py

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'"
}
EOFupload_video.sh

Gerenciar uploads

Depois que o upload de um vídeo for concluído, você poderá usá-lo como um recurso de vídeo.

Usar o vídeo enviado

Depois que um vídeo atinge o estado PROCESSED, é possível encontrar o ID do vídeo do YouTube no campo video_id do recurso YouTubeVideoUpload.

Use este video_id para criar um VideoAsset ou vincule-o diretamente a tipos de anúncio que aceitam vídeos do YouTube referenciando o ID do vídeo.

Atualizar metadados

É possível atualizar os metadados de um vídeo enviado por essa API usando o método UpdateYouTubeVideoUpload. Apenas os campos video_title, video_description e video_privacy podem ser atualizados.

Remover uploads

Se você precisar excluir vídeos enviados com a API Google Ads, use o método RemoveYouTubeVideoUpload. Isso vai remover o vídeo da Biblioteca de recursos do Google Ads e do YouTube.

Recursos de mensagens comerciais

Avançar

Relatórios

Enviar vídeos Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Principais conceitos

Propriedade do canal

Estados de upload

Configurações de privacidade

Enviar um vídeo

1. Iniciar o upload

Java

C#

PHP

Python

Ruby

Perl

curl

2. Envie o vídeo.

3. Recuperar o estado de upload do vídeo

Java

C#

PHP

Python

Ruby

Perl

curl

Gerenciar uploads

Usar o vídeo enviado

Atualizar metadados

Remover uploads

Enviar vídeos