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

Artigo
05/13/2024

APLICA-SE A: Azure Data Factory Azure Synapse Analytics

Gorjeta

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

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

Importante

Por favor, 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 à preterição do driver herdado.

Capacidades suportadas

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

Capacidades suportadas	IR
Atividade de cópia (fonte/-)	(1) (2)
Atividade de Pesquisa	(1) (2)

(1) Tempo de execução de integração do Azure (2) Tempo de execução de integração auto-hospedado

Para obter uma lista de armazenamentos de dados suportados como fontes/coletores, consulte a tabela Armazenamentos de dados suportados.

O serviço fornece um driver interno para habilitar a conectividade, portanto, você não precisa instalar manualmente nenhum driver usando esse conector.

Introdução

Para executar a atividade Copiar com um pipeline, você pode usar uma das seguintes ferramentas ou SDKs:

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

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

Navegue até a guia Gerenciar em seu espaço de trabalho do Azure Data Factory ou Synapse e selecione Serviços Vinculados e clique em Novo:
- Fábrica de Dados do Azure
- Azure Synapse
Pesquise por Google Ads e selecione o conector do Google Ads.
Configure os detalhes do serviço, teste a conexão e crie o novo serviço vinculado.

Detalhes de 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:

Property	Descrição	Obrigatório
tipo	A propriedade type deve ser definida como: GoogleAdWords	Sim
googleAdsApiVersion	A versão da API do Google Ads que você usa ao selecionar a versão recomendada do driver. Você pode consultar este artigo para obter informações sobre a versão da API.	Sim
clientCustomerID	O ID de cliente do cliente da conta de anúncios para a qual você deseja buscar dados de relatório.	Sim
loginID do Cliente	O ID de cliente da conta de gestor do Google Ads através da qual pretende obter dados de relatório de um cliente específico.	Não
developerToken	O token de desenvolvedor associado à conta de administrador que você usa para conceder acesso à API de anúncios. Você pode optar por marcar esse campo como um SecureString para armazená-lo com segurança ou armazenar a senha no Cofre de Chaves do Azure e permitir que a atividade de cópia seja extraída de lá ao executar a cópia de dados - saiba mais em Armazenar credenciais no Cofre de Chaves.	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 for UserAuthentication. Você pode optar por marcar esse campo como um SecureString para armazená-lo com segurança ou armazenar a senha no Cofre de Chaves do Azure e permitir que a atividade de cópia seja extraída de lá ao executar a cópia de dados - saiba mais em Armazenar credenciais no Cofre de Chaves.	Não
clientId	O ID do cliente do aplicativo do Google usado para adquirir o token de atualização. Você pode optar por marcar esse campo como um SecureString para armazená-lo com segurança ou armazenar a senha no Cofre de Chaves do Azure e permitir que a atividade de cópia seja extraída de lá ao executar a cópia de dados - saiba mais em Armazenar credenciais no Cofre de Chaves.	Não
clientSecret	O segredo do cliente do aplicativo do Google usado para adquirir o token de atualização. Você pode optar por marcar esse campo como um SecureString para armazená-lo com segurança ou armazenar a senha no Cofre de Chaves do Azure e permitir que a atividade de cópia seja extraída de lá ao executar a cópia de dados - saiba mais em Armazenar credenciais no Cofre de Chaves.	Não
Para ServiceAuthentication:
Correio eletrónico	O ID de email da conta de serviço que é usado para ServiceAuthentication e só pode ser usado em IR auto-hospedado.	Não
chave privada	A chave privada de serviço que é usada para ServiceAuthentication para a versão recomendada do driver e só pode ser usada em IR auto-hospedado. Você pode optar por marcar esse campo como um SecureString para armazená-lo com segurança ou armazenar a senha no Cofre de Chaves do Azure e permitir que a atividade de cópia seja extraída de lá ao executar a cópia de dados - saiba mais em Armazenar credenciais no Cofre de Chaves.	Não
Para ServiceAuthentication* usando a versão* do driver herdado:
Correio eletrónico	O ID de email da conta de serviço que é usado para ServiceAuthentication e só pode ser usado em IR auto-hospedado.	Não
keyFilePath	O caminho completo para o `.p12` arquivo ou `.json` chave que é usado para autenticar o endereço de e-mail da conta de serviço e só pode ser usado no IR auto-hospedado.	Não
trustedCertPath	O caminho completo do arquivo .pem contendo certificados de CA confiáveis para verificar o servidor ao se conectar por TLS. Essa propriedade só pode ser definida ao usar TLS em IR auto-hospedado. O valor padrão é o arquivo cacerts.pem instalado com o IR.	Não
useSystemTrustStore	Especifica se um certificado de autoridade de certificação deve ser usado do armazenamento confiável do sistema ou de um arquivo PEM especificado. O valor predefinido é 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 de seções e propriedades disponíveis para definir conjuntos de dados, consulte o artigo sobre conjuntos de dados. Esta seção fornece uma lista de 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. As seguintes propriedades são suportadas:

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

