Detalhes de Conexão do Google Ads

Introdução

Versão do conector

Esta documentação é baseada na versão 21.0.8361 do conector.

Começando

Suporte à versão do Google Ads

O conector fornece uma visualização relacional dos dados do Google Ads para sua conta do Google ou domínio do Google Apps. O conector inclui tabelas contendo dimensões e métricas usadas com frequência; além disso, você pode personalizar os esquemas de tabela ou escrever seus próprios para combinar qualquer conjunto válido de dimensões e métricas. O conector exibe as colunas disponíveis por meio da versão v201809 da API do AdWords.

Estabelecendo uma Conexão

Conectando-se ao Google Ads

Forneça as seguintes propriedades de conexão antes de adicionar as propriedades de autenticação.

• DeveloperToken: Defina isso como o token de desenvolvedor da conta do AdWords. Você pode obter um token de desenvolvedor inscrevendo-se na API do AdWords. Para fazer isso, faça login no site do AdWords com sua conta da MCC e navegue até Configurações -> Configurações da conta -> Centro de API do Google AdWords. Inscreva-se para acesso à API e aguarde o Google entrar em contato com você por e-mail com mais instruções. Você deve receber um token com status pendente. Este token é apenas para teste e não permite que você se conecte a dados ativos. O Google deve entrar em contato com você para preencher um questionário e, assim que for recebido e aprovado pelo Google, você receberá seu token de desenvolvedor ativo.

• ClientCustomerId: Defina como seu ID de cliente do Google Ads. Você pode encontrar o seu ClientCustomerId na parte inferior do menu de ajuda após clicar no ícone de ajuda no canto superior direito da IU do Google Ads.

  Observação: Esta propriedade de conexão é necessária apenas ao usar o 'AdWords' Schema.

Recuperando Dados de Várias Contas

Um uso comum para o driver é recuperar dados de vários IDs de clientes. Isso é útil quando você tem uma conta MCC do Google Ads que inclui várias contas/ClientCustomerIds. Você pode consultar e obter dados das contas que deseja especificando CustomerId na cláusula WHERE, por exemplo:

SELECT * FROM AdGroupAd WHERE CustomerId='3333333333'
SELECT * FROM AdGroupAd WHERE CustomerId IN ('1111111111', '2222222222')

O driver ignora o ClientCustomerId propriedade de conexão quando você especifica o CustomerId em cláusulas WHERE.

Autenticação no Google Ads

Todas as conexões com o Google Ads são autenticadas usando OAuth. O conector oferece suporte ao uso de contas de usuário, contas de serviço e contas de instância do GCP para autenticação.

Autenticar com uma Conta de Usuário

AuthScheme deve ser definido como OAuth em todos os fluxos da conta do usuário. Para aplicativos de desktop, o aplicativo padrão do conector é a maneira mais simples de autenticação. O único requisito adicional é definir InitiateOAuth para GETANDREFRESH.

Quando o driver for iniciado, ele abrirá um navegador e o Google Ads solicitará suas informações de login. O conector usará as credenciais que você fornecer para acessar seus dados do Google Ads. Essas credenciais serão salvas e atualizadas automaticamente conforme necessário.

Consulte Usando autenticação OAuth para obter um guia de autenticação que abrange todos os métodos suportados em detalhes.

Autenticar com uma Conta de Serviço

Para autenticar usando uma conta de serviço, você deve criar uma nova conta de serviço e ter uma cópia do certificado de contas.

Para um arquivo JSON, você precisará definir estas propriedades:

• AuthScheme: Obrigatório. Defina isso como OAuthJWT.
• InitiateOAuth: Obrigatório. Defina isso como GETANDREFRESH.
• OAuthJWTCertType: Obrigatório. Defina isso como GOOGLEJSON.
• OAuthJWTCert: Obrigatório. Defina isso como o caminho para o arquivo .json fornecido pelo Google.
• OAuthJWTSubject: Obrigatório. A conta de serviço deve fazer parte de um domínio G Suite, com delegação habilitada. O valor desta propriedade deve ser o endereço e-mail do usuário cujos dados você deseja acessar.

Para um arquivo PFX, você precisará definir estas propriedades:

• AuthScheme: Obrigatório. Defina isso como OAuthJWT.
• InitiateOAuth: Obrigatório. Defina isso como GETANDREFRESH.
• OAuthJWTCertType: Obrigatório. Defina isso como PFXFILE.
• OAuthJWTCert: Obrigatório. Defina isso como o caminho para o arquivo .pfx fornecido pelo Google.
• OAuthJWTCertPassword: Opcional. Defina isso como a senha do arquivo .pfx. Na maioria dos casos, isso precisará ser fornecido, pois o Google criptografa os certificados PFX.
• OAuthJWTCertSubject: Opcional. Defina isso apenas se você estiver usando um OAuthJWTCertType que armazena vários certificados. Não deve ser definido para certificados PFX gerados pelo Google.
• OAuthJWTIssuer: Obrigatório. Defina isso como o endereço e-mail da conta de serviço. Este endereço geralmente incluirá o domínio iam.gserviceaccount.com.
• OAuthJWTSubject: Obrigatório. A conta de serviço deve fazer parte de um domínio G Suite, com delegação habilitada. O valor desta propriedade deve ser o endereço e-mail do usuário cujos dados você deseja acessar.

Se você ainda não tiver uma conta de serviço, poderá criar uma seguindo o procedimento em Criando um aplicativo OAuth personalizado.

Autenticar com uma Conta de Instância do GCP

Ao executar em uma máquina virtual GCP, o conector pode autenticar usando uma conta de serviço vinculada à máquina virtual. Para usar este modo, defina AuthScheme para GCPInstanceAccount.

Usando Autenticação OAuth

Use o padrão de autenticação OAuth para se conectar ao Google Ads. Você pode autenticar com uma conta de usuário ou uma conta de serviço. O conector facilita isso conforme descrito abaixo.

