A API Google Ads permite vincular vídeos do YouTube à sua conta do Google Ads. Este guia explica como usar a API para adicionar e remover links da sua conta.
Vincular vídeos
Os vídeos podem ser vinculados à sua conta de duas maneiras, dependendo de quem inicia o processo:
- Você pede para vincular um vídeo à sua conta. Nesse cenário, você envia um pedido a um criador de conteúdo, que precisa aceitar para estabelecer a vinculação ao vídeo dele. Você pode revogar um pedido que foi estendido antes de ser aceito e também remover um vídeo vinculado depois que ele for aceito.
- O criador de conteúdo pede que o vídeo seja vinculado à sua conta do Google Ads. Depois, você pode aceitar ou recusar a solicitação.
Os seguintes métodos são usados em cada cenário:
| Cenário | Ação | Comentários |
|---|---|---|
| Cenário 1 | Receber as informações do vídeo da API YouTube | Use a API do YouTube
para receber o channel_id e enviar a solicitação de link do vídeo, além do video_id
do vídeo que você quer vincular. O video_id é a string de 11 caracteres encontrada nos URLs de vídeos do YouTube (por exemplo, o parâmetro v em www.youtube.com/watch?v=VIDEO_ID ou o caminho em youtu.be/VIDEO_ID). |
| Criar um pedido de vinculação | Use o método
DataLinkService.CreateDataLink
para criar uma solicitação de vinculação, especificando youtube_video.channel_id e youtube_video.video_id
para identificar o vídeo e o canal associado. A partir da v24, você também pode especificar
youtube_link_metadata.brand_channel_id
para fornecer o ID do canal da marca do YouTube vinculado e ajudar os criadores de conteúdo
a entender sua marca.
O status do DataLink não deve ser definido. O servidor da API Google Ads vai definir isso como REQUESTED após a conclusão da chamada de API. |
|
| Inspecionar o status de uma solicitação | Use GoogleAdsService.SearchStream ou GoogleAdsService.Search para consultar o recurso data_link
e inspecionar o
status dele. |
|
| Revogar um pedido | Use o método
DataLinkService.UpdateDataLink
para revogar um pedido de vinculação mudando o status do
DataLink de REQUESTED para REVOKED. |
|
| Remover uma vinculação | Use
DataLinkService.RemoveDataLink para remover um vídeo vinculado. |
|
| Cenário 2 | Recuperar um convite | Use GoogleAdsService.Search
ou GoogleAdsService.SearchStream
para consultar o recurso data_link. Filtre por
status = PENDING_APPROVAL para encontrar pedidos de vinculação
e aceitar ou recusar. |
| Aceitar ou recusar um pedido de vinculação | Use o método
DataLinkService.UpdateDataLink para atualizar o status
do DataLink
para ENABLED (aceitar) ou REJECTED (rejeitar) o
pedido. |
Recuperar detalhes do link
É possível usar GoogleAdsService.Search
ou
GoogleAdsService.SearchStream
para consultar o recurso data_link. A consulta a seguir recupera detalhes de links de vídeos do YouTube, incluindo o ID do vídeo e o ID do canal:
SELECT
data_link.resource_name,
data_link.status,
data_link.youtube_video.video_id,
data_link.youtube_video.channel_id
FROM data_link
WHERE data_link.type = 'VIDEO'
Os seguintes erros comuns podem ser gerados neste fluxo de trabalho:
| Código do erro | Explicação |
|---|---|
DataLinkError.PERMISSION_DENIED |
O cliente não tem permissão para realizar essa ação. |
DataLinkError.YOUTUBE_VIDEO_ID_INVALID |
Não foi possível criar um link de vídeo porque o ID do vídeo é inválido. |
DataLinkError.INVALID_STATUS |
Gerado quando o status atual da vinculação de dados é inválido para a operação solicitada. |
DataLinkError.INVALID_UPDATE_STATUS |
Gerado ao tentar uma transição de status não compatível durante uma atualização (por exemplo, passar diretamente de REVOKED para ENABLED). |
MutateError.RESOURCE_ALREADY_EXISTS |
Gerado quando já existe uma vinculação de dados para o vídeo. |