Exemplo

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

Propriedades da atividade Copy

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

Google Ads como fonte

Para copiar dados do Google Ads, defina o tipo de origem na atividade de cópia como GoogleAdWordsSource. As seguintes propriedades são suportadas na seção de origem da atividade de cópia:

Property	Descrição	Obrigatório
tipo	A propriedade type da fonte de atividade de cópia deve ser definida como: GoogleAdWordsSource	Sim
query	Use a consulta GAQL para ler 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>"
            }
        }
    }
]

Propriedades da atividade de pesquisa

Para saber detalhes sobre as propriedades, verifique Atividade de pesquisa.

Atualizar a versão do driver do Google Ads

Para atualizar a versão do driver do Google Ads, você precisa atualizar o serviço vinculado e saber como migrar do SQL para o Google Ads Query Language (GAQL).

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 de SQL para GAQL

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

Instruções de consulta

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

Em contraste com o SQL, a consulta no GAQL é composta por seis tipos de cláusulas:

SELECT
FROM
WHERE
ORDER BY
LIMIT
PARAMETERS

Aceda a Gramática do idioma de consulta do Google Ads para obter a introdução do GAQL.

Tome a seguinte instrução SQL como exemplo:

SELECT *|FieldName FROM ResourceName WHERE FieldName Operator Value

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

Se * (asterisco) for usado após a SELECT cláusula, então você precisa especificar todos os campos obrigatórios no lugar do asterisco, pois o GAQL não suporta SELECT *. Vá para este artigo para ver todos os campos selecionáveis no recurso específico.
Se o nome do campo for usado após a SELECT cláusula, você precisará converter o nome para o nome do campo correspondente no GAQL, pois eles têm convenções de nomenclatura diferentes. Por exemplo, o nome campaign_id do campo na instrução de consulta SQL deve ser convertido em campaign.id GAQL. Consulte Nome do campo para obter mais detalhes sobre a conversão do nome do campo.
O nome do recurso pode ser deixado como está, a menos que seu caso seja inconsistente com o que é especificado aqui.
WHERE deve ser atualizada de acordo com a gramática GAQL, pois os operadores suportados pelo GAQL não são consistentes com 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 e 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 o GAQL. Você também precisa aprender as regras de conversão de nomes de campo em SQL para nomes de campo em GAQL. A regra de conversão pode ser resumida da seguinte forma:

Se o nome do campo pertencer a um recurso, o sublinhado (_) no SQL será alterado para ponto (.) no GAQL. E para as palavras entre o ponto, a instrução de tipo camelCase usada em 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 no GAQL.
Se o nome do campo pertencer a segmentos ou métricas, o prefixo segments. ou metrics. deve ser adicionado no GAQL, siga a mesma regra descrita no primeiro ponto para converter o nome.

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