Usando uma Conta de Usuário para Autenticar no Google Ads

O fluxo da conta do usuário exige que o usuário autenticado interaja com o Google Ads por meio do navegador.

Credenciais Personalizadas

Quando Criar um Aplicativo OAuth Personalizado

Talvez você queira criar um aplicativo OAuth personalizado para alterar as informações exibidas quando os usuários fazem login no endpoint OAuth do Google Ads para conceder permissões ao conector.

Usando uma Conta de Serviço para Se Conectar ao Google Ads

As contas de serviço têm autenticação silenciosa, sem autenticação do usuário no navegador. Você também pode usar uma conta de serviço para delegar escopos de acesso em toda a empresa ao conector.

Você precisa criar um aplicativo OAuth neste fluxo. Você pode se conectar aos dados do Google Ads que a conta de serviço tem permissão para acessar. Consulte Credenciais personalizadas para obter um guia de autenticação.

Criando um Aplicativo OAuth Personalizado

Consulte Criando um aplicativo OAuth personalizado para um procedimento.

Credenciais Personalizadas

Você pode usar um aplicativo OAuth personalizado para autenticar com uma conta de serviço ou uma conta de usuário. Consulte Usando autenticação OAuth Para maiores informações.

Autenticar com uma Conta de Usuário

Autenticação de Desktop com um Aplicativo OAuth Personalizado

Siga as etapas abaixo para autenticar com as credenciais de um aplicativo OAuth personalizado. Consulte Criando um aplicativo OAuth personalizado.

Obtenha e atualize o token de acesso OAuth

Depois de definir o seguinte, você está pronto para se conectar:

• OAuthClientId: Defina isso para o ID do cliente atribuído quando você registrou seu aplicativo.
• OAuthClientSecret: Defina isso para o segredo do cliente atribuído quando você registrou seu aplicativo.
• InitiateOAuth: Defina como GETANDREFRESH. Você pode usar InitiateOAuth para evitar repetir a troca de OAuth e configurar manualmente o OAuthAccessToken.
• DeveloperToken: Defina isso como o token de desenvolvedor da conta do AdWords. Você pode obter um token de desenvolvedor inscrevendo-se na API do AdWords. Para fazer isso, faça login no site do AdWords com sua conta da MCC e navegue até Configurações -> Configurações da conta -> Centro de API do Google AdWords. Inscreva-se para acesso à API e aguarde o Google entrar em contato com você por e-mail com mais instruções. Você deve receber um token com status pendente. Este token é apenas para teste e não permite que você se conecte a dados ativos. O Google deve entrar em contato com você para preencher um questionário e, assim que for recebido e aprovado pelo Google, você receberá seu token de desenvolvedor ativo.
• ClientCustomerId: defina como o ID de cliente da conta do AdWords. Você pode encontrar esse valor em sua conta do AdWords. Esse valor não é igual ao ID da conta MCC. Você precisa fornecer os IDs de nível mais baixo para recuperar dados.

Quando você conecta, o conector abre o endpoint OAuth em seu navegador padrão. Faça login e conceda permissões ao aplicativo. O conector então conclui o processo OAuth:

1. Extrai o token de acesso da URL de retorno de chamada e autentica as solicitações.
2. Atualiza o token de acesso quando ele expira.
3. Salva valores OAuth em OAuthSettingsLocation para ser persistido nas conexões.

Autenticar com uma Conta de Serviço

As contas de serviço têm autenticação silenciosa, sem autenticação do usuário no navegador. Você também pode usar uma conta de serviço para delegar escopos de acesso em toda a empresa ao conector.

Você precisa criar um aplicativo OAuth neste fluxo. Consulte Criando um aplicativo OAuth personalizado para criar e autorizar um aplicativo. Você pode se conectar aos dados do Google Ads que a conta de serviço tem permissão para acessar.

Depois de definir as seguintes propriedades de conexão, você está pronto para se conectar:

• InitiateOAuth: Defina como GETANDREFRESH.
• OAuthJWTCertType: Defina como "PFXFILE".
• OAuthJWTCert: Defina isso como o caminho para o arquivo .p12 que você gerou.
• OAuthJWTCertPassword: Defina isso como a senha do arquivo .pem.
• OAuthJWTCertSubject: Defina como "*" para escolher o primeiro certificado no armazenamento de certificados.
• OAuthJWTIssuer: Na seção de contas de serviço, clique em Gerenciar contas de serviço e defina este campo para o endereço de e-mail exibido no campo ID da conta de serviço.
• OAuthJWTSubject: Defina como o endereço e-mail do usuário para quem o aplicativo está solicitando acesso delegado. Observe que o acesso delegado deve ser concedido por um administrador.
• DeveloperToken: Defina isso como o token de desenvolvedor da conta do AdWords. Você pode obter um token de desenvolvedor inscrevendo-se na API do AdWords. Para fazer isso, faça login no site do AdWords com sua conta da MCC e navegue até Configurações -> Configurações da conta -> Centro de API do Google AdWords. Inscreva-se para acesso à API e aguarde o Google entrar em contato com você por e-mail com mais instruções. Você deve receber um token com status pendente. Este token é apenas para teste e não permite que você se conecte a dados ativos. O Google deve entrar em contato com você para preencher um questionário e, assim que for recebido e aprovado pelo Google, você receberá seu token de desenvolvedor ativo.
• ClientCustomerId: defina como o ID de cliente da conta do AdWords. Você pode encontrar esse valor em sua conta do AdWords. Esse valor não é igual ao ID da conta MCC. Você precisa fornecer os IDs de nível mais baixo para recuperar dados.

Quando você conecta, o conector conclui o fluxo OAuth para uma conta de serviço.

