Compartilhar via


Copiar dados do Google Ads usando o Azure Data Factory ou o Synapse Analytics

APLICA-SE A: Azure Data Factory Azure Synapse Analytics

Dica

Experimente o Data Factory no Microsoft Fabric, uma solução de análise tudo-em-um para empresas. O Microsoft Fabric abrange desde movimentação de dados até ciência de dados, análise em tempo real, business intelligence e relatórios. Saiba como iniciar uma avaliação gratuita!

Este artigo descreve como usar a atividade de cópia em um pipeline do Azure Data Factory ou do Azure Synapse Analytics para copiar dados do Google Ads. Ele amplia o artigo Visão geral da atividade de cópia que apresenta uma visão geral da atividade de cópia.

Importante

Atualize sua versão do driver do Google Ads antes de 18 de fevereiro de 2024. Caso contrário, a conexão começará a falhar com um erro devido à substituição do driver herdado.

Funcionalidades com suporte

Esse conector do Google Ads é compatível com os seguintes recursos:

Funcionalidades com suporte IR
Atividade de cópia (origem/-) ① ②
Atividade de pesquisa ① ②

① Runtime de integração do Azure ② Runtime de integração auto-hospedada

Para obter uma lista de armazenamentos de dados com suporte como origens e coletores, confira a tabela Armazenamentos de dados com suporte.

O serviço fornece um driver interno para habilitar a conectividade, portanto, não é necessário instalar manualmente qualquer driver usando esse conector.

Introdução

Para executar a atividade de Cópia com um pipeline, será possível usar as ferramentas ou os SDKs abaixo:

Criar um serviço vinculado ao Google Ads com a interface do usuário

Siga as etapas abaixo para criar um serviço vinculado ao Google Ads na interface do usuário do portal do Azure.

  1. Navegue até a guia Gerenciar no workspace do Azure Data Factory ou do Synapse, selecione Serviços Vinculados e clique em Novo:

  2. Pesquise Google Ads e selecione o conector do Google Ads.

    Captura de tela do conector do Google Ads.

  3. Configure os detalhes do serviço, teste a conexão e crie o novo serviço vinculado.

    Captura de tela da configuração do serviço vinculado ao Google Ads.

Detalhes da configuração do conector

As seções a seguir fornecem detalhes sobre as propriedades usadas para definir entidades do Data Factory específicas do conector do Google Ads.

Propriedades do serviço vinculado

As seguintes propriedades são compatíveis com o serviço vinculado do Google Ads:

Propriedade Descrição Obrigatório
type A propriedade type deve ser definida como GoogleAdWords Sim
googleAdsApiVersion A versão da API do Google Ads que você usa quando seleciona a versão de driver recomendada. Você pode consultar este artigo para obter informações sobre a versão da API. Sim
clientCustomerID A ID do cliente da conta do Ads da qual você deseja buscar dados do relatório. Sim
loginCustomerID A ID do cliente da conta do gerenciador do Google Ads por meio da qual você deseja obter dados de relatório de um cliente específico. Não
developerToken O token de desenvolvedor associado à conta do gerenciador que você usa para conceder acesso à API do Ads. Você pode optar por marcar este campo como uma SecureString para armazená-la com segurança ou armazenar a senha no Azure Key Vault e permitir o pull de atividade de cópia a partir daí, ao executar a cópia de dados - Saiba mais de Armazenar credenciais no Key Vault. Sim
authenticationType O mecanismo de autenticação OAuth 2.0 usado para autenticação.
Os valores permitidos são: ServiceAuthentication, UserAuthentication.
ServiceAuthentication só pode ser usado em IR auto-hospedado.
Sim
Para UserAuthentication:
refreshToken O token de atualização obtido do Google para autorizar o acesso ao Ads para UserAuthentication. Você pode optar por marcar este campo como uma SecureString para armazená-la com segurança ou armazenar a senha no Azure Key Vault e permitir o pull de atividade de cópia a partir daí, ao executar a cópia de dados - Saiba mais de Armazenar credenciais no Key Vault. Não
clientId A ID do cliente do aplicativo Google utilizado para adquirir o token de atualização. Você pode optar por marcar este campo como uma SecureString para armazená-la com segurança ou armazenar a senha no Azure Key Vault e permitir o pull de atividade de cópia a partir daí, ao executar a cópia de dados - Saiba mais de Armazenar credenciais no Key Vault. Não
clientSecret O segredo do cliente do aplicativo Google usado para adquirir o token de atualização. Você pode optar por marcar este campo como uma SecureString para armazená-la com segurança ou armazenar a senha no Azure Key Vault e permitir o pull de atividade de cópia a partir daí, ao executar a cópia de dados - Saiba mais de Armazenar credenciais no Key Vault. Não
Para ServiceAuthentication:
Email A ID de e-mail da conta de serviço que é usada para ServiceAuthentication e que só pode ser usada em IR auto-hospedado. Não
privateKey A chave privada do serviço que é usada em ServiceAuthentication para a versão do driver recomendada e que só pode ser usada em IR auto-hospedado. Você pode optar por marcar este campo como uma SecureString para armazená-la com segurança ou armazenar a senha no Azure Key Vault e permitir o pull de atividade de cópia a partir daí, ao executar a cópia de dados - Saiba mais de Armazenar credenciais no Key Vault. Não
Para ServiceAuthentication usando a versão do driver herdado:
Email A ID de e-mail da conta de serviço que é usada para ServiceAuthentication e que só pode ser usada em IR auto-hospedado. Não
keyFilePath O caminho completo para o arquivo de chave .p12 ou .json usado para autenticar o endereço de email da conta de serviço e que só pode ser usado em IR auto-hospedado. Não
trustedCertPath O caminho completo do arquivo .pem que contém certificados de AC confiáveis para verificar o servidor ao se conectar via TLS. Essa propriedade só pode ser definida ao usar o TLS em IR auto-hospedado. O valor padrão é o arquivo de cacerts.pem instalado com o IR. Não
useSystemTrustStore Especifica se deve usar um certificado de autoridade de certificação do repositório de confiança de sistema ou de um arquivo PEM especificado. O valor padrão é false. Não

