Exportar dados do Google Analytics

Você está vendo a documentação do Apigee Edge.
Acesse a documentação da Apigee X. informações

Configurar permissões para agentes de serviço atribuídos

Para configurar permissões para agentes de serviço atribuídos, em preparação para as mudanças descritas acima, siga as etapas a seguir.

1. Digite o seguinte comando para encontrar o nome do agente de serviço do Google Cloud:

   curl -X GET \
     "https://api.enterprise.apigee.com/v1/organizations/ORG" \
     -u email:password \
     | jq -r '.properties.property[] | select(.name=="serviceAgent.analytics") | .value'

   em que ORG é sua organização. Isso retorna o nome e o valor do agente de serviço, conforme mostrado abaixo:

   "property" : [
     {
      "name" : "serviceAgent.analytics",
      "value" : "service-9q1ibk@gcp-sa-apigee-uap.iam.gserviceaccount.com"
      },

2. Abra o painel do IAM no console do Google Cloud.
3. Selecione seu projeto do Google Cloud.
4. Clique em Adicionar na parte de cima do painel IAM.
5. No campo Novas principais, insira o agente de serviço value retornado na etapa 1. Por exemplo, o value mostrado na etapa 1 é service-9q1ibk@gcp-sa-apigee-uap.iam.gserviceaccount.com.
6. Clique no botão +Adicionar outro papel e adicione os seguintes papéis:
   • Usuário do BigQuery
   • Administrador do Storage
7. Clique em Salvar.

Dados de análise da Apigee

Formato de dados de exportação

Exporte os dados de análise para um dos seguintes formatos:

• Valores separados por vírgula (CSV)

  O delimitador padrão é um caractere vírgula (,). Os caracteres delimitadores aceitos incluem vírgula (,), barra vertical (|) e tabulação (\t). Configure o valor usando a propriedade csvDelimiter, conforme descrito na Referência de propriedade de solicitação de exportação.

• JSON (delimitado por nova linha)

  Permite que o caractere de nova linha seja usado como um delimitador.

Os dados exportados incluem todas as métricas e dimensões de análise integradas ao Edge, além de todos os dados de análise personalizados que você adicionar. Para ver uma descrição dos dados exportados, consulte as referências de métricas, dimensões e filtros do Analytics.

É possível exportar dados de análise para os seguintes repositórios de dados:

• Google Cloud Storage
• Google BigQuery

Visão geral do processo de exportação

As etapas a seguir resumem o processo usado para exportar os dados de análise:

1. Configure seu repositório de dados (Cloud Storage ou BigQuery) para a exportação de dados. Verifique se o repositório de dados foi configurado corretamente e se a conta de serviço usada para gravar dados nele tem as permissões corretas.

2. Crie um repositório de dados que defina as propriedades do repositório de dados (Cloud Storage ou BigQuery) para onde você exporta seus dados, incluindo as credenciais usadas para acessar o repositório de dados.

   Ao criar um repositório de dados, você faz upload das credenciais do repositório de dados para o Vault de credenciais de borda para armazená-las com segurança. O mecanismo de exportação de dados usa essas credenciais para gravar dados no seu repositório.

3. Use a API de exportação de dados para iniciar a exportação dos dados. A exportação de dados é executada de forma assíncrona em segundo plano.

4. Use a API de exportação de dados para determinar quando a exportação será concluída.

5. Quando a exportação for concluída, acesse os dados exportados no seu repositório de dados.

As seções a seguir descrevem essas etapas em mais detalhes.

Configurar seu repositório de dados

O mecanismo de exportação de dados de análise grava dados no Cloud Storage ou no BigQuery. Para que essa gravação ocorra, você precisa:

• Crie uma conta de serviço do Google Cloud Platform.
• Defina o papel da conta de serviço para que ela possa acessar o Cloud Storage ou o BigQuery.

Criar uma conta de serviço para o Cloud Storage ou o BigQuery

Uma conta de serviço é um tipo de Conta do Google que pertence ao seu aplicativo e não a um usuário individual. Em seguida, o aplicativo usa a conta de serviço para acessar um serviço.

Uma conta de serviço tem uma chave de conta de serviço representada por uma string JSON. Quando você cria o repositório de dados do Edge que define a conexão com seu repositório de dados, passa essa chave a ele. O mecanismo de exportação de dados usa a chave para acessar seu repositório de dados.

A conta de serviço associada à chave precisa ser de um projeto do Google Cloud Platform e ter acesso de gravação ao bucket do Google Cloud Storage. Para criar uma chave de serviço e fazer o download do payload necessário, consulte Como criar e gerenciar chaves de conta de serviço na documentação do Google Cloud Platform.

Por exemplo, quando você fizer o download da chave pela primeira vez, ela será formatada como um objeto JSON:

{ 
  "type": "service_account", 
  "project_id": "myProject", 
  "private_key_id": "12312312", 
  "private_key": "-----BEGIN PRIVATE KEY-----\n...", 
  "client_email": "client_email@developer.gserviceaccount.com", 
  "client_id": "879876769876", 
  "auth_uri": "https://accounts.google.com/organizations/oauth2/auth", 
  "token_uri": "https://oauth2.googleapis.com/token", 
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2", 
  "client_x509_cert_url": "https://www.googleapis.com" 
}

Configurar o Google Cloud Storage

Antes de exportar dados para o Google Cloud Storage:

• Verifique se as APIs do BigQuery e do Cloud Resource Manager estão ativadas no projeto do Google Cloud Platform. Consulte Como ativar APIs para mais instruções. A Apigee usa a API BigQuery para aproveitar os recursos do BigQuery Export ao exportar para o Cloud Storage, e a API Cloud Resource Manager para verificar a permissão antes de cada exportação.

• Verifique se a conta de serviço está atribuída aos seguintes papéis:

  • Usuário de jobs do BigQuery
  • Criador de objetos do Storage
  • Administrador de armazenamento (necessário apenas para testar o armazenamento de dados, conforme descrito em Testar uma configuração de repositório de dados. Se esse papel for muito amplo, adicione a permissão storage.buckets.get a um papel existente.

  Como alternativa, se você quiser modificar um papel atual ou criar um papel personalizado, adicione as seguintes permissões ao papel:

  • bigquery.jobs.create
  • storage.objects.create
  • storage.buckets.get (necessário apenas para testar o armazenamento de dados, conforme descrito em Testar uma configuração de repositório de dados)

Configurar o Google BigQuery

Antes de exportar dados para o Google BigQuery:

• Verifique se as APIs do BigQuery e do Cloud Resource Manager estão ativadas no projeto do Google Cloud Platform. Consulte Como ativar APIs para mais instruções. A Apigee usa a API Cloud Resource Manager para verificar a permissão antes de cada exportação.
• Verifique se a API BigQuery está ativada no seu projeto do Google Cloud Platform. Consulte Como ativar e desativar APIs para instruções.

• Verifique se a conta de serviço está atribuída aos seguintes papéis:

  • Usuário de jobs do BigQuery
  • Editor de dados do BigQuery

  Se você quiser modificar um papel atual ou criar um papel personalizado, adicione as seguintes permissões:

  • bigquery.datasets.create
  • bigquery.datasets.get
  • bigquery.jobs.create
  • bigquery.tables.create
  • bigquery.tables.get
  • bigquery.tables.updateData

Criar um repositório de dados

O armazenamento de dados define a conexão com seu repositório de dados de exportação (Cloud Storage, BigQuery), incluindo as credenciais usadas para acessar o repositório de dados.

Sobre o Edge Credentials Vault

O Edge usa o Vault de credenciais para armazenar com segurança as credenciais usadas para acessar seu repositório de dados de exportação. Para que um serviço possa acessar as credenciais no Edge Credentials Vault, você precisa definir um consumidor de credenciais.

Ao criar um repositório de dados na IU do Edge, conforme descrito abaixo, o Edge cria automaticamente o consumidor usado para acessar as credenciais.

Testar uma configuração de repositório de dados

Quando você cria o armazenamento de dados, o Edge não testa nem valida se as credenciais e a configuração do repositório de dados são válidas. Isso significa que você pode criar o repositório de dados e não detectar erros até executar sua primeira exportação de dados.

Como alternativa, teste a configuração do repositório de dados antes de criá-lo. O teste é útil porque um grande processo de exportação de dados pode levar muito tempo para ser executado. Ao testar suas credenciais e a configuração do repositório de dados antes de começar a fazer o download de grandes quantidades de dados, você pode corrigir rapidamente qualquer problema com suas configurações.

Se o teste for bem-sucedido, crie o armazenamento de dados. Se o teste falhar, corrija os erros e teste novamente a configuração. O armazenamento de dados só é criado após a conclusão dos testes.

Para ativar o recurso de teste, faça o seguinte:

• Verifique se a API Cloud Resource Manager está ativada no seu projeto do Google Cloud Platform. Consulte Como ativar e desativar APIs para instruções.

Criar um repositório de dados

Para criar um repositório de dados na interface:

1. Faça login em https://apigee.com/edge como administrador da organização e selecione sua organização.

   OBSERVAÇÃO: você precisa ser um administrador da organização de Edge para criar um repositório de dados.

2. Selecione Administrador > Armazenamentos de dados de análise na barra de navegação à esquerda. A página Repositórios de dados do Google Analytics é exibida.

3. Selecione o botão + Adicionar Datastore. Você precisa selecionar o tipo de repositório de dados:

   

4. Escolha um tipo de destino de dados de exportação:

   • Google Cloud Storage
   • Google BigQuery

   A página de configuração será exibida:

   

5. Insira o Nome do repositório de dados.

6. Selecione uma credencial usada para acessar o repositório de dados. Uma lista suspensa de credenciais disponíveis é exibida.

   As credenciais são específicas para um tipo de repositório de dados. Consulte Criar uma conta de serviço para o Cloud Storage ou o BigQuery para saber mais.

   • Se você já tiver feito upload das credenciais, selecione-as na lista suspensa. Selecione as credenciais adequadas ao tipo de repositório de dados.

   • Se você estiver adicionando novas credenciais ao repositório de dados, selecione Adicionar nova. Na caixa de diálogo, insira:

     1. O Nome das credenciais.
     2. O Conteúdo de credenciais é a chave da conta de serviço JSON específica do seu repositório de dados, conforme definido em Criar uma conta de serviço para o Cloud Storage ou o BigQuery.
     3. Selecione Criar.

7. Digite as propriedades específicas para o tipo de repositório de dados:

   • Para o Google Cloud Storage:

     Propriedade	Descrição	Obrigatório?
     ID	ID do projeto do Google Cloud Platform. Para criar um projeto do Google Cloud Platform, consulte Como criar e gerenciar projetos na documentação do Google Cloud Platform.	Sim
     Nome do bucket	Nome do bucket no Cloud Storage para o qual você quer exportar os dados de análise. O bucket precisa existir antes da exportação de dados. Para criar um bucket do Cloud Storage, consulte Como criar buckets do Storage na documentação do Google Cloud Platform.	Sim
     Caminho	Diretório para armazenar os dados de análise no bucket do Cloud Storage.	Sim

   • Para o BigQuery:

     Propriedade	Descrição	Obrigatório?
     ID	ID do projeto do Google Cloud Platform. Para criar um projeto do Google Cloud Platform, consulte Como criar e gerenciar projetos na documentação do Google Cloud Platform.	Sim
     Nome do conjunto de dados	Nome do conjunto de dados do BigQuery para o qual você quer exportar dados de análise. Verifique se o conjunto de dados foi criado antes de solicitar a exportação de dados. Para criar um conjunto de dados do BigQuery, consulte Como criar e usar conjuntos de dados na documentação do Google Cloud Platform.	Sim
     Prefixo da tabela	O prefixo dos nomes das tabelas criadas para os dados de análise no conjunto de dados do BigQuery.	Sim

8. Selecione Testar conexão para garantir que as credenciais possam ser usadas para acessar o repositório de dados.

   Se o teste for bem-sucedido, salve o repositório de dados.

   Se o teste falhar, corrija os problemas e tente novamente. Passe o mouse sobre a mensagem de erro na interface para exibir mais informações em uma dica.

9. Quando o teste de conexão for aprovado, salve o armazenamento de dados.

Modificar um repositório de dados

Para modificar um repositório de dados:

1. Faça login em https://apigee.com/edge como administrador da organização e selecione sua organização.

2. Selecione Administrador > Armazenamentos de dados de análise na barra de navegação à esquerda. A página Repositórios de dados do Google Analytics é exibida.

3. Passe o cursor do mouse sobre a coluna Modificado do relatório que será alterado. Os ícones editar e excluir serão exibidos.

4. Edite ou exclua o repositório de dados.

5. Se você editou o repositório de dados, selecione Testar conexão para garantir que as credenciais possam ser usadas para acessar o repositório de dados.

   Se o teste for bem-sucedido, você poderá ver os dados de amostra no seu repositório de dados.

   Se o teste falhar, corrija os problemas e tente novamente.

6. Depois que o teste de conexão for aprovado, atualize o armazenamento de dados.

Exportar dados de análise

Para exportar dados de análise, emita uma solicitação POST para a API /analytics/exports. Transmita as informações a seguir no corpo da solicitação:

• Nome e descrição da solicitação de exportação
• Período de dados exportados (o valor só pode abranger um dia)
• Formato de dados exportados
• Nome do repositório de dados
• Se a monetização está ativada na organização

Veja abaixo exemplos de solicitações de exportação. Para uma descrição completa das propriedades do corpo da solicitação, consulte Referência de propriedade da solicitação de exportação.

A resposta do POST está no formato:

{
    "self": "/organizations/myorg/environments/test/analytics/exports/a7c2f0dd-1b53-4917-9c42-a211b60ce35b",
    "created": "2017-09-28T12:39:35Z",
    "state": "enqueued"
}

Observe que a propriedade state na resposta está definida como enqueued. A solicitação POST funciona de maneira assíncrona. Isso significa que ela continuará sendo executada em segundo plano depois que a solicitação retornar uma resposta. Os valores possíveis para state incluem: enqueued, running, completed, failed.

Use o URL retornado na propriedade self para ver o status da solicitação de exportação de dados, conforme descrito em Como visualizar o status de uma solicitação de exportação de análise. Quando a solicitação é concluída, o valor da propriedade state na resposta é definido como completed. Depois, você poderá acessar os dados de análise no seu repositório de dados.

Exemplo 1: exportar dados para o Cloud Storage

A solicitação a seguir exporta um conjunto completo de dados brutos das últimas 24 horas do ambiente test na organização myorg. O conteúdo é exportado para o Cloud Storage em JSON:

curl -X POST -H "Content-Type:application/json" \
"https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/analytics/exports" \
  -d \
  '{
    "name": "Export raw results to Cloud Storage",
    "description": "Export raw results to Cloud Storage for last 24 hours",
    "dateRange": {
      "start": "2018-06-08", 
      "end": "2018-06-09"
    },
    "outputFormat": "json",
    "datastoreName": "My Cloud Storage data repository"
  }' \
  -u orgAdminEmail:password

Use o URI especificado pela propriedade self para monitorar o status do job, conforme descrito em Como visualizar o status de uma solicitação de exportação do Analytics.

Exemplo 2: exportar dados para o BigQuery

A solicitação a seguir exporta um arquivo CSV delimitado por vírgulas para o BigQuery:

curl -X POST -H "Content-Type:application/json"  \
  "https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/analytics/exports" \
  -d \
  '{
    "name": "Export query results to BigQuery",
    "description": "One-time export to BigQuery",
    "dateRange": {
      "start": "2018-06-08", 
      "end": "2018-06-09"
    },
    "outputFormat": "csv",
    "csvDelimiter": ",", 
    "datastoreName": "My BigQuery data repository"
  }' \
  -u orgAdminEmail:password