1. Cria e assina o JWT com o conjunto de declarações exigido pelo conector.
2. Troca o JWT pelo token de acesso.
3. Salva valores OAuth em OAuthSettingsLocation para ser persistido nas conexões.
4. Envia o JWT para um novo token de acesso quando o token expira.

Máquinas Sem Cabeça

Usando OAuth em uma Máquina Sem Periféricos

As seções a seguir mostram como autenticar um servidor headless ou outra máquina na qual o conector não pode abrir um navegador. Você pode autenticar com uma conta de usuário ou com uma conta de serviço.

Autenticar com uma Conta de Usuário

Para autenticar com uma conta de usuário, você precisa autenticar de outra máquina. A autenticação é um processo de duas etapas.

1. Ao invés de instalar o conector em outra máquina, você pode seguir os passos abaixo para obter o OAuthVerifier valor. Ou você pode instalar o conector em outra máquina e transferir os valores de autenticação OAuth, depois de autenticar por meio do fluxo normal baseado em navegador.
2. Em seguida, você pode configurar o conector para atualizar automaticamente o token de acesso da máquina sem periféricos.

Você pode seguir o fluxo de autenticação OAuth headless usando as credenciais OAuth para seu aplicativo OAuth personalizado.

Usando as Credenciais para um Aplicativo OAuth Personalizado

Crie um aplicativo OAuth personalizado

Consulte Criando um aplicativo OAuth personalizado para um procedimento. Você pode seguir os procedimentos abaixo para autenticar e conectar-se aos dados.

Obtenha um código verificador

Defina as seguintes propriedades na máquina sem periféricos:

• InitiateOAuth: Defina como DESLIGADO.
• OAuthClientId: Defina isso como o ID do cliente nas configurações do aplicativo.
• OAuthClientSecret: Defina isso como o segredo do cliente nas configurações do aplicativo.
• DeveloperToken: Defina isso como o token de desenvolvedor da conta do AdWords. Você pode obter um token de desenvolvedor inscrevendo-se na API do AdWords. Para fazer isso, faça login no site do AdWords com sua conta da MCC e navegue até Configurações -> Configurações da conta -> Centro de API do Google AdWords. Inscreva-se para acesso à API e aguarde o Google entrar em contato com você por e-mail com mais instruções. Você deve receber um token com status pendente. Este token é apenas para teste e não permite que você se conecte a dados ativos. O Google deve entrar em contato com você para preencher um questionário e, assim que for recebido e aprovado pelo Google, você receberá seu token de desenvolvedor ativo.
• ClientCustomerId: defina como o ID de cliente da conta do AdWords. Você pode encontrar esse valor em sua conta do AdWords. Esse valor não é igual ao ID da conta MCC. Você precisa fornecer os IDs de nível mais baixo para recuperar dados.

Você pode seguir as etapas abaixo para autenticar em outra máquina e obter o OAuthVerifier propriedade de conexão.

1. Chame o GetOAuthAuthorizationURL procedimento armazenado* com o parâmetro de entrada CallbackURL definido para o URI de redirecionamento exato que você especificou nas configurações do aplicativo.
2. Abra o URL retornado em um navegador. Faça login e conceda permissões ao conector. Você será redirecionado para o URL de retorno de chamada, que contém o código do verificador.
3. Salve o valor do código do verificador. Você definirá isso no OAuthVerifier propriedade de conexão.

Na máquina sem periféricos, defina as seguintes propriedades de conexão para obter os valores de autenticação OAuth:

• OAuthClientId: Defina isso como a chave do consumidor nas configurações do aplicativo.
• OAuthClientSecret: Defina isso como o segredo do consumidor nas configurações do aplicativo.
• OAuthVerifier: Defina isso para o código do verificador.
• OAuthSettingsLocation: Defina para manter os valores de autenticação OAuth criptografados no arquivo especificado.
• InitiateOAuth: Configure para ATUALIZAR.
• DeveloperToken: Defina isso como o token de desenvolvedor da conta do AdWords. Você pode obter um token de desenvolvedor inscrevendo-se na API do AdWords. Para fazer isso, faça login no site do AdWords com sua conta da MCC e navegue até Configurações -> Configurações da conta -> Centro de API do Google AdWords. Inscreva-se para acesso à API e aguarde o Google entrar em contato com você por e-mail com mais instruções. Você deve receber um token com status pendente. Este token é apenas para teste e não permite que você se conecte a dados ativos. O Google deve entrar em contato com você para preencher um questionário e, assim que for recebido e aprovado pelo Google, você receberá seu token de desenvolvedor ativo.
• ClientCustomerId: defina como o ID de cliente da conta do AdWords. Você pode encontrar esse valor em sua conta do AdWords. Esse valor não é igual ao ID da conta MCC. Você precisa fornecer os IDs de nível mais baixo para recuperar dados.

Depois que o arquivo de configurações OAuth for gerado, defina as seguintes propriedades para se conectar aos dados:

• OAuthClientId: Defina isso como a chave do consumidor nas configurações do aplicativo.
• OAuthClientSecret: Defina isso como o segredo do consumidor nas configurações do aplicativo.
• OAuthSettingsLocation: Defina isso para o arquivo que contém os valores de autenticação OAuth criptografados. Certifique-se de que este arquivo forneça permissões de leitura e gravação ao provedor para ativar a atualização automática do token de acesso.
• InitiateOAuth: Configure para ATUALIZAR.
• DeveloperToken: Defina isso como o token de desenvolvedor da conta do AdWords. Você pode obter um token de desenvolvedor inscrevendo-se na API do AdWords. Para fazer isso, faça login no site do AdWords com sua conta da MCC e navegue até Configurações -> Configurações da conta -> Centro de API do Google AdWords. Inscreva-se para acesso à API e aguarde o Google entrar em contato com você por e-mail com mais instruções. Você deve receber um token com status pendente. Este token é apenas para teste e não permite que você se conecte a dados ativos. O Google deve entrar em contato com você para preencher um questionário e, assim que for recebido e aprovado pelo Google, você receberá seu token de desenvolvedor ativo.
• ClientCustomerId: defina como o ID de cliente da conta do AdWords. Você pode encontrar esse valor em sua conta do AdWords. Esse valor não é igual ao ID da conta MCC. Você precisa fornecer os IDs de nível mais baixo para recuperar dados.