Exemplo:

{
    "name": "GoogleAdsLinkedService",
    "properties": {
        "type": "GoogleAdWords",
        "typeProperties": {
            "clientCustomerID": "<clientCustomerID>",
            "loginCustomerID": "<loginCustomerID>",
            "developerToken": {
                "type": "SecureString",
                "value": "<developerToken>"
            },
            "authenticationType": "UserAuthentication",
            "refreshToken": {
                "type": "SecureString",
                "value": "<refreshToken>"
            },
            "clientId": {
                "type": "SecureString",
                "value": "<clientId>"
            },
            "clientSecret": {
                "type": "SecureString",
                "value": "<clientSecret>"
            },
            "googleAdsApiVersion": "v14"
        }
    }
}

Propriedades do conjunto de dados

Para obter uma lista completa das seções e propriedades disponíveis para definir os conjuntos de dados, confira o artigo sobre conjuntos de dados. Esta seção fornece uma lista das propriedades compatíveis com o conjunto de dados do Google Ads.

Para copiar dados do Google Ads, defina a propriedade type do conjunto de dados como GoogleAdWordsObject. Há suporte para as seguintes propriedades:

Propriedade Descrição Obrigatório
type A propriedade type do conjunto de dados precisa ser definida como: GoogleAdWordsObject Sim
tableName Nome da tabela. Especifique essa propriedade ao usar a versão do driver herdado. Não (se "query" na fonte da atividade for especificada)

Exemplo

{
    "name": "GoogleAdsDataset",
    "properties": {
        "type": "GoogleAdWordsObject",
        "typeProperties": {},
        "schema": [],
        "linkedServiceName": {
            "referenceName": "<GoogleAds linked service name>",
            "type": "LinkedServiceReference"
        }
    }
}

Propriedades da atividade de cópia

Para obter uma lista completa das seções e propriedades disponíveis para definir atividades, confia o artigo Pipelines. Esta seção fornece uma lista das propriedades compatíveis com a origem do Google Ads.

Para copiar dados do Google Ads, defina o tipo de origem na atividade de cópia como GoogleAdWordsSource. As propriedades a seguir têm suporte na seção source da atividade de cópia:

Propriedade Descrição Obrigatório
type A propriedade type da origem da atividade de cópia deve ser definida como: GoogleAdWordsSource Sim
consulta Utilize a consulta GAQL para ler os dados. Por exemplo: SELECT campaign.id FROM campaign. Não (se "tableName" no conjunto de dados for especificado)

Exemplo:

