Exportar dados do Google Analytics

Você está vendo a documentação do Apigee Edge.
Consulte a documentação do Apigee X.

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

Para configurar permissões para agentes de serviço atribuídos, como preparação para as alterações descritas acima, siga as etapas abaixo.

  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 do IAM no Console do Google Cloud.
  3. Selecione seu projeto do Google Cloud.
  4. Clique em Add na parte superior do painel IAM.
  5. No campo Novos 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 do Apigee Analytics

O Apigee Analytics coleta e analisa um amplo espectro de dados que fluem por suas 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 de 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 integradas ao Edge e todos os dados de análise personalizados que você adiciona. 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 armazenamento 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 armazenamento de dados, você faz o upload das credenciais do repositório de dados no armazenamento de credenciais do Edge para armazená-las com segurança. O mecanismo de exportação usa essas credenciais para gravar dados no repositório de dados.

  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 será concluída.

  5. Quando a exportação for concluída, acesse os dados exportados no 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ê deve:

  • 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. Seu 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 armazenamento de dados do Edge que define a conexão com seu repositório de dados, você passa essa chave para 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 proprietária 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 contas 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 seu projeto do Google Cloud Platform. Consulte Como ativar APIs para mais instruções. A Apigee usa a API BigQuery para aproveitar os recursos de exportação do BigQuery 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 armazenamento de dados). Se o 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 do BigQuery e do Cloud Resource Manager estão ativadas no seu projeto do Google Cloud Platform. Consulte Como ativar APIs para mais instruções. A Apigee usa a API Cloud Resource Manager para verificar permissões antes de cada exportação.
  • Verifique se a API BigQuery está ativada no seu projeto do Google Cloud Platform. Consulte as instruções em Como ativar e desativar APIs.
  • 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 armazenamento 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 Vault de credenciais do Edge

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 armazenamento de dados usando a IU do Edge, conforme descrito abaixo, o Edge cria automaticamente o consumidor usado para acessar as credenciais.

Testar uma configuração de armazenamento de dados

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

Como alternativa, teste a configuração do armazenamento de dados antes de criá-la. 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 armazenamento 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 a configuração novamente. Você só cria o armazenamento de dados após a conclusão dos testes.

Para ativar o recurso de teste, você precisa:

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

Criar um armazenamento de dados

Para criar um armazenamento de dados na IU:

  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 armazenamento de dados.

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

  3. Selecione o botão + Adicionar armazenamento de dados. Você precisará selecionar o tipo de armazenamento de dados:

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

    • Google Cloud Storage
    • Google BigQuery

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

  5. Insira o Nome do armazenamento de dados.

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

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

    • Se você já tiver enviado as credenciais, selecione-as na lista suspensa. Selecione as credenciais apropriadas para o tipo de repositório de dados.

    • Se você estiver adicionando novas credenciais ao armazenamento de dados, selecione Adicionar nova. Na caixa de diálogo, digite:

      1. O Nome das credenciais.
      2. O conteúdo de credenciais é a chave de conta de serviço JSON específica para 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 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 dados de análise. O bucket precisa existir antes de você exportar 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 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 armazenamento de dados.

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

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

Modificar um repositório de dados

Para modificar um armazenamento de dados:

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

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

  3. Mova o ponteiro do mouse sobre a coluna Modificado do relatório para modificar. Os ícones editar e excluir são exibidos.

  4. Edite ou exclua o armazenamento de dados.

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

    Se o teste for bem-sucedido, veja 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 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. 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 teste 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 caras da API de exportação de dados, 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 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 ver 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.

Property 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 no dia anterior, pode ser necessário atrasar o horário de início da solicitação de exportação (por exemplo, 00:05:00 AM 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 armazenamento de dados que contém a definição do seu armazenamento de dados. 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"
  }