Configurações de transferência OAuth

Siga as etapas abaixo para instalar o conector em outra máquina, autenticar e depois transferir os valores OAuth resultantes.

Em uma segunda máquina, instale o conector e conecte-se com o seguinte conjunto de propriedades:

• OAuthSettingsLocation: Defina isso como um arquivo de texto gravável.
• InitiateOAuth: Defina como GETANDREFRESH.
• OAuthClientId: Defina isso para o ID do cliente atribuído quando você registrou seu aplicativo.
• OAuthClientSecret: Defina isso como o segredo do cliente atribuído quando você registrou seu aplicativo.
• DeveloperToken: Defina isso como o token de desenvolvedor da conta do AdWords. Você pode obter um token de desenvolvedor inscrevendo-se na API do AdWords. Para fazer isso, faça login no site do AdWords com sua conta da MCC e navegue até Configurações -> Configurações da conta -> Centro de API do Google AdWords. Inscreva-se para acesso à API e aguarde o Google entrar em contato com você por e-mail com mais instruções. Você deve receber um token com status pendente. Este token é apenas para teste e não permite que você se conecte a dados ativos. O Google deve entrar em contato com você para preencher um questionário e, assim que for recebido e aprovado pelo Google, você receberá seu token de desenvolvedor ativo.
• ClientCustomerId: defina como o ID de cliente da conta do AdWords. Você pode encontrar esse valor em sua conta do AdWords. Esse valor não é igual ao ID da conta MCC. Você precisa fornecer os IDs de nível mais baixo para recuperar dados.

Teste a conexão para autenticar. Os valores de autenticação resultantes são gravados, criptografados, no caminho especificado por OAuthSettingsLocation. Depois de testar a conexão com sucesso, copie o arquivo de configurações OAuth para sua máquina sem periféricos. Na máquina sem periféricos, defina as seguintes propriedades de conexão para se conectar aos dados:

• InitiateOAuth: Configure para ATUALIZAR.
• OAuthClientId: Defina isso como a chave do consumidor nas configurações do aplicativo.
• OAuthClientSecret: Defina isso como o segredo do consumidor nas configurações do aplicativo.
• OAuthSettingsLocation: Defina isso como o caminho para o arquivo de configurações OAuth. Certifique-se de que este arquivo forneça permissões de leitura e gravação ao conector para habilitar a atualização automática do token de acesso.
• DeveloperToken: Defina isso como o token de desenvolvedor da conta do AdWords. Você pode obter um token de desenvolvedor inscrevendo-se na API do AdWords. Para fazer isso, faça login no site do AdWords com sua conta da MCC e navegue até Configurações -> Configurações da conta -> Centro de API do Google AdWords. Inscreva-se para acesso à API e aguarde o Google entrar em contato com você por e-mail com mais instruções. Você deve receber um token com status pendente. Este token é apenas para teste e não permite que você se conecte a dados ativos. O Google deve entrar em contato com você para preencher um questionário e, assim que for recebido e aprovado pelo Google, você receberá seu token de desenvolvedor ativo.
• ClientCustomerId: defina como o ID de cliente da conta do AdWords. Você pode encontrar esse valor em sua conta do AdWords. Esse valor não é igual ao ID da conta MCC. Você precisa fornecer os IDs de nível mais baixo para recuperar dados.

Autenticar com uma Conta de Serviço

As contas de serviço têm autenticação silenciosa, sem autenticação do usuário no navegador. Você também pode usar uma conta de serviço para delegar escopos de acesso em toda a empresa ao conector.

Você precisa criar um aplicativo OAuth neste fluxo. Consulte Criando um aplicativo OAuth personalizado para criar e autorizar um aplicativo. Você pode se conectar aos dados do Google Ads que a conta de serviço tem permissão para acessar.

Depois de definir as seguintes propriedades de conexão, você está pronto para se conectar:

• InitiateOAuth: Defina como GETANDREFRESH.
• OAuthJWTCertType: Defina como "PFXFILE".
• OAuthJWTCert: Defina isso como o caminho para o arquivo .p12 que você gerou.
• OAuthJWTCertPassword: Defina isso como a senha do arquivo .pem.
• OAuthJWTCertSubject: Defina como "*" para escolher o primeiro certificado no armazenamento de certificados.
• OAuthJWTIssuer: Na seção de contas de serviço, clique em Gerenciar contas de serviço e defina este campo para o endereço de e-mail exibido no campo ID da conta de serviço.
• OAuthJWTSubject: Defina como o endereço e-mail do usuário para quem o aplicativo está solicitando acesso delegado. Observe que o acesso delegado deve ser concedido por um administrador.
• DeveloperToken: Defina isso como o token de desenvolvedor da conta do AdWords. Você pode obter um token de desenvolvedor inscrevendo-se na API do AdWords. Para fazer isso, faça login no site do AdWords com sua conta da MCC e navegue até Configurações -> Configurações da conta -> Centro de API do Google AdWords. Inscreva-se para acesso à API e aguarde o Google entrar em contato com você por e-mail com mais instruções. Você deve receber um token com status pendente. Este token é apenas para teste e não permite que você se conecte a dados ativos. O Google deve entrar em contato com você para preencher um questionário e, assim que for recebido e aprovado pelo Google, você receberá seu token de desenvolvedor ativo.
• ClientCustomerId: defina como o ID de cliente da conta do AdWords. Você pode encontrar esse valor em sua conta do AdWords. Esse valor não é igual ao ID da conta MCC. Você precisa fornecer os IDs de nível mais baixo para recuperar dados.