Observação: o arquivo CSV exportado cria uma tabela do BigQuery com o seguinte prefixo:

<PREFIX>_<EXPORT_DATE>_api_<UUID>_from_<FROM_DATE>_to_<TO_DATE>

Use o URI especificado pela propriedade self para monitorar o status do job, conforme descrito em Como visualizar o status de uma solicitação de exportação de análise.

Exemplo 3: exportar dados de monetização

Se a monetização estiver ativada em um ambiente na organização, será possível fazer dois tipos de exportações de dados:

• Exportação de dados padrão, conforme mostrado nos dois exemplos anteriores.
• Exportação de dados de monetização para exportar dados específicos da monetização.

Para realizar uma exportação de dados de monetização, especifique "dataset":"mint" no payload da solicitação. A organização e o ambiente precisam aceitar a monetização para definir essa opção. Caso contrário, omita a propriedade dataset do payload:

  '{
    "name": "Export raw results to Cloud Storage",
    "description": "Export raw results to Cloud Storage for last 24 hours",
    "dateRange": {
      "start": "2018-06-08", 
      "end": "2018-06-09"
    },
    "outputFormat": "json",
    "datastoreName": "My Cloud Storage data repository",
    "dataset":"mint"
  }'

Sobre as cotas da API de exportação

Para evitar o uso excessivo de chamadas de API de exportação de dados caras, o Edge aplica uma cota em chamadas para a API /analytics/exports:

