Configure o Openflow Connector for Amazon Ads¶

Nota

O conector está sujeito aos termos do conector.

Este tópico descreve as etapas para configurar o Openflow Connector for Amazon Ads.

Pré-requisitos¶

Certifique-se de ter revisado Sobre a Openflow Connector for Amazon Ads.
Certifique-se de ter seguido as etapas em Configuração do Openflow - BYOC ou Configuração do Openflow - Implantação do Snowflake - Visão geral da tarefa.

Obtenha as credenciais¶

Como administrador do Amazon Ads, execute as seguintes ações:

Certifique-se de que você tenha acesso a uma conta Amazon Ads.
Adquira o acesso à Amazon Ads API e conclua o processo de integração.
Obtenha o ID e segredo de cliente.
Crie uma concessão de autorização e recupere um token de atualização.
Analise as regiões disponíveis e obtenha um URL base usado para solicitações com base na região em que você está anunciando.
Busque os IDs de perfil para configuração do relatório.

Configure a conta Snowflake¶

Como administrador de conta Snowflake, execute as seguintes tarefas:

Crie uma nova função ou use uma função existente e conceda a Privilégios de banco de dados.
Crie um novo usuário de serviço Snowflake com o tipo SERVICE.
Conceda ao usuário do serviço Snowflake a função que você criou nas etapas anteriores.
Configure com a autenticação de pares de chaves para o usuário do Snowflake SERVICE da etapa 2.
A Snowflake recomenda enfaticamente essa etapa. Configure um gerenciador de segredos compatível com o Openflow, por exemplo, AWS, Azure e Hashicorp, e armazene as chaves públicas e privadas no armazenamento de segredos.

Nota

Se, por algum motivo, você não quiser usar um gerenciador de segredos, será responsável por proteger os arquivos de chave pública e chave privada usados para autenticação de pares de chaves de acordo com as políticas de segurança de sua organização.
1. Depois que o gerenciador de segredos estiver configurado, determine como você se autenticará nele. No AWS, é recomendável que você use a função de instância EC2 associada ao Openflow, pois dessa forma nenhum outro segredo precisa ser mantido.
2. No Openflow, configurar um provedor de parâmetros associado a este Secrets Manager, a partir do menu de configuração no canto superior direito. Navegue até Controller Settings » Parameter Provider e depois buscar seus valores de parâmetro.
3. Nesse momento, todas as credenciais podem ser referenciadas com os caminhos de parâmetros associados e nenhum valor sensível precisa ser mantido no Openflow.
Se qualquer outro usuário Snowflake precisar de acesso aos documentos e tabelas brutos ingeridos pelo conector (por exemplo, para processamento personalizado no Snowflake), conceda a esses usuários a função criada na etapa 1.
Designar um warehouse para o conector usar. Comece com o menor tamanho de warehouse e, em seguida, experimente o tamanho, dependendo do número de tabelas sendo replicadas e da quantidade de dados transferidos. Os números de tabelas grandes normalmente são mais bem dimensionados com warehouses multicluster, em vez de warehouses maiores.

Configuração do conector¶

Como engenheiro de dados, execute as seguintes tarefas para instalar e configurar o conector:

Instalação do conector¶

Navegue até a página Visão geral do Openflow. Na seção Featured connectors, selecione View more connectors.
Na página de conectores do Openflow, localize o conector e selecione Add to runtime.
Na caixa de diálogo Select runtime, selecione seu tempo de execução na lista suspensa Available runtimes.
Selecione Add.

Nota

Antes de instalar o conector, verifique se você criou um banco de dados e um esquema no Snowflake para que o conector armazene os dados ingeridos.
Autentique-se na implementação com as credenciais de sua conta Snowflake e selecione Allow quando solicitado para permitir que o aplicativo de tempo de execução acesse sua conta Snowflake. O processo de instalação do conector leva alguns minutos para ser concluído.
Autentique-se no tempo de execução com as credenciais de sua conta Snowflake.

A tela do Openflow é exibida com o grupo de processos do conector adicionado a ela.

Configuração do conector¶