Quando você conecta, o conector conclui o fluxo OAuth para uma conta de serviço.

1. Cria e assina o JWT com o conjunto de declarações exigido pelo conector.
2. Troca o JWT pelo token de acesso.
3. Salva valores OAuth em OAuthSettingsLocation para ser persistido nas conexões.
4. Envia o JWT para um novo token de acesso quando o token expira.

Criando um Aplicativo OAuth Personalizado

Você pode usar um aplicativo OAuth personalizado para autenticar uma conta de serviço ou uma conta de usuário. Consulte Usando autenticação OAuth Para maiores informações.

Crie um Aplicativo OAuth para Autenticação de Conta de Usuário

Siga o procedimento abaixo para registrar um aplicativo e obter o OAuthClientId e OAuthClientSecret.

Crie um Aplicativo OAuth Personalizado: Área de Trabalho

1. Faça login no Google API Console e abra um projeto. Selecione o API Manager no menu principal.
2. Clique em Credenciais -> Criar credenciais -> ID do cliente OAuth. Clique em Outro.

Crie um Aplicativo OAuth para Autenticação de Conta de Serviço

Siga as etapas abaixo para criar um aplicativo OAuth e gerar uma chave privada. Em seguida, você autorizará a conta de serviço.

1. Faça login no Google API Console e abra um projeto. Selecione o API Manager no menu principal.
2. Clique em Criar credenciais -> Chave da conta de serviço.
3. No menu Conta de serviço, selecione Nova conta de serviço ou selecione uma conta de serviço existente.
4. Se estiver criando uma nova conta de serviço, selecione adicionalmente uma ou mais funções. Você pode atribuir funções primitivas no nível do projeto na seção IAM e Admin; outras funções permitem que você personalize ainda mais o acesso às APIs do Google.
5. Na seção Tipo de chave, selecione o tipo de chave P12.
6. Crie o aplicativo para baixar o par de chaves. A senha da chave privada é exibida: Defina isso em OAuthJWTCertPassword.
7. Na seção de contas de serviço, clique em Gerenciar contas de serviço e defina OAuthJWTIssuer para o endereço e-mail exibido no campo ID da conta de serviço.

Recuperando Dados do Google AdWords

Os dados do Google AdWords são organizados em várias métricas (por exemplo, Conversões, Impressões e Cliques Inválidos), que podem ser agrupados por vários segmentos (por exemplo, Data e Dispositivo). Além disso, existem atributos que representam dados fixos ou configurações de conta (por exemplo, CampaignName, AdType e AdGroupStatus). Estes são chamados de Comportamento para o campo. Existem muitas combinações válidas de métricas, segmentos e atributos. O conector exibe cada tipo de relatório separado no Google AdWords como uma tabela.

Selecionando Dados

Ao contrário da maioria das tabelas de banco de dados, não é muito útil selecionar todas as métricas, segmentos e atributos em uma determinada tabela. Em alguns casos, nem é possível fazer isso, pois alguns dados entram em conflito entre si quando selecionados. Como resultado, o conector interpreta a consultar SELECT * para significar que um conjunto padrão de métricas, segmentos e atributos são solicitados. Isso inclui consultas que selecionam explicitamente todas as colunas para contabilizar ferramentas que usam projeção ao retornar resultados. Esses campos padrão representam as colunas padrão expostas por meio do console do Google AdWords. Para selecionar colunas não padrão, simplesmente selecione explicitamente essas colunas na consultar em vez de emitir uma consultar SELECT *. Por fim, é importante observar que pelo menos uma métrica deve ser incluída na solicitação para que qualquer dado seja retornado.

Por padrão, os nomes das colunas são os valores usados pela API.

Outras Considerações

Certos campos de porcentagem podem retornar os valores '< 10%' ou '> 90%'. Para permitir que você use esta coluna como um campo numérico, esses valores são relatados exatamente como '10' e '90', respectivamente.

Acesso a Dados de Ajuste Fino

Google Ads

Selecionando a Versão da API

A Google Ads API adere a um cronograma de descontinuação de aproximadamente a cada 10 meses.
Para compatibilidade com versões anteriores, o conector mantém APIs que foram obsoletas, mas não obsoletas; se seu aplicativo requer uma API obsoleta, você pode configurá-la no Schema propriedade.

Acesso a Dados de Ajuste Fino

Você pode usar as seguintes propriedades para obter maior controle sobre os recursos da Google Ads API e as estratégias que o conector usa para exibi-los:

• IncludeZeroImpressions: Esta propriedade controla se os registros com zero impressões são incluídos nos relatórios.

Anotações Importantes

Procedimentos Armazenados

• Os recursos de procedimentos armazenados descritos nesta documentação não são suportados no momento.
• Como os procedimentos armazenados não são suportados atualmente, qualquer recurso dependente de procedimentos armazenados também não é suportado atualmente.

Arquivos de Configuração e Seus Caminhos

• Todas as referências para adicionar arquivos de configuração e seus caminhos referem-se a arquivos e locais no Harmony Agente onde o conector está instalado. Esses caminhos devem ser ajustados conforme apropriado, dependendo do agente e do sistema operacional. Se vários agentes forem usados em um grupo de agentes, arquivos idênticos serão necessários em cada agente.

Características Avançadas

Esta seção detalha uma seleção de recursos avançados do conector do Google Ads.

Visualizações definidas pelo usuário

O conector permite definir tabelas virtuais, denominadas visões definidas pelo usuário, cujo conteúdo é decidido por uma consultar pré-configurada. Essas exibições são úteis quando você não pode controlar diretamente as consultas enviadas aos drivers. Consulte Visualizações definidas pelo usuário para obter uma visão geral da criação e configuração de exibições personalizadas.

Configuração SSL

Use Configuração SSL para ajustar como o conector lida com as negociações de certificado TLS/SSL. Você pode escolher entre vários formatos de certificado; Veja o SSLServerCert propriedade em "Opções de cadeia de conexão" para obter mais informações.