Categoria	Nomes de campos em SQL	Nomes de campos no GAQL
Campos de recursos	`Campaign_startDate`	`campaign.start_date`
Campos de recursos	`Customer_conversionTrackingSetting_conversionTrackingStatus`	`customer.conversion_tracking_setting.conversion_tracking_status`
Segmentos	`DayOfWeek`	`segments.day_of_week`
Métricas	`VideoViews`	`metrics.video_views`

Diferenças entre o Google Ads usando a versão recomendada e a versão de driver herdada

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

Versão recomendada do driver	Versão do driver herdado
É compatível com a especificação da versão da API do Google Ads.	Não há suporte para especificar a versão da API do Google Ads.
ServiceAuthentication suporta duas propriedades: •Email • chave privada	ServiceAuthentication suporta quatro propriedades: •Email • keyFilePath • confiávelCertPath • useSystemTrustStore
Não há suporte para a seleção de uma tabela em um conjunto de dados.	Suporte a selecionar uma tabela em um conjunto de dados e consultar a tabela em atividades de cópia.
Suporta sintaxe GAQL como a linguagem de consulta.	Suporte a sintaxe SQL como a linguagem de consulta.
Os nomes das colunas de saída são iguais aos nomes de campos definidos no Google Ads.	Os nomes das colunas de saída não correspondem aos nomes de campos definidos no Google Ads.
Os mapeamentos a seguir são usados de tipos de dados do Google Ads para tipos de dados provisórios usados pelo serviço internamente. flutuar -> flutuar int32 -> int int64 -> longo	Os mapeamentos a seguir são usados de tipos de dados do Google Ads para tipos de dados provisórios usados pelo serviço internamente. float -> corda int32 -> string int64 -> string

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

Atualize seu serviço vinculado do Google AdWords para o serviço vinculado mais recente do Google Ads seguindo as etapas abaixo:

Selecione Recomendado como versão do driver para criar um novo serviço vinculado do Google Ads e configurá-lo fazendo referência às propriedades do serviço vinculado.

Atualize seus pipelines que se referem ao serviço vinculado herdado do Google AdWords. Considerando que o serviço vinculado do Google Ads só suporta o uso de consulta para copiar dados, assim:

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

Relatório do Google AdWords	Recursos 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	etiqueta
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

Se o pipeline estiver usando a consulta para recuperar dados do Google AdWords, use a ferramenta de migração de consultas para traduzir o AWQL (AdWords Query Language) para GAQL (Google Ads Query Language).

Esteja ciente de que há certas limitações com esta atualização:
1. Nem todos os tipos de relatório do AWQL são suportados no GAQL.
2. Nem todas as consultas AWQL são traduzidas corretamente para consultas GAQL.

Para obter uma lista de armazenamentos de dados suportados como fontes e coletores pela atividade de cópia, consulte Armazenamentos de dados suportados.

Partilhar via

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

Capacidades suportadas

Introdução

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

Detalhes de configuração do conector

Propriedades do serviço vinculado

Propriedades do conjunto de dados

Propriedades da atividade Copy

Google Ads como fonte

Propriedades da atividade de pesquisa

Atualizar a versão do driver do Google Ads

Atualizar a configuração do serviço vinculado

Migrar de SQL para GAQL

Instruções de consulta

Nome do campo

Diferenças entre o Google Ads usando a versão recomendada e a versão de driver herdada

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

Comentários

Recursos adicionais

Partilhar via

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

Capacidades suportadas

Introdução

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

Detalhes de configuração do conector

Propriedades do serviço vinculado

Propriedades do conjunto de dados

Propriedades da atividade Copy

Google Ads como fonte

Propriedades da atividade de pesquisa

Atualizar a versão do driver do Google Ads

Atualizar a configuração do serviço vinculado

Migrar de SQL para GAQL

Instruções de consulta

Nome do campo

Diferenças entre o Google Ads usando a versão recomendada e a versão de driver herdada

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

Conteúdos relacionados

Comentários

Recursos adicionais