Clique com o botão direito do mouse no grupo de processos importado e selecione Parameters.
Preencha os valores dos parâmetros necessários conforme descrito em Parâmetros de fluxo.

Parâmetros de fluxo¶

Esta seção descreve os parâmetros de fluxo que podem ser configurados com base nos contextos de parâmetros a seguir:

Parâmetros de origem do Amazon Ads: usados para estabelecer conexão com a API do Amazon Ads.
Parâmetros de destino do Amazon Ads: usados para estabelecer conexão com o Snowflake.
Parâmetros de ingestão do Amazon Ads: usados para definir a configuração dos dados baixados do Amazon Ads.

Parâmetros de origem do Amazon Ads¶

Parâmetro	Descrição
ID do cliente	ID de cliente da conta Amazon Advertising
Segredo do cliente	Segredo de cliente da conta Amazon Advertising
URL base de OAuth	O URL do servidor de autorização que emite o token de acesso Possíveis valores: https://api.amazon.com/auth/o2/token https://api.amazon.co.uk/auth/o2/token https://api.amazon.co.jp/auth/o2/token
Token de atualização	Token de atualização para a Amazon Ads API
Região	Ambiente do qual os dados de publicidade são baixados Possíveis valores: NA EU FE

Parâmetros de destino do Amazon Ads¶

Parâmetro	Descrição	Obrigatório
Banco de dados de destino	O banco de dados onde os dados serão persistidos. Ele já deve existir no Snowflake. O nome diferencia maiúsculas de minúsculas. Para identificadores sem aspas, forneça o nome em maiúsculas.	Sim
Esquema de destino	O esquema onde os dados serão persistidos, que já deve existir no Snowflake. O nome diferencia maiúsculas de minúsculas. Para identificadores sem aspas, forneça o nome em maiúsculas. Veja os exemplos a seguir: `CREATE SCHEMA SCHEMA_NAME` ou `CREATE SCHEMA schema_name`: use `SCHEMA_NAME` `CREATE SCHEMA "schema_name"` ou `CREATE SCHEMA "SCHEMA_NAME"`: use `schema_name` ou `SCHEMA_NAME`, respectivamente	Sim
Identificador de conta Snowflake	Ao utilizar: Session Token Authentication Strategy: deve ficar em branco. KEY_PAIR: nome da conta Snowflake formatado como [nome-da-organização]-[nome-da-conta], onde os dados serão persistentes.	Sim
Estratégia de autenticação Snowflake	Ao utilizar: Implantação do Snowflake Openflow: Use SNOWFLAKE_SESSION_TOKEN. Esse token é gerenciado automaticamente pelo Snowflake. BYOC: use KEY_PAIR como o valor para a estratégia de autenticação.	Sim
Chave privada Snowflake	Ao utilizar: Session Token Authentication Strategy: deve ficar em branco. KEY_PAIR: deve ser a chave privada RSA utilizada para a autenticação. A chave RSA deve ser formatada de acordo com os padrões PKCS8 e têm os cabeçalhos e rodapés PEM padrão. Observe que ou o arquivo de chave privada do Snowflake ou a chave privada do Snowflake deve ser definido.	Não
Arquivo de chave privada Snowflake	Ao utilizar: Estratégia de autenticação de token de sessão: o arquivo de chave privada deve estar em branco. KEY_PAIR: carregue o arquivo que contém a chave privada RSA usada para autenticação no Snowflake, formatado de acordo com os padrões PKCS8 e incluindo cabeçalhos e rodapés PEM padrão. A linha do cabeçalho começa com `-----BEGIN PRIVATE`. Para carregar o arquivo de chave privada, marque a caixa de seleção Reference asset.	Não
Senha de chave privada Snowflake	Ao usar Session Token Authentication Strategy: deve ficar em branco. KEY_PAIR: forneça a senha associada ao arquivo de chave privada do Snowflake.	Não
Função Snowflake	Ao usar Estratégia de autenticação de tokens de sessão: use sua função de tempo de execução. Você pode encontrar sua função de tempo de execução na UI do Openflow, navegando para View Details no seu tempo de execução. Estratégia de autenticação de KEY_PAIR: use uma função válida configurada para o usuário do seu serviço.	Sim
Nome de usuário do Snowflake	Ao usar Session Token Authentication Strategy: deve ficar em branco. KEY_PAIR: forneça o nome de usuário usado para se conectar à instância do Snowflake.	Sim
Warehouse Snowflake	Warehouse Snowflake usado para executar consultas.	Sim