Procurador

Para configurar o conector usando configurações de proxy do Agente Privado, selecione os Use Proxy Settings caixa de seleção na tela de configuração da conexão.

Visualizações Definidas pelo Usuário

O Jitterbit Connector for Google Ads permite definir uma tabela virtual cujo conteúdo é decidido por uma consultar pré-configurada. Elas são chamadas de Visualizações Definidas pelo Usuário, que são úteis em situações onde você não pode controlar diretamente a consultar que está sendo emitida para o driver, por exemplo, ao usar o driver do Jitterbit. As Visualizações Definidas pelo Usuário podem ser usadas para definir predicados que são sempre aplicados. Se você especificar predicados adicionais na consultar para a visualização, eles serão combinados com a consultar já definida como parte da visualização.

Há duas maneiras de criar exibições definidas pelo usuário:

• Crie um arquivo de configuração em formato JSON definindo as visualizações desejadas.
• declarações DDL.

Definindo Visualizações Usando um Arquivo de Configuração

As visualizações definidas pelo usuário são definidas em um arquivo de configuração formatado em JSON chamado UserDefinedViews.json. O conector detecta automaticamente as visualizações especificadas neste arquivo.

Você também pode ter várias definições de exibição e controlá-las usando o UserDefinedViews propriedade de conexão. Quando você usa essa propriedade, apenas as exibições especificadas são vistas pelo conector.

Este arquivo de configuração de exibição definida pelo usuário é formatado da seguinte forma:

• Cada elemento raiz define o nome de uma exibição.
• Cada elemento raiz contém um elemento filho, chamado query, que contém a consultar SQL personalizada para a visualização.

Por exemplo:

{
    "MyView": {
        "query": "SELECT * FROM CampaignPerformance WHERE MyColumn = 'value'"
    },
    "MyView2": {
        "query": "SELECT * FROM MyTable WHERE Id IN (1,2,3)"
    }
}

Use o UserDefinedViews propriedade de conexão para especificar a localização do seu arquivo de configuração JSON. Por exemplo:

"UserDefinedViews", "C:\Users\yourusername\Desktop\tmp\UserDefinedViews.json"

Esquema para Exibições Definidas pelo Usuário

As visualizações definidas pelo usuário são expostas no UserViews esquema por padrão. Isso é feito para evitar que o nome da exibição entre em conflito com uma entidade real no modelo de dados. Você pode alterar o nome do esquema usado para UserViews definindo o UserViewsSchemaName propriedade.

Trabalhando com Exibições Definidas pelo Usuário

Por exemplo, uma instrução SQL com uma Visualização Definida pelo Usuário chamada UserViews.RCustomers lista apenas clientes em Raleigh:

SELECT * FROM Customers WHERE City = 'Raleigh';

Exemplo de consultar ao driver:

SELECT * FROM UserViews.RCustomers WHERE Status = 'Active';

Resultando na consultar efetiva à fonte:

SELECT * FROM Customers WHERE City = 'Raleigh' AND Status = 'Active';

Esse é um exemplo muito simples de uma consultar a uma exibição definida pelo usuário que é efetivamente uma combinação da consultar de exibição e da definição de exibição. É possível compor essas consultas em padrões muito mais complexos. Todas as operações SQL são permitidas em ambas as consultas e são combinadas quando apropriado.

Configuração SSL

Personalizando a Configuração SSL

Por padrão, o conector tenta negociar SSL/TLS verificando o certificado do servidor em relação ao armazenamento de certificados confiáveis do sistema.

Para especificar outro certificado, consulte o SSLServerCert propriedade para os formatos disponíveis para fazê-lo.

Modelo de Dados

O Jitterbit Connector for Google Ads oferece suporte a dois esquemas distintos.

Modelo de dados do AdWords

Consulte Modelo de dados do Google AdWords.

Google Ads

Consulte Modelo de dados do Google Ads.

Modelo de Dados do AdWords

O Jitterbit Connector for Google Ads modela entidades do Google Ads em exibições relacionais e procedimentos armazenados. As visualizações fornecidas darão a você acesso aos dados do relatório do Google AdWords usando v201809 da API de relatórios do Google AdWords.

Visualizações

Visualizações são tabelas que não podem ser modificadas. Normalmente, os dados que são somente leitura e não podem ser atualizados são mostrados como exibições. Além disso, as limitações e os requisitos da API estão documentados nesta seção.

Procedimentos Armazenados

NOTE: Procedimentos armazenados não são suportados atualmente. Veja a nota para detalhes.

Procedimentos armazenados são interfaces semelhantes a funções para a fonte de dados. Eles podem ser usados para pesquisar, atualizar e modificar informações na fonte de dados.

Visualizações

As exibições são compostas por colunas e pseudocolunas. As exibições são semelhantes às tabelas na forma como os dados são representados; no entanto, as exibições não oferecem suporte a atualizações. Entidades que são representadas como exibições são normalmente entidades somente leitura. Frequentemente, um procedimento armazenado* está disponível para atualizar os dados se tal funcionalidade for aplicável à fonte de dados.

As consultas podem ser executadas em uma exibição como se fosse uma tabela normal, e os dados retornados são semelhantes nesse aspecto. Para saber mais sobre tabelas e procedimentos armazenados, navegue até as entradas correspondentes neste documento de ajuda.

Conector Jitterbit para Visualizações de Google Ads

Desempenho da Conta

O relatório Desempenho da conta inclui todas as estatísticas agregadas por padrão no nível da conta, uma linha por conta.

Informações Específicas da Tabela

Selecione

O Google AdWords não permite que todas as colunas sejam selecionadas em uma única consultar, pois alguns dados entrarão em conflito se forem selecionados juntos. Portanto, ao emitir uma consultar que selecione todas as colunas, apenas as métricas, segmentos e atributos padrão serão retornados. Em geral, esses padrões são os mesmos campos expostos por meio do console do AdWords.

