# Conexão com o Facebook Ads O Facebook Ads é uma poderosa plataforma de publicidade digital usada por empresas de todos os tamanhos para atingir seu público-alvo e cumprir objetivos variados de marketing. A plataforma permite que os anunciantes criem anúncios personalizados que podem ser exibidos em toda a família de aplicações e serviços do Facebook, incluindo o Facebook e o Messenger. Com seus recursos avançados de segmentação, o Facebook Ads permite que as empresas atinjam dados demográficos, interesses, comportamentos e locais específicos. **Topics** + [Suporte do AWS Glue para o Facebook Ads](facebook-ads-support.md) + [Políticas que contêm as operações de API para criar e usar conexões](facebook-ads-configuring-iam-permissions.md) + [Configuração do Facebook Ads](facebook-ads-configuring.md) + [Configuração de conexões do Facebook Ads](facebook-ads-configuring-connections.md) + [Leitura de entidades do Facebook Ads](facebook-ads-reading-from-entities.md) + [Opções de conexão do Facebook Ads](facebook-ads-connection-options.md) + [Limitações e notas do conector do Facebook Ads](facebook-ads-connector-limitations.md) # Suporte do AWS Glue para o Facebook Ads O AWS Glue oferece suporte ao Facebook Ads da seguinte maneira: **Compatível como fonte?** Sim. Você pode usar trabalhos de ETL do AWS Glue para consultar dados do Facebook Ads. **Compatível como destino?** N.º **Versões da API do Facebook Ads compatíveis** As seguintes versões da API do Facebook Ads são compatíveis: + v17.0 + v18.0 + v19.0 + v20.0 # Políticas que contêm as operações de API para criar e usar conexões O exemplo de política a seguir descreve as permissões necessárias do AWS IAM para criar e usar conexões. Se você estiver criando um novo perfil, crie uma política que contenha o seguinte: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "glue:ListConnectionTypes", "glue:DescribeConnectionType", "glue:RefreshOAuth2Tokens", "glue:ListEntities", "glue:DescribeEntity" ], "Resource": "*" } ] } ``` ------ Se você não quiser usar o método acima, como alternativa use as seguintes políticas do IAM gerenciadas: + [AWSGlueServiceRole](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/service-role/AWSGlueServiceRole) – Concede acesso a recursos que vários processos do AWS Glue exigem para fazer a execução em seu nome. Esses recursos incluem o AWS Glue, Amazon S3, IAM, CloudWatch Logs e Amazon EC2. Se você seguir a convenção de nomenclatura para os recursos especificados nesta política, os processos do AWS Glue terão as permissões necessárias. Esta política geralmente é anexada a funções especificadas durante a definição de crawlers, trabalhos e endpoints de desenvolvimento. + [AWSGlueConsoleFullAccess](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/AWSGlueConsoleFullAccess): concede acesso total aos recursos do AWS Glue quando uma identidade à qual a política está anexada usa o Console de Gerenciamento da AWS. Se você seguir a convenção de nomenclatura para os recursos especificados nesta política, os usuários poderão acessar todos os recursos do console. Esta política geralmente é anexada aos usuários do console do AWS Glue. # Configuração do Facebook Ads Antes de poder usar o AWS Glue para transferir dados do Facebook Ads, você precisa atender aos seguintes requisitos: ## Requisitos mínimos Estes são os requisitos mínimos: + As contas padrão do Facebook são acessadas diretamente pelo Facebook. + A autenticação do usuário é necessária para gerar o token de acesso. + O conector do SDK do Facebook Ads implementará o fluxo do *OAuth para tokens de acesso do usuário*. + Estamos usando o OAuth2.0 para autenticar nossas solicitações de API para o Facebook Ads. Essa autenticação baseada na Web se enquadra na arquitetura autenticação multifator (MFA), que é um superconjunto de 2FA. + O usuário precisa conceder permissões para acessar os endpoints. Para acessar os dados do usuário, a autorização do endpoint é processada por meio de [permissões](https://developers.facebook.com/docs/permissions) e [recursos](https://developers.facebook.com/docs/features-reference). ## Obtenção de credenciais do Outh 2.0 Para obter credenciais de API para que você possa fazer chamadas autenticadas para instâncias, consulte [API REST](https://developers.facebook-ads.com/rest-api/) no Facebook Ads Developer Guide. # Configuração de conexões do Facebook Ads O Facebook Ads é compatível com o tipo de concessão AUTHORIZATION\$1CODE para OAuth2. + Esse tipo de concessão é considerado um OAuth de três pernas, pois conta com o redirecionamento dos usuários para o servidor de autorização de terceiros para autenticar o usuário. É usado ao criar conexões por meio do console do AWS Glue. + Os usuários ainda podem optar por criar sua própria aplicação conectada no Facebook Ads e fornecer os próprios ID e segredo de cliente quando criarem conexões por meio do Console do AWS Glue. Nesse cenário, eles ainda serão redirecionados para o Facebook Ads para fazer login e autorizar o acesso do AWS Glue aos recursos. + Esse tipo de concessão resulta em um token de acesso. Um token de usuário do sistema prestes a expirar é válido por 60 dias a partir de uma data gerada ou atualizada. Para criar continuidade, o desenvolvedor deve atualizar o token de acesso em até 60 dias. Se isso não for feito, o token de acesso será perdido e será exigido que o desenvolvedor obtenha um novo token para recuperar o acesso à API. Consulte [Atualizar token de acesso](https://developers.facebook.com/docs/marketing-api/system-users/install-apps-and-generate-tokens/). + Para obter a documentação pública do Facebook Ads sobre a criação de uma aplicação conectada para o fluxo de código de autorização do OAuth, consulte [Uso do OAuth 2.0 para acessar APIs do Google](https://developers.google.com/identity/protocols/oauth2) no guia Google para desenvolvedores. Para configurar uma conexão com o Facebook Ads: 1. No AWS Glue Glue Studio, crie uma conexão em **Conexões de dados** seguindo estas etapas: 1. Ao selecionar um **Tipo de conexão**, selecione Facebook Ads. 1. Forneça o `INSTANCE_URL` da instância do Facebook Ads à qual você deseja se conectar. 1. Selecione o perfil do AWS IAM que o AWS Glue pode assumir e que tem permissões para as seguintes ações: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "secretsmanager:DescribeSecret", "secretsmanager:GetSecretValue", "secretsmanager:PutSecretValue", "ec2:CreateNetworkInterface", "ec2:DescribeNetworkInterfaces", "ec2:DeleteNetworkInterface" ], "Resource": "*" } ] } ``` ------ 1. Selecione o `secretName` que você deseja usar para essa conexão no AWS Glue para colocar os tokens. 1. Selecione as opções de rede se quiser usar sua rede. 1. Conceda permissão ao perfil do IAM associado ao seu trabalho do AWS Glue para ler `secretName`. # Leitura de entidades do Facebook Ads **Pré-requisito** Um objeto do Facebook Ads do qual você deseja ler. Você precisará do nome do objeto. As tabelas a seguir mostram as entidades compatíveis. **Entidades compatíveis quanto à origem**: | Entidade | Pode ser filtrada | Oferece suporte a limite | Oferece suporte a Ordenar por | Oferece suporte a Selecionar \$1 | Oferece suporte a particionamento | | --- | --- | --- | --- | --- | --- | | Campaign | Sim | Sim | Não | Sim | Sim | | Conjunto de anúncios | Sim | Sim | Não | Sim | Sim | | Ads | Sim | Sim | Não | Sim | Sim | | Anúncio criativo | Não | Sim | Não | Sim | Não | | Insights: conta | Não | Sim | Não | Sim | Não | | Adaccounts | Sim | Sim | Não | Sim | Não | | Insights: anúncio | Sim | Sim | Não | Sim | Sim | | Insights: AdSet | Sim | Sim | Não | Sim | Sim | | Insights: campanha | Sim | Sim | Não | Sim | Sim | **Exemplo:** ``` FacebookAds_read = glueContext.create_dynamic_frame.from_options( connection_type="FacebookAds", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "entityName", "API_VERSION": "v20.0" } ``` ## Detalhes das entidades e dos campos do Facebook Ads Para obter mais informações sobre os detalhes das entidades e dos campos, consulte: + [Conta de anúncios](https://developers.facebook.com/docs/marketing-api/reference/ad-account) + [Campanha](https://developers.facebook.com/docs/marketing-api/reference/ad-campaign-group) + [Conjunto de anúncios](https://developers.facebook.com/docs/marketing-api/reference/ad-campaign) + [Ad](https://developers.facebook.com/docs/marketing-api/reference/adgroup) + [Anúncio criativo](https://developers.facebook.com/docs/marketing-api/reference/ad-creative) + [Conta de anúncios de insight](https://developers.facebook.com/docs/marketing-api/reference/ad-account/insights) + [Anúncios de insights](https://developers.facebook.com/docs/marketing-api/reference/adgroup/insights/) + [Conjuntos de anúncios de insights](https://developers.facebook.com/docs/marketing-api/reference/ad-campaign/insights) + [Campanhas de insights](https://developers.facebook.com/docs/marketing-api/reference/ad-campaign-group/insights) Para obter mais informações, consulte [API de marketing](https://developers.facebook.com/docs/marketing-api/reference/v21.0). **nota** Os tipos de dados Struct e List são convertidos no tipo de dados String na resposta dos conectores. ## Consultas de particionamento É possível fornecer as opções adicionais do Spark `PARTITION_FIELD`, `LOWER_BOUND`, `UPPER_BOUND` e `NUM_PARTITIONS` se quiser utilizar a simultaneidade no Spark. Com esses parâmetros, a consulta original seria dividida em `NUM_PARTITIONS` subconsultas, que poderiam ser executadas pelas tarefas do Spark simultaneamente. + `PARTITION_FIELD`: o nome do campo a ser usado para particionar a consulta. + `LOWER_BOUND`: um valor limite inferior **inclusivo** do campo de partição escolhido. No campo Data e hora, aceitamos o formato de carimbo de data/hora do Spark usado em consultas SQL do Spark. Exemplo de valor válido: ``` "2022-01-01" ``` + `UPPER_BOUND`: um valor limite superior **exclusivo** do campo de partição escolhido. + `NUM_PARTITIONS`: o número de partições. Exemplo: ``` FacebookADs_read = glueContext.create_dynamic_frame.from_options( connection_type="FacebookAds", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "entityName", "API_VERSION": "v20.0", "PARTITION_FIELD": "created_time" "LOWER_BOUND": "2022-01-01" "UPPER_BOUND": "2024-01-02" "NUM_PARTITIONS": "10" } ``` # Opções de conexão do Facebook Ads Estas são as opções de conexão do Facebook Ads: + `ENTITY_NAME`(String): (obrigatório) usado para leitura. O nome do objeto no Facebook Ads. + `API_VERSION`(String): (obrigatório) usado para leitura. Versão da API Rest do Facebook Ads que você deseja usar. Por exemplo: v1. + `SELECTED_FIELDS`(Lista): padrão: vazio(SELECIONE \$1). Usado para leitura. Colunas que deseja selecionar para o objeto. + `FILTER_PREDICATE`(string): padrão: vazio. Usado para leitura. Deve estar no formato Spark SQL. + `QUERY`(String): padrão: vazia. Usado para leitura. Consulta completa do Spark SQL. + `PARTITION_FIELD`(String): usado para leitura. Campo a ser usado para particionar a consulta. + `LOWER_BOUND`(String): usado para leitura. Um valor limite inferior inclusivo do campo de partição escolhido. + `UPPER_BOUND`(String): usado para leitura. Um valor limite superior exclusivo do campo de partição escolhido. + `NUM_PARTITIONS`(Inteiro): padrão: 1. Usado para leitura. Número de partições para leitura. + `TRANSFER_MODE`(String): padrão: SYNC. Usado para leitura assíncrona. # Limitações e notas do conector do Facebook Ads Estas são as limitações ou notas do conector do Facebook Ads: + Como o Facebook Ads é compatível com metadados dinâmicos, todos os campos podem ser consultados. Todos os campos oferecem suporte a filtragem e os registros serão buscados quando os dados estiverem disponíveis. Caso contrário, o Facebook retornará uma resposta de solicitação inválida (400) com uma mensagem de erro adequada. + A contagem de chamadas de uma aplicação é o número de chamadas que um usuário pode fazer durante uma janela contínua de uma hora, 200 multiplicado pelo número de usuários. Para conhecer detalhes sobre o limite de taxa, consulte [Limites de taxa](https://developers.facebook.com/docs/graph-api/overview/rate-limiting/) e [Limites de taxa de casos de uso empresarial](https://developers.facebook.com/docs/graph-api/overview/rate-limiting/#buc-rate-limits).