Parâmetros de ingestão do Amazon Ads¶

Parâmetro	Descrição
Nome do relatório	Nome do relatório a ser usado como nome da tabela de destino. O nome deve ser exclusivo no esquema de destino.
Relatório de produto de anúncio	Tipo de produto publicitário que está sendo relatado Possíveis valores: SPONSORED_PRODUCTS SPONSORED_BRANDS SPONSORED_DISPLAY SPONSORED_TELEVISION DEMAND_SIDE_PLATFORM
Colunas do relatório	Conjunto de colunas que estarão presentes no relatório final. A lista de colunas disponíveis depende do tipo de relatório e pode ser encontrada na documentação da API Amazon Ads. Por exemplo, para o tipo de relatório `spCampaigns`, a lista de colunas disponíveis pode ser encontrada na documentação dos produtos patrocinados.
Filtros de relatório	Conjunto de filtros usados para aparar os dados retornados. A lista de filtros disponíveis depende do tipo de relatório e pode ser encontrada na documentação da API Amazon Ads. Por exemplo, para o tipo de relatório `spCampaigns`, a lista de filtros disponíveis pode ser encontrada na documentação dos produtos patrocinados. Os filtros devem estar no formato `columnName=filterValue`, e os valores devem ser separados por vírgula (`,`). Por exemplo, `campaignStatus=ENABLED,PAUSED`.
Agrupar relatórios por	Determina o nível de granularidade e como os dados do relatório serão agregados e apresentados. A lista de colunas agrupadas disponíveis depende do tipo de relatório e pode ser encontrada na documentação daAPI Amazon Ads. Por exemplo, para o tipo de relatório `spCampaigns`, a lista de colunas agrupadas disponíveis pode ser encontrada na documentação dos produtos patrocinados.
Estratégia de ingestão de relatórios	Modo em que os dados são obtidos, instantâneo ou incremental Possíveis valores: `SNAPSHOT` `INCREMENTAL`
Janela de ingestão de relatórios	Especifica o número de dias em que os dados devem ser baixados durante a ingestão incremental. Por exemplo, com uma janela de ingestão de relatório de 30 dias, um carregamento incremental inicia a ingestão 30 dias antes da última data de ingestão bem-sucedida, a menos que essa data calculada seja anterior à data de início geral, caso em que a ingestão começa a partir da data de início geral. Se a estratégia de ingestão `SNAPSHOT` for usada, todos os dados disponíveis, desde a data de início até o presente, serão baixados, eliminando a necessidade de usar uma janela de ingestão de relatório.
ID do perfil do relatório	O ID de perfil associado a uma conta de publicidade em um marketplace específico
Unidade de tempo do relatório	Agregação de datas Possíveis valores: `DAILY`: cada dia é representado por uma linha `SUMMARY`: todo o período de data ingerido é representado como uma linha
Tipo de relatório	A API Amazon Ads oferece suporte a vários tipos de relatório. Por exemplo: sbAds e spCampaigns. Copie o valor de `reportTypeId` da documentação e cole-o no valor do parâmetro.
Data de início do relatório	Data de início a partir da qual a ingestão deve ocorrer. O formato da data é YYYY-MM-DD.
Cronograma do relatório	Agende o horário para o processador criar os relatórios. Por exemplo: `8 h` ou `1 d`. `h` representa horas, e `d` dias.

Nota

A retenção de dados na API do Amazon Ads é um período específico que varia de 60 a 365 dias, dependendo do tipo de relatório, durante o qual os dados históricos de desempenho de publicidade são armazenados e podem ser recuperados. Após esse período, os dados mais antigos podem não estar mais disponíveis.

Execute o fluxo¶

Clique com o botão direito do mouse no plano e selecione Enable all Controller Services.
Clique com o botão direito do mouse no grupo de processos importado e selecione Start.

O conector inicia a ingestão de dados.