• Para organizações e ambientes que não têm monetização ativada, a cota é:

  • 70 chamadas por mês por organização/ambiente.

  Por exemplo, se você tiver dois ambientes na sua organização, prod e test, poderá fazer 70 chamadas de API por mês para cada ambiente.

• Para organizações e ambientes com monetização ativada, a cota é:

  • 70 chamadas por mês para cada organização e ambiente para dados padrão.
  • 70 chamadas por mês para cada organização e ambiente para dados de monetização.

  Por exemplo, se você ativar a monetização na sua organização prod, poderá fazer 70 chamadas de API para dados padrão e 70 chamadas de API para dados de monetização.

Se você exceder a cota de chamada, a API retornará uma resposta HTTP 429.

Como visualizar o status de todas as solicitações de exportação de análise

Para ver o status de todas as solicitações de exportação de análise, emita uma solicitação GET para /analytics/exports.

Por exemplo, a solicitação a seguir retorna o status de todas as solicitações de exportação de análise para o ambiente test na organização myorg:

curl -X GET \
  "https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/analytics/exports" \
  -u email:password

Veja a seguir um exemplo da resposta que lista duas solicitações de exportação, uma enfileirada (criada e na fila) e outra concluída:

[
  {
    "self":
"/v1/organizations/myorg/environments/test/analytics/exports/e8b8db22-fe03-4364-aaf2-6d4f110444ba",
    "name": "Export results To Cloud Storage",
    "description": "One-time export to Google Cloud Storage",
    "userId": "my@email.com",
    "datastoreName": "My Cloud Storage data store",
    "executionTime": "36 seconds",
    "created": "2018-09-28T12:39:35Z",
    "updated": "2018-09-28T12:39:42Z",
    "state": "enqueued"
  },
  {
    "self":
"/v1/organizations/myorg/environments/test/analytics/exports/9870987089fe03-4364-aaf2-6d4f110444ba"
    "name": "Export raw results to BigQuery",
    "description": "One-time export to BigQuery",
    ... 
  }
]

