# Conexão com o Google Analytics 4 O Google Analytics 4 é um serviço de análise que rastreia e relata métricas sobre as interações dos visitantes com aplicações e sites. Essas métricas incluem visualizações de página, usuários ativos e eventos. Se você usa o Google Analytics 4, pode conectar o AWS Glue à sua conta do Google Analytics 4. Você então poderá usar o Google Analytics 4 como fonte de dados em seus trabalhos de ETL. Execute esses trabalhos para transferir dados do Google Analytics 4 para serviços da AWS ou outras aplicações compatíveis. **Topics** + [Suporte do AWS Glue ao Google Analytics 4](googleanalytics-support.md) + [Políticas que contêm as operações de API para criar e usar conexões](googleanalytics-configuring-iam-permissions.md) + [Configuração do Google Analytics 4](googleanalytics-configuring.md) + [Configuração de conexões do Google Analytics 4](googleanalytics-configuring-connections.md) + [Leitura de entidades do Google Analytics 4](googleanalytics-reading-from-entities.md) + [Opções de conexão do Google Analytics 4](googleanalytics-connection-options.md) + [Criar uma conta do Google Analytics 4](googleanalytics-create-account.md) + [Etapas para criar uma aplicação cliente e credenciais do OAuth 2.0](googleanalytics-client-app-oauth-credentials.md) + [Limitações e considerações](googleanalytics-connector-limitations.md) # Suporte do AWS Glue ao Google Analytics 4 O AWS Glue oferece suporte ao Google Analytics 4 da seguinte forma: **Compatível como fonte?** Sim. É possível usar trabalhos de ETL do AWS Glue para consultar dados do Google Analytics 4. **Compatível como destino?** Não. **Versões da API do Google Analytics 4 com suporte** v1 Beta. # 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 da AWS necessárias 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": "*" } ] } ``` ------ É possível usar as seguintes políticas gerenciadas do IAM para permitir acesso: + [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 serem executados 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 Google Analytics 4 Para usar o AWS Glue para transferir dados do Goggle Analytics 4, os seguintes requisitos deverão ser atendidos: ## Requisitos mínimos + Você tem uma conta do Google Analytics com um ou mais fluxos de dados que coletam os dados que deseja transferir. + Você tem uma conta do Google Cloud Platform e um projeto do Google Cloud. + No seu projeto do Google Cloud, você habilitou as seguintes APIs: + API do Google Analytics + API de administração do Google Analytics + API de dados do Google Analytics + No seu projeto do Google Cloud, você configurou uma tela de consentimento de OAuth para usuários externos. Para obter mais informações, consulte [Configurar tela de consentimento do OAuth](https://support.google.com/cloud/answer/10311615#) na Ajuda do console do Google Cloud Platform. + No seu projeto do Google Cloud, você configurou um ID de cliente OAuth 2.0. Para obter mais informações, consulte [Configurar o OAuth 2.0](https://support.google.com/cloud/answer/6158849?hl=en#zippy=). Caso atenda a esses requisitos, você poderá conectar o AWS Glue à sua conta do Google Analytics 4. # Configuração de conexões do Google Analytics 4 Para configurar uma conexão com o Planilhas Google: 1. No AWS Secrets Manager, crie um segredo com os detalhes a seguir. É necessário criar um segredo para cada conexão no AWS Glue. 1. Para o tipo de concessão AuthorizationCode: + Para uma aplicação conectada gerenciada pelo cliente, o segredo deve conter a aplicação conectada Segredo do consumidor com a chave `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET`. 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 Google Analytics 4. 1. Forneça o `INSTANCE_URL` do Google Analytics 4 ao qual deseja se conectar. 1. Selecione o perfil do IAM que o AWS Glue pode assumir e 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`. Tipo de concessão `AUTHORIZATION_CODE`. 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. Ele é usado na criação de conexões por meio do Console do AWS Glue. O Console do AWS Glue redirecionará o usuário para o Google Analytics 4, onde ele deverá fazer login e dar autorização para que as permissões solicitadas pelo AWS Glue acessem a instância do Google Analytics 4. Os usuários ainda podem optar por criar sua própria aplicação conectada no Google Analytics 4 e fornecer seus próprios ID e segredo do cliente ao criar conexões por meio do console do AWS Glue. Nesse cenário, eles ainda serão redirecionados para o Google Analytics 4 para fazer login e autorizar o acesso do AWS Glue aos recursos. Esse tipo de concessão resulta em um token de atualização e um token de acesso. O token de acesso tem vida curta e pode ser atualizado automaticamente sem a interação do usuário usando o token de atualização. Para obter mais informações, consulte [Uso do Auth 2.0 para acessar APIs do Google](https://developers.google.com/identity/protocols/oauth2). # Leitura de entidades do Google Analytics 4 **Pré-requisitos** + Um objeto do Google Analytics 4 do qual você deseja ler. Consulte a tabela de entidades compatíveis abaixo para verificar as entidades disponíveis. **Entidades compatíveis** | Entidade | Pode ser filtrada | Oferece suporte a limite | Oferece suporte a Ordenar por | Oferece suporte a Selecionar \$1 | Oferece suporte a particionamento | | --- | --- | --- | --- | --- | --- | | Relatório em tempo real | Sim | Sim | Sim | Sim | Não | | Relatório principal | Sim | Sim | Sim | Sim | Sim | **Exemplo** ``` googleAnalytics4_read = glueContext.create_dynamic_frame.from_options( connection_type="GoogleAnalytics4", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "entityName", "API_VERSION": "v1beta" } ``` **Detalhes de entidades e campos do Google Analytics 4** | Entidade | Campo | Tipo de dado | Operadores com suporte | | --- | --- | --- | --- | | Relatório principal | Campos dinâmicos | | | | Relatório principal | Campos de dimensão | String | LIKE, = | | Relatório principal | Campos de dimensão | Data | LIKE, = | | Relatório principal | Campos de métricas | String | >, <, >=, <=, = BETWEEN | | Relatório principal | Dimensão personalizada e campos de métricas personalizados | String | NA | | Relatório em tempo real | appVersion | String | LIKE, = | | Relatório em tempo real | audienceId | String | LIKE, = | | Relatório em tempo real | audienceName | String | LIKE, = | | Relatório em tempo real | city | String | LIKE, = | | Relatório em tempo real | cityId | String | LIKE, = | | Relatório em tempo real | country | String | LIKE, = | | Relatório em tempo real | countryId | String | LIKE, = | | Relatório em tempo real | deviceCategory | String | LIKE, = | | Relatório em tempo real | eventName | String | LIKE, = | | Relatório em tempo real | minutesAgo | String | LIKE, = | | Relatório em tempo real | platform | String | LIKE, = | | Relatório em tempo real | streamId | String | LIKE, = | | Relatório em tempo real | streamName | String | LIKE, = | | Relatório em tempo real | unifiedScreenName | String | LIKE, = | | Relatório em tempo real | activeUsers | String | >, <, >=, <=, = BETWEEN | | Relatório em tempo real | conversões | String | >, <, >=, <=, = BETWEEN | | Relatório em tempo real | eventCount | String | >, <, >=, <=, = BETWEEN | | Relatório em tempo real | screenPageViews | String | >, <, >=, <=, = BETWEEN | **Particionamento de consultas** 1. **Particionamento baseado em filtros** Podem ser fornecidas as opções adicionais do Spark `PARTITION_FIELD`, `LOWER_BOUND`, `UPPER_BOUND` e `NUM_PARTITIONS` se você 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. Na data, aceitamos o formato de data do Spark usado em consultas SQL do Spark. Exemplo de valores válidos: `"2024-02-06"`. + `UPPER_BOUND`: um valor limite superior exclusivo do campo de partição escolhido. + `NUM_PARTITIONS`: número de partições. **Exemplo** ``` googleAnalytics4_read = glueContext.create_dynamic_frame.from_options( connection_type="GoogleAnalytics4", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "entityName", "API_VERSION": "v1beta", "PARTITION_FIELD": "date" "LOWER_BOUND": "2022-01-01" "UPPER_BOUND": "2024-01-02" "NUM_PARTITIONS": "10" } ``` 1. **Partição com base em registros** Opções adicionais `NUM_PARTITIONS` do Spark poderão ser fornecidas caso você deseje 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. + `NUM_PARTITIONS`: número de partições. **Exemplo** ``` googleAnalytics4_read = glueContext.create_dynamic_frame.from_options( connection_type="GoogleAnalytics4", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "entityName", "API_VERSION": "v1beta", "NUM_PARTITIONS": "10" } ``` # Opções de conexão do Google Analytics 4 São opções de conexão do Google Analytics 4: + `ENTITY_NAME`(string): (obrigatório) usado para leitura. O nome do seu objeto no Google Analytics 4. + `API_VERSION`(string): (obrigatório) usado para leitura. Versão da API REST do Google Analytics 4 que você deseja usar. + `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. + `INSTANCE_URL`(Integer): usado para leitura. (Opcional) # Criar uma conta do Google Analytics 4 Siga as etapas para criar uma conta do Google Analytics 4: [ https://support.google.com/analytics/answer/9304153?hl=en ](https://support.google.com/analytics/answer/9304153?hl=en) # Etapas para criar uma aplicação cliente e credenciais do OAuth 2.0 Para obter mais informações, consulte a [Documentação da API do Google Analytics 4](https://developers.google.com/analytics/devguides/reporting/data/v1). 1. Crie e configure sua conta fazendo login na sua [conta do Google Analytics](https://analytics.google.com/) com suas credenciais. Em seguida, navegue até **Admin** > **Criar conta**. 1. Crie uma propriedade para a conta que acabou de criar escolhendo **Criar propriedade**. Configure a propriedade com os detalhes necessários. Assim que todos os detalhes forem fornecidos, o ID da propriedade correspondente será gerado. 1. Adicione um fluxo de dados para a propriedade criada escolhendo **Fluxos de dados** > **Adicionar fluxo** > **Web** no menu suspenso. Forneça os detalhes do site, como URL e outros campos obrigatórios. Após todos os detalhes serem fornecidos, o **ID de fluxo** e o **ID de medição** correspondentes serão gerados. 1. Configure o Google Analytics em seu site copiando o ID de medição e adicionando-o à configuração do seu site. 1. Crie um relatório do Google Analytics navegando até **Relatórios** e gerando o relatório necessário. 1. Autorize sua aplicação navegando até [console.cloud.google.com]( https://console.cloud.google.com), pesquise a API de Dados do Google Analytics e, em seguida, habilite a API. 1. Navegue até a página API e serviços e escolha **Credenciais** > **Configurar IDs de clientes do OAuth 2.0**. 1. Forneça o URL de redirecionamento adicionando o URL de redirecionamento do AWS Glue. 1. Copie o ID do cliente e o segredo do cliente, os quais serão necessários posteriormente para criar a conexão. # Limitações e considerações São limitações do conector do Google Analytics 4: + Para a entidade Core Report, somente 9 campos de dimensão e 10 campos métricos são permitidos para enviar em uma solicitação. Se o número permitido de campos for excedido, a solicitação falhará e o conector lançará uma mensagem de erro. + Para a entidade Realtime Report, somente 4 campos de dimensão são permitidos para enviar em uma solicitação. Se o número permitido de campos for excedido, a solicitação falhará e o conector lançará uma mensagem de erro. + O Google Analytics 4 é uma ferramenta gratuita em versão beta. Consequentemente, haverá atualizações regulares sobre novos recursos, aprimoramento de entidades, adição de novos campos e descontinuação de campos existentes. + Os campos do relatório principal são preenchidos dinamicamente. Por isso haverá adição, depreciação e renomeação de campos, e a imposição de novos limites aos campos pode ser feita a qualquer momento. + A data de início padrão é 30 dias e a data de término é ontem (um dia antes da data atual). Essas datas serão substituídas no código da expressão de filtro se o usuário tiver definido o valor OU se o fluxo for incremental. + De acordo com a documentação, a entidade de relatório em tempo real retornará 10.000 registros se o limite não for passado na solicitação, caso contrário, a API retornará no máximo 250.000 linhas por solicitação, não importa quantas você solicite. Para obter mais informações, consulte [Método: properties.runRealtimeReport](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/runRealtimeReport) na documentação do Google Analytics. + A entidade de relatório em tempo real não oferece suporte à partição baseada em registros, pois não oferece suporte à paginação. Além disso, ele não oferece suporte à partição baseada em campo, pois nenhum dos campos atende aos critérios definidos. + Devido à limitação no número de campos que podem ser transmitidos em uma solicitação. Estamos definindo campos de dimensão e métrica padrão dentro dos limites designados. Se "selecionar tudo" for escolhido, somente os dados desses campos predeterminados serão recuperados. + Relatório principal + De acordo com a limitação do SAAS, as solicitações são permitidas em até 9 dimensões e até 10 métricas (ou seja, uma solicitação pode conter no máximo 19 campos (métricas \$1 dimensão). + De acordo com a implementação: se o usuário utilizar SELECT\$1ALL ou selecionar mais de 25 campos, os campos padrão serão passados na solicitação. + Os seguintes campos são considerados campos padrão para o relatório principal: "country", "city", "eventName", "cityId", "browser", "date", "currencyCode", "deviceCategory", "transactionId", active1DayUsers", "active28DayUsers", "active7DayUsers", "activeUsers", "averagePurchaseRevenue", "averageRevenuePerUser", "averageSessionDuration", "engagedSessions", "eventCount", "engagementRate". + Relatório em tempo real + De acordo com a limitação das solicitações do SAAS, são permitidas até 4 dimensões. + Se o usuário passar SELECT\$1ALL ou selecionar mais de 15 campos, os campos padrão serão passados na solicitação. + Os seguintes campos são considerados campos padrãõ para o relatório em tempo real: "country", "deviceCategory", "city", "cityId", "activeUsers", "conversions", "eventCount", "screenPageViews". + Na entidade de relatório principal Core-Report, se a partição no campo date e o filtro em startDate estiverem presentes ao mesmo tempo. Nesse caso, o valor de dateRange será substituído pelo valor do filtro startDate. Mas, já que a partição deve sempre ser a prioridade, descarte o filtro startDate se a partição no campo date já estiver presente. + Como agora o cohortSpecs também faz parte do corpo da solicitação do relatório principal, aprimoramos a entidade atual do relatório principal para incluir suporte ao atributo cohortSpec. No corpo da solicitação de cohortSpecs, quase todos os campos exigem a entrada do usuário. Para resolver isso, definimos valores padrão para esses atributos/campos e fornecemos provisões para que o usuário substitua esses valores, se necessário. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/glue/latest/dg/googleanalytics-connector-limitations.html) + Você também pode passar todos esses filtros juntos de uma só vez ou com outros filtros. + Exemplo 1: filterPredicate: startDate entre "2023-05-09" e "2023-05-10" E startOffset=1 E endOffset=2 E granularity="SEMANAL" + Example 2 filterPredicate: city=“xyz” E startOffset=1 E endOffset=2 E granularity="SEMANAL" + Na solicitação de coorte: + Se "cohortNthMonth" for passado na solicitação, o valor interno de granularity será definido como "MENSAL" + Da mesma forma, se "cohortNthWeek" for passado, o valor de granularity será definido como "SEMANAL" + E, para "cohortNthDay", o valor de granularity será definido como "DIÁRIO". Para obter mais informações, consulte: + [ https://developers.google.com/analytics/devguides/reporting/data/v1/advanced ](https://developers.google.com/analytics/devguides/reporting/data/v1/advanced) + [ https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/CohortSpec ](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/CohortSpec) + Provisão é fornecida para que o usuário substitua os valores padrão de dateRange e granularity. Consulte a tabela acima.