"activities":[
    {
        "name": "CopyFromGoogleAds",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<GoogleAds input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "GoogleAdWordsSource",
                "query": "SELECT campaign.id FROM campaign"
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

Pesquisar propriedades de atividade

Para saber detalhes sobre as propriedades, verifique Pesquisar atividade.

Atualizar a versão do driver do Google Ads

Para atualizar sua versão do driver do Google Ads, você precisa atualizar seu serviço vinculado e aprender a migrar do SQL para a GAQL (Linguagem de Consulta do Google Ads).

Atualizar a configuração do serviço vinculado

Na página Editar serviço vinculado, selecione Recomendado em Versão do driver e configure o serviço vinculado, consultando as Propriedades do serviço vinculado.

Migrar do SQL para a GAQL

Converta instruções de consulta e nomes de campo ao migrar do SQL para a GAQL.

Instruções de consulta

Se você usar a consulta SQL na origem da atividade de cópia ou na atividade de pesquisa que se refere ao serviço vinculado herdado do Google Ads, será necessário atualizá-la para a consulta GAQL.

Ao contrário do SQL, a consulta em GAQL é composta por seis tipos de cláusulas:

  • SELECT
  • FROM
  • WHERE
  • ORDER BY
  • LIMIT
  • PARAMETERS

Acesse Gramática da linguagem de consulta do Google Ads para obter a introdução da GAQL.

Use a seguinte instrução SQL como um exemplo:

SELECT *|FieldName FROM ResourceName WHERE FieldName Operator Value

Você pode seguir as diretrizes abaixo para converter a instrução SQL na instrução GAQL correspondente:

  1. Se * (asterisco) for usado após a cláusula SELECT, você precisará especificar todos os campos obrigatórios no lugar do asterisco, pois a GAQL não é compatível com SELECT *. Acesse o artigo para ver todos os campos selecionáveis no recurso específico.
  2. Se o nome do campo for usado após a cláusula SELECT, você precisará converter o nome no nome do campo correspondente em GAQL, pois eles têm convenções de nomenclatura diferentes. Por exemplo, o nome do campo campaign_id na instrução da consulta SQL deve ser convertido em campaign.id na GAQL. Consulte Nome do campo para obter mais detalhes sobre a conversão de nome de campo.
  3. O nome do recurso pode ser deixado como está, a menos que seu caso seja inconsistente com o especificado aqui.
  4. A cláusula WHERE deve ser atualizada de acordo com a gramática de GAQL, pois os operadores compatíveis com a GAQL não são consistentes com o SQL, e o nome do campo também deve ser convertido, conforme descrito no segundo ponto.

Aqui estão duas ferramentas muito úteis oferecidas pelo Google que são altamente recomendadas ao criar as instruções de consulta GAQL correspondentes:

Nome do campo

O nome do campo usado no SQL não está alinhado com GAQL. É necessário aprender as regras de conversão de nomes de campo no SQL para nomes de campo na GAQL. A regra de conversão pode ser resumida da seguinte maneira:

  • Se o nome do campo pertencer a um recurso, o sublinhado (_) no SQL será alterado para ponto (.) em GAQL. Para as palavras entre o ponto, a instrução de tipo camelCase usada no SQL será alterada para palavras autônomas com sublinhados adicionados no meio. A primeira cadeia de caracteres do tipo PascalCase no SQL será alterada para o nome do recurso correspondente em GAQL.

  • Se o nome do campo pertencer a segmentos ou métricas, o prefixo segments. ou metrics. deverá ser adicionado na GAQL. Depois, siga a mesma regra descrita no primeiro ponto para converter o nome.

Aqui estão os exemplos concretos da conversão de nome de campo:

Categoria Nomes de campo no SQL Nomes de campo na GAQL
Campos de recurso Campaign_startDate campaign.start_date
Campos de recurso Customer_conversionTrackingSetting_conversionTrackingStatus customer.conversion_tracking_setting.conversion_tracking_status
Segmentos DayOfWeek segments.day_of_week
Métricas VideoViews metrics.video_views

A tabela a seguir mostra as diferenças de recursos entre o Google Ads usando a versão de driver recomendada e herdada.

Versão recomendada do driver Versão herdada do driver
Há suporte para especificar a versão da API do Google Ads. Não há suporte para especificar a versão da API do Google Ads.
ServiceAuthentication dá suporte a duas propriedades:
  • email
  • privateKey
ServiceAuthentication dá suporte a quatro propriedades:
  • email
  • keyFilePath
  • trustedCertPath
  • useSystemTrustStore
Não há suporte para a seleção de uma tabela em um conjunto de dados. Suporte para selecionar uma tabela em um conjunto de dados e consultar a tabela em atividades de cópia.
Suporte à sintaxe GAQL como a linguagem de consulta. Suporte à sintaxe SQL como a linguagem de consulta.
Os nomes das colunas de saída são os mesmos que os nomes de campo definidos no Google Ads. Os nomes das colunas de saída não correspondem aos nomes de campo definidos no Google Ads.
Os mapeamentos a seguir são usados, desde tipos de dados do Google Ads até tipos de dados provisórios usados pelo serviço internamente.

float –> float
int32 –> int
int64 –> long
Os mapeamentos a seguir são usados, desde tipos de dados do Google Ads até tipos de dados provisórios usados pelo serviço internamente.

float –> string
int32 –> string
int64 –> string

Atualizar o conector do Google AdWords para o conector do Google Ads

Para atualizar seu serviço vinculado do Google AdWords para o serviço vinculado mais recente do Google Ads, siga as etapas abaixo:

  1. Selecione Recomendado como a versão do driver para criar um novo serviço vinculado do Google Ads e configurá-lo consultando as Propriedades do serviço vinculado.

  2. Atualize seus pipelines que se referem ao serviço vinculado herdado do Google AdWords. Considerando que o serviço vinculado do Google Ads só é compatível com o uso de consulta para copiar dados, portanto:

    1. Se o pipeline estiver recuperando dados diretamente do relatório do Google AdWords, localize o nome do recurso correspondente do Google Ads na tabela abaixo e use esta ferramenta para criar a consulta.

      Relatório do Google AdWords Recurso do Google Ads
      ACCOUNT_PERFORMANCE_REPORT cliente
      AD_PERFORMANCE_REPORT ad_group_ad
      ADGROUP_PERFORMANCE_REPORT ad_group
      AGE_RANGE_PERFORMANCE_REPORT age_range_view
      AUDIENCE_PERFORMANCE_REPORT campaign_audience_view,ad_group_audience_view
      AUTOMATIC_PLACEMENTS_PERFORMANCE_REPORT group_placement_view
      BID_GOAL_PERFORMANCE_REPORT bidding_strategy
      BUDGET_PERFORMANCE_REPORT campaign_budget
      CALL_METRICS_CALL_DETAILS_REPORT call_view
      CAMPAIGN_AD_SCHEDULE_TARGET_REPORT ad_schedule_view
      CAMPAIGN_CRITERIA_REPORT campaign_criterion
      CAMPAIGN_PERFORMANCE_REPORT campanha
      CAMPAIGN_SHARED_SET_REPORT campaign_shared_set
      CAMPAIGN_LOCATION_TARGET_REPORT location_view
      CLICK_PERFORMANCE_REPORT click_view
      DISPLAY_KEYWORD_PERFORMANCE_REPORT display_keyword_view
      DISPLAY_TOPICS_PERFORMANCE_REPORT topic_view
      GENDER_PERFORMANCE_REPORT gender_view
      GEO_PERFORMANCE_REPORT geographic_view,user_location_view
      KEYWORDLESS_QUERY_REPORT dynamic_search_ads_search_term_view
      KEYWORDS_PERFORMANCE_REPORT keyword_view
      LABEL_REPORT label
      LANDING_PAGE_REPORT landing_page_view,expanded_landing_page_view
      PAID_ORGANIC_QUERY_REPORT paid_organic_search_term_view
      PARENTAL_STATUS_PERFORMANCE_REPORT parental_status_view
      PLACEHOLDER_FEED_ITEM_REPORT feed_item,feed_item_target
      PLACEHOLDER_REPORT feed_placeholder_view
      PLACEMENT_PERFORMANCE_REPORT managed_placement_view
      PRODUCT_PARTITION_REPORT product_group_view
      SEARCH_QUERY_PERFORMANCE_REPORT search_term_view
      SHARED_SET_CRITERIA_REPORT shared_criterion
      SHARED_SET_REPORT shared_set
      SHOPPING_PERFORMANCE_REPORT shopping_performance_view
      TOP_CONTENT_PERFORMANCE_REPORT Não está mais disponível na API do Google Ads.
      URL_PERFORMANCE_REPORT detail_placement_view
      USER_AD_DISTANCE_REPORT distance_view
      VIDEO_PERFORMANCE_REPORT vídeo
    2. Se o pipeline estiver usando a consulta para recuperar dados do Google AdWords, use a ferramenta de Migração de Consulta para converter a AWQL (Linguagem de Consulta do AdWords) na GAQL (Linguagem de Consulta do Google Ads).

  3. Lembre-se de que há certas limitações com este upgrade:

    1. Nem todos os tipos de relatório da AWQL são compatíveis com a GAQL.
    2. Nem todas as consultas AWQL são convertidas de forma clara em consultas GAQL.

Para obter uma lista de armazenamentos de dados com suporte como coletores e fontes da atividade de cópia, confira os armazenamentos de dados com suporte.