Como visualizar o status de uma solicitação de exportação de análise

Para visualizar o status de uma solicitação de exportação de análise específica, emita uma solicitação GET para /analytics/exports/{exportId}, em que {exportId} é o ID associado à solicitação de exportação de análise.

Por exemplo, a solicitação a seguir retorna o status da solicitação de exportação do Google Analytics com o ID 4d6d94ad-a33b-4572-8dba-8677c9c4bd98.

curl -X GET \
"https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/analytics/exports/4d6d94ad-a33b-4572-8dba-8677c9c4bd98" \
-u email:password

Veja a seguir um exemplo de resposta:

{
  "self":
"/v1/organizations/myorg/environments/test/analytics/exports/4d6d94ad-a33b-4572-8dba-8677c9c4bd98",
  "name": "Export results To Cloud Storage",
  "description": "One-time export to Google Cloud Storage",
  "userId": "my@email.com",
  "datastoreName": "My Cloud Storage data store",
  "executionTime": "36 seconds",
  "created": "2018-09-28T12:39:35Z",
  "updated": "2018-09-28T12:39:42Z",
  "state": "enqueued"
}

Se a exportação do Google Analytics não retornar dados de análise, executionTime será definido como "0 segundos".

Exportar referência da propriedade da solicitação

A tabela a seguir descreve as propriedades que podem ser transmitidas no corpo da solicitação no formato JSON ao exportar dados de análise.

"dateRange": {
    "start": "2018-07-29",
    "end": "2018-07-30"
}

Exemplo:

{
    "name": "Export raw results to Cloud Storage",
    "description": "Export raw results to Cloud Storage for last 24 hours",
    "dateRange": {
      "start": "2018-06-08", 
      "end": "2018-06-09"
    },
    "outputFormat": "json",
    "datastoreName": "My Cloud Storage data repository"
  }