Para usar os campos não padrão, selecione-os explicitamente em sua consultar.

Os filtros também podem ser usados na cláusula WHERE. Os operadores suportados são os operadores =, !=, >, >=, <, <=, LIKE, NOT LIKE, IN e NOT IN. Todos os filtros devem ser unidos pela palavra-chave AND, pois OR não é compatível com a API do AdWords.

Colunas

Pseudo-colunas

Os campos de pseudocoluna são usados na cláusula WHERE das instruções SELECT e oferecem um controle mais granular sobre as tuplas que são retornadas da fonte de dados.

AdCustomizersFeedItem

O relatório Item de feed de personalizadores de anúncios fornece estatísticas para itens de feed usados em Personalizadores de anúncios. As estatísticas são agregadas no nível do item de feed, uma linha por item de feed.

Informações Específicas da Tabela

Selecione

O Google AdWords não permite que todas as colunas sejam selecionadas em uma única consultar, pois alguns dados entrarão em conflito se forem selecionados juntos. Portanto, ao emitir uma consultar que selecione todas as colunas, apenas as métricas, segmentos e atributos padrão serão retornados. Em geral, esses padrões são os mesmos campos expostos por meio do console do AdWords.

Para usar os campos não padrão, selecione-os explicitamente em sua consultar.

Os filtros também podem ser usados na cláusula WHERE. Os operadores suportados são os operadores =, !=, >, >=, <, <=, LIKE, NOT LIKE, IN e NOT IN. Todos os filtros devem ser unidos pela palavra-chave AND, pois OR não é compatível com a API do AdWords.

Colunas

Pseudo-colunas

Os campos de pseudocoluna são usados na cláusula WHERE das instruções SELECT e oferecem um controle mais granular sobre as tuplas que são retornadas da fonte de dados.

AdGroupBidLandscape

Representa dados sobre um bidlandscape para um grupo de anúncios.

Colunas

Desempenho do Grupo de Anúncios

O Relatório de desempenho do grupo de anúncios inclui todas as estatísticas agregadas por padrão no nível do grupo de anúncios, uma linha por grupo de anúncios.

Informações Específicas da Tabela

Selecione

O Google AdWords não permite que todas as colunas sejam selecionadas em uma única consultar, pois alguns dados entrarão em conflito se forem selecionados juntos. Portanto, ao emitir uma consultar que selecione todas as colunas, apenas as métricas, segmentos e atributos padrão serão retornados. Em geral, esses padrões são os mesmos campos expostos por meio do console do AdWords.

Para usar os campos não padrão, selecione-os explicitamente em sua consultar. Por exemplo, a consultar a seguir usa o dispositivo em vez do segmento de data padrão para consultar os dados de desempenho do grupo de anúncios:

SELECT AdGroupId, AdGroupName, CampaignName, Device, Clicks, ConversionRate, Impressions FROM AdGroupPerformance

Os filtros também podem ser usados na cláusula WHERE. Os operadores suportados são os operadores =, !=, >, >=, <, <=, LIKE, NOT LIKE, IN e NOT IN. Todos os filtros devem ser unidos pela palavra-chave AND, pois OR não é compatível com a API do AdWords. Todos os filtros devem ser unidos pela palavra-chave AND, pois OR não é compatível com a API do AdWords. Por exemplo, a consultar a seguir retornará apenas grupos de anúncios em campanhas habilitadas com uma taxa de conversão maior que 0:

SELECT AdGroupId, AdGroupName, CampaignName, Device, Clicks, ConversionRate, Impressions FROM AdGroupPerformance WHERE CampaignStatus='ENABLED' AND ConversionRate > 0

Colunas

Pseudo-colunas

Os campos de pseudocoluna são usados na cláusula WHERE das instruções SELECT e oferecem um controle mais granular sobre as tuplas que são retornadas da fonte de dados.

Grupos de Anúncios

Serviço para acessar detalhes sobre quaisquer grupos de anúncios.

Informações Específicas da Tabela

Selecione

Há duas maneiras de consultar AdGroups.

• A consultar a seguir retorna o grupo de anúncios especificado.

  SELECT * FROM [Grupos de anúncios] WHERE Id=123456789
  

• A consultar a seguir retorna todos os grupos de anúncios.

  SELECT * FROM [AdGroups]
  

Colunas

Desempenho do Anúncio

O relatório de desempenho do anúncio inclui todas as estatísticas agregadas no nível do anúncio, uma linha por anúncio.

Informações Específicas da Tabela

Selecione

O Google AdWords não permite que todas as colunas sejam selecionadas em uma única consultar, pois alguns dados entrarão em conflito se forem selecionados juntos. Portanto, ao emitir uma consultar que selecione todas as colunas, apenas as métricas, segmentos e atributos padrão serão retornados. Em geral, esses padrões são os mesmos campos expostos por meio do console do AdWords.

Para usar os campos não padrão, selecione-os explicitamente em sua consultar. Por exemplo, a consultar a seguir usa ClickType em vez do segmento de data padrão para consultar os dados de desempenho do anúncio:

SELECT AdType, Headline, CampaignName, ClickType, Clicks, ConversionRate, Impressions FROM AdPerformance

Os filtros também podem ser usados na cláusula WHERE. Os operadores suportados são os operadores =, !=, >, >=, <, <=, LIKE, NOT LIKE, IN e NOT IN. Todos os filtros devem ser unidos pela palavra-chave AND, pois OR não é compatível com a API do AdWords. Todos os filtros devem ser unidos pela palavra-chave AND, pois OR não é compatível com a API do AdWords. Por exemplo, esta consultar retornará apenas anúncios ativados com uma taxa de conversão maior que 0:

