Exportar dados do Google Analytics

Você está visualizando a documentação do Apigee Edge.
Acesse a documentação da Apigee X. info

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

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

  1. Encontre o nome do agente de serviço do Google Cloud digitando o seguinte comando: 
    curl -X GET \
  "https://api.enterprise.apigee.com/v1/organizations/ORG" \
  -u email:password \
  | jq -r '.properties.property[] | select(.name=="serviceAgent.analytics") | .value'

    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 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 Novos participantes, 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 do Apigee Analytics

O Apigee Analytics coleta e analisa uma ampla variedade de dados que fluem em todas as APIs e fornece ferramentas de visualização, incluindo painéis interativos, relatórios personalizados e outras ferramentas que identificam tendências no desempenho do proxy da API. Agora, é possível desbloquear esse conteúdo avançado exportando dados de análise do Apigee Analytics para seu próprio repositório de dados, como o Google Cloud Storage ou o Google BigQuery. Você pode aproveitar os recursos avançados de consulta e machine learning oferecidos pelo Google BigQuery e pelo TensorFlow para realizar sua própria análise de dados. Você também pode combinar os dados de análise exportados com outros dados, como registros da Web, para ter novos insights sobre seus usuários, APIs e aplicativos.

Formato de exportação de dados

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 incorporadas no Edge e quaisquer 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:

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 no repositório de dados 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.

    Ao criar um repositório de dados, você faz o upload das credenciais do repositório de dados para o cofre de credenciais do Edge e as armazena com segurança. O mecanismo de exportação de dados usa essas credenciais para gravar dados no repositório.

  3. Use a API de exportação de dados para iniciar a exportação de 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 é 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 o 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. 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. Ao criar o repositório de dados do Edge que define a conexão com o repositório de dados, você transmite essa chave. O mecanismo de exportação de dados usa a chave para acessar o repositório de dados.

A conta de serviço associada à chave precisa ser proprietária do projeto do Google Cloud Platform e ter acesso de gravação ao bucket do Cloud Storage. Para criar uma chave de serviço e fazer o download do payload necessário, consulte 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 BigQuery e Cloud Resource Manager estão ativadas no seu projeto do Google Cloud Platform. Consulte Como ativar APIs para ver instruções. A Apigee usa a API BigQuery para aproveitar os recursos de exportação do BigQuery na exportação 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 (obrigatório apenas para testar o repositório 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:

Configurar o Google BigQuery

Antes de exportar dados para o Google BigQuery:

  • Verifique se as APIs BigQuery e Cloud Resource Manager estão ativadas no seu projeto do Google Cloud Platform. Consulte Como ativar APIs para ver 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 ver 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.

Sobre o cofre de credenciais do Edge

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

Ao criar um repositório de dados usando a interface 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 repositório 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 armazenamento de dados e não detectar erros antes de executar a 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 processo de exportação de dados grande pode levar muito tempo para ser executado. Ao testar as 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 os problemas com as configurações.

Se o teste for bem-sucedido, crie o repositório de dados. Se o teste falhar, corrija os erros e teste a configuração novamente. Você só cria o repositório de dados depois que os testes forem bem-sucedidos.

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 ver 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 do Edge para criar um repositório de dados.

  2. Selecione Administrador > Datastores do Google Analytics na barra de navegação à esquerda. A página Bancos de dados do Google Analytics é exibida.

  3. Selecione o botão + Adicionar repositório de dados. Você vai precisar selecionar o tipo de armazenamento de dados:

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

    • Google Cloud Storage
    • Google BigQuery

    A página de configuração aparece:

  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 vai aparecer.

    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á fez upload das credenciais, selecione-as na lista suspensa. Selecione as credenciais adequadas para o tipo de repositório de dados.

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

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

  7. Insira as propriedades específicas do tipo de repositório de dados:

    • Para o Google Cloud Storage:
      Propriedade Descrição Obrigatório?
      ID do projeto 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 de armazenamento na documentação do Google Cloud Platform.

      		Sim
      Caminho Diretório em que armazenar os dados de análise no bucket do Cloud Storage. Sim
    • Para o BigQuery:
      Propriedade Descrição Obrigatório?
      ID do projeto 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 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. Mova o mouse sobre a mensagem de erro na interface para mostrar mais informações em uma dica.

  9. Depois que o teste de conexão for aprovado, salve o repositório 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 > Datastores do Google Analytics na barra de navegação à esquerda. A página Bancos de dados do Google Analytics é exibida.

  3. Mova o cursor do mouse sobre a coluna Modificado do relatório a ser modificado. Um ícone de editar e excluir aparece.

  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á conferir os dados de amostra no 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 repositório 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. Em seguida, você pode 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 de 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 do Analytics.

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 impõe 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 conferir 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 conferir 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.

Propriedade Descrição Obrigatório?
description Descrição da solicitação de exportação. Não
name Nome da solicitação de exportação. Sim
dateRange

Especifique as datas start e end dos dados a serem exportados, no formato yyyy-mm-dd. Por exemplo:

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

O valor dateRange só pode abranger um dia. O período começa às 00:00:00 UTC na data start e termina às 00:00:00 UTC na data end.

OBSERVAÇÃO: para garantir que todos os dados sejam capturados do dia anterior, talvez seja necessário atrasar o horário de início da solicitação de exportação (por exemplo, às 5h UTC).

Sim
outputFormat Especifique como json ou csv. Sim
csvDelimiter

Delimitador usado no arquivo de saída CSV, se outputFormat estiver definido como csv. O padrão é o caractere , (vírgula). Os caracteres delimitadores aceitos incluem vírgula (,), barra vertical (|) e tabulação (\t).

 Não
datastoreName O nome do repositório de dados que contém a definição dele. Sim

Por 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"
  }