SELECT AdType, Headline, CampaignName, Device, Clicks, ConversionRate, Impressions FROM AdPerformance WHERE Status='ENABLED' AND ConversionRate > 0

Colunas

Pseudo-colunas

Os campos de pseudocoluna são usados na cláusula WHERE das instruções SELECT e oferecem um controle mais granular sobre as tuplas que são retornadas da fonte de dados.

Faixa Etáriadesempenho

O relatório de desempenho por faixa etária inclui todas as estatísticas da rede de exibição agregadas por faixa etária. Ele também inclui desempenho de público automático.

Informações Específicas da Tabela

Selecione

O Google AdWords não permite que todas as colunas sejam selecionadas em uma única consultar, pois alguns dados entrarão em conflito se forem selecionados juntos. Portanto, ao emitir uma consultar que selecione todas as colunas, apenas as métricas, segmentos e atributos padrão serão retornados. Em geral, esses padrões são os mesmos campos expostos por meio do console do AdWords.

Para usar os campos não padrão, selecione-os explicitamente em sua consultar.

Os filtros também podem ser usados na cláusula WHERE. Os operadores suportados são os operadores =, !=, >, >=, <, <=, LIKE, NOT LIKE, IN e NOT IN. Todos os filtros devem ser unidos pela palavra-chave AND, pois OR não é compatível com a API do AdWords.

Colunas

Pseudo-colunas

Os campos de pseudocoluna são usados na cláusula WHERE das instruções SELECT e oferecem um controle mais granular sobre as tuplas que são retornadas da fonte de dados.

AudiênciaDesempenho

O relatório de desempenho do público inclui dados de desempenho de interesses e listas de remarketing para anúncios gráficos e listas de remarketing para anúncios de pesquisa (RLSA), agregados no nível do público - uma linha por público.

Informações Específicas da Tabela

Selecione

O Google AdWords não permite que todas as colunas sejam selecionadas em uma única consultar, pois alguns dados entrarão em conflito se forem selecionados juntos. Portanto, ao emitir uma consultar que selecione todas as colunas, apenas as métricas, segmentos e atributos padrão serão retornados. Em geral, esses padrões são os mesmos campos expostos por meio do console do AdWords.

Para usar os campos não padrão, selecione-os explicitamente em sua consultar.

Os filtros também podem ser usados na cláusula WHERE. Os operadores suportados são os operadores =, !=, >, >=, <, <=, LIKE, NOT LIKE, IN e NOT IN. Todos os filtros devem ser unidos pela palavra-chave AND, pois OR não é compatível com a API do AdWords.

Colunas

Pseudo-colunas

Os campos de pseudocoluna são usados na cláusula WHERE das instruções SELECT e oferecem um controle mais granular sobre as tuplas que são retornadas da fonte de dados.

Desempenho de Posicionamentos Automáticos

O relatório Desempenho de canais automáticos inclui todas as estatísticas agregadas no nível do canal, uma linha por canal.

Informações Específicas da Tabela

Selecione

O Google AdWords não permite que todas as colunas sejam selecionadas em uma única consultar, pois alguns dados entrarão em conflito se forem selecionados juntos. Portanto, ao emitir uma consultar que selecione todas as colunas, apenas as métricas, segmentos e atributos padrão serão retornados. Em geral, esses padrões são os mesmos campos expostos por meio do console do AdWords.

Para usar os campos não padrão, selecione-os explicitamente em sua consultar.

Os filtros também podem ser usados na cláusula WHERE. Os operadores suportados são os operadores =, !=, >, >=, <, <=, LIKE, NOT LIKE, IN e NOT IN. Todos os filtros devem ser unidos pela palavra-chave AND, pois OR não é compatível com a API do AdWords.

Colunas

Pseudo-colunas

Os campos de pseudocoluna são usados na cláusula WHERE das instruções SELECT e oferecem um controle mais granular sobre as tuplas que são retornadas da fonte de dados.

LanceMetaDesempenho

O Relatório de desempenho da meta de lances inclui estatísticas para suas estratégias de lances.

Informações Específicas da Tabela

Selecione

O Google AdWords não permite que todas as colunas sejam selecionadas em uma única consultar, pois alguns dados entrarão em conflito se forem selecionados juntos. Portanto, ao emitir uma consultar que selecione todas as colunas, apenas as métricas, segmentos e atributos padrão serão retornados. Em geral, esses padrões são os mesmos campos expostos por meio do console do AdWords.

Para usar os campos não padrão, selecione-os explicitamente em sua consultar.

Os filtros também podem ser usados na cláusula WHERE. Os operadores suportados são os operadores =, !=, >, >=, <, <=, LIKE, NOT LIKE, IN e NOT IN. Todos os filtros devem ser unidos pela palavra-chave AND, pois OR não é compatível com a API do AdWords.

Colunas

Pseudo-colunas

Os campos de pseudocoluna são usados na cláusula WHERE das instruções SELECT e oferecem um controle mais granular sobre as tuplas que são retornadas da fonte de dados.

OrçamentoDesempenho

O relatório de desempenho do orçamento inclui todas as estatísticas agregadas por padrão no nível do orçamento, uma linha por orçamento.

Informações Específicas da Tabela

Selecione

O Google AdWords não permite que todas as colunas sejam selecionadas em uma única consultar, pois alguns dados entrarão em conflito se forem selecionados juntos. Portanto, ao emitir uma consultar que selecione todas as colunas, apenas as métricas, segmentos e atributos padrão serão retornados. Em geral, esses padrões são os mesmos campos expostos por meio do console do AdWords.

Para usar os campos não padrão, selecione-os explicitamente em sua consultar.

Os filtros também podem ser usados na cláusula WHERE. Os operadores suportados são os operadores =, !=, >, >=, <, <=, LIKE, NOT LIKE, IN e NOT IN. Todos os filtros devem ser unidos pela palavra-chave AND, pois OR não é compatível com a API do AdWords.

Colunas