Como exportar dados do Analytics

Esta página se aplica à Apigee e à Apigee híbrida.

Confira a documentação da Apigee Edge.

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.

Quais formatos de dados de exportação são compatíveis?

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 na Apigee 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:

Etapas para exportar os dados de análise

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 do agente de serviço da Apigee 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 os dados serão exportados.
  3. Exporte os dados de análise. A exportação de dados é executada de forma assíncrona em segundo plano.
  4. Visualize o status da solicitação de exportação 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.

Como configurar seu repositório de dados

Configure o Cloud Storage ou o BigQuery para ativar o acesso pela exportação de dados de análise.

Como configurar o Google Cloud Storage

Antes de exportar dados para o Google Cloud Storage, faça o seguinte:

  • Crie um bucket do Google Cloud Storage.

  • Verifique se a API BigQuery está ativada no seu projeto do Google Cloud Platform. A Apigee usa a API BigQuery para aproveitar os recursos de exportação do BigQuery na exportação para o Cloud Storage.

    Consulte Como ativar APIs para ver instruções.

  • Verifique se a conta de serviço do Apigee Service Agent com o endereço de e-mail service-project-number@gcp-sa-apigee.iam.gserviceaccount.com está atribuída aos seguintes papéis:

    • Usuário de jobs do BigQuery
    • Administrador do Storage

    O project-number está listado na página inicial do projeto, conforme mostrado abaixo.

    Consulte Como conceder, alterar e revogar acesso a recursos.

    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.objects.delete
    • storage.objects.list

Como configurar o Google BigQuery

Antes de exportar dados para o Google BigQuery:

  • Certifique-se de ter ativado o BigQuery no projeto do Google Cloud Platform.
  • Verifique se a API BigQuery está ativada no seu projeto do Google Cloud Platform. Consulte Como ativar APIs para instruções.
  • Verifique se a conta de serviço do Apigee Service Agent com o endereço de e-mail service-project-number@gcp-sa-apigee.iam.gserviceaccount.com está atribuída aos seguintes papéis:

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

    O project-number está listado na página inicial do projeto, conforme mostrado abaixo.

    Consulte Como conceder, alterar e revogar acesso a recursos.

    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
  • Crie um conjunto de dados do BigQuery.

Como exportar dados para o BigQuery em uma região individual nos EUA ou na UE

Como os dados de análise dos EUA ou da UE são armazenados em várias regiões dos EUA ou da UE, não é possível exportar os dados diretamente para uma região individual dos EUA ou da UE no BigQuery. Como solução alternativa, é possível exportar os dados para o Google Cloud Storage e transferi-los para o BigQuery da seguinte maneira:

  1. Crie um bucket do Cloud Storage e defina o local como a região individual nos EUA ou na UE que você quer associar aos seus dados no BigQuery.
  2. Crie um armazenamento de dados do Cloud Storage usando o bucket de armazenamento criado na etapa anterior.
  3. Exporte os dados para o Cloud Storage. Veja no Exemplo 1: exportar dados para o Cloud Storage abaixo.
  4. Carregue os dados no BigQuery, conforme descrito nas seções a seguir:

Como gerenciar armazenamentos de dados

O armazenamento de dados define a conexão com seu repositório de dados de exportação (Cloud Storage, BigQuery).

As seções a seguir descrevem como criar e gerenciar seus armazenamentos de dados. Antes de criar um armazenamento de dados, é recomendável testar a configuração do repositório de dados.

Como testar a configuração do repositório de dados

Quando você cria o repositório de dados, a Apigee não testa nem valida a configuração. Isso significa que você pode criar o armazenamento de dados (na próxima etapa) e não detectar erros antes de executar a primeira exportação de dados.

Como um processo de exportação de dados pode levar muito tempo para ser executado, é possível detectar erros mais cedo. Basta testar a configuração do repositório de dados para garantir que ele seja válido e corrigir os erros antes de criar o armazenamento de dados.

Para testar a configuração do repositório de dados, emita uma solicitação POST para a API /organizations/{org}/analytics/datastores:test. Transmita as informações a seguir no corpo da solicitação:

Por exemplo, o exemplo a seguir testa uma configuração de repositório de dados do Cloud Storage:

curl "https://apigee.googleapis.com/v1/organizations/myorg/analytics/datastores:test" \
  -X POST \
  -H "Content-type:application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d \
  '{
    "displayName": "My Cloud Storage datastore",
    "targetType": "gcs",
    "datastoreConfig": {
      "projectId": "my-project",
      "bucketName": "my-bucket",
      "path": "my/analytics/path"
    }
  }'

Veja a seguir um exemplo de resposta caso o teste seja bem-sucedido:

{
  "state": "completed",
}

Veja a seguir um exemplo da resposta se o teste falhar:

{
  "state": "failed",
  "error": "<error message>"
}

Nesse caso, resolva os problemas levantados na mensagem de erro e teste novamente a configuração do repositório de dados. Após um teste bem-sucedido, crie o armazenamento de dados, conforme descrito na próxima seção.

Como criar um armazenamento de dados

Para criar um armazenamento de dados, emita uma solicitação POST para a API /organizations/{org}/analytics/datastores. Transmita as informações a seguir no corpo da solicitação:

Veja abaixo exemplos para cada tipo de armazenamento de dados.

Veja a seguir um exemplo da resposta para um repositório de dados do Cloud Storage:

{
    "self": "/organizations/myorg/analytics/datastores/c7d3b5aq-1c64-3389-9c43-b211b60de35b",
    "displayName": "My Cloud Storage datastore",
    "org": "myorg",
    "targetType": "gcs",
    "createTime": "1535411583949",
    "lastUpdateTime": "1535411634291",
    "datastoreConfig": {
          "projectId": "my-project",
          "bucketName": "my-bucket",
          "path": "my/analytics/path"
    }
}

Use o URL retornado na propriedade self para visualizar os detalhes do armazenamento de dados, conforme descrito em Como visualizar os detalhes de um armazenamento de dados.

Para mais informações, consulte Criar API Data Store.

Exemplo 1: criar um armazenamento de dados do Cloud Storage

A solicitação a seguir cria um armazenamento de dados do Cloud Storage:

curl "https://apigee.googleapis.com/v1/organizations/myorg/analytics/datastores" \
  -X POST \
  -H "Content-type:application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d \
  '{
    "displayName": "My Cloud Storage datastore",
    "targetType": "gcs",
    "datastoreConfig": {
      "projectId": "my-project",
      "bucketName": "my-bucket",
      "path": "my/analytics/path"
    }
  }'

Em que $TOKEN está definido como seu token de acesso OAuth 2.0, conforme descrito em Como receber um token de acesso OAuth 2.0. Para informações sobre as opções de curl usadas neste exemplo, consulte Como usar curl. Para uma descrição das variáveis de ambiente usadas, consulte Como configurar variáveis de ambiente para solicitações da API Apigee.

Exemplo 2: criar um armazenamento de dados do BigQuery

A solicitação a seguir cria um armazenamento de dados do BigQuery:

curl "https://apigee.googleapis.com/v1/organizations/myorg/analytics/datastores" \
  -X POST \
  -H "Content-type:application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d \
  '{
    "displayName": "My BigQuery datastore",
    "targetType": "bigquery",
    "datastoreConfig": {
      "projectId": "my-project",
      "datasetName": "mybigquery",
      "tablePrefix": "bqprefix"
    }
  }'

Em que $TOKEN está definido como seu token de acesso OAuth 2.0, conforme descrito em Como receber um token de acesso OAuth 2.0. Para informações sobre as opções de curl usadas neste exemplo, consulte Como usar curl. Para uma descrição das variáveis de ambiente usadas, consulte Como configurar variáveis de ambiente para solicitações da API Apigee.

Como visualizar todos os armazenamentos de dados

Para visualizar todos os armazenamentos de dados de sua organização, emita uma solicitação GET para a API /organizations/{org}/analytics/datastores.

Exemplo:

curl "https://apigee.googleapis.com/v1/organizations/myorg/analytics/datastores" \
  -X GET \
  -H "Authorization: Bearer $TOKEN"

Em que $TOKEN está definido como seu token de acesso OAuth 2.0, conforme descrito em Como receber um token de acesso OAuth 2.0. Para informações sobre as opções de curl usadas neste exemplo, consulte Como usar curl. Para uma descrição das variáveis de ambiente usadas, consulte Como definir variáveis de ambiente para solicitações de API da Apigee.

Veja a seguir um exemplo de resposta:

{
  "datastores": [
  {
    "self": "/organizations/myorg/analytics/datastores/c7d3b5aq-1c64-3389-9c43-b211b60de35b",
    "displayName": "My Cloud Storage datastore",
    "org": "myorg",
    "targetType": "gcs",
    "createTime": "1535411583949",
    "lastUpdateTime": "1535411634291",
    "datastoreConfig": {
          "projectId": "my-project",
          "bucketName": "my-bucket",
          "path": "my/analytics/path"
    }
  },
  {
    "self": "/organizations/myorg/analytics/datastores/g8c3f0mk-1f78-8837-9c67-k222b60ce30b",
    "displayName": "My BigQuery datastore",
    "org": "myorg",
    "targetType": "bigquery",
    "createTime": "1535411583949",
    "lastUpdateTime": "1535411634291",
    "datastoreConfig": {
      "projectId": "my-project",
      "datasetName": "mybigquery",
      "tablePrefix": "bqprefix"
    }
  }
  ]
}

Para mais informações, consulte a API List Data Stores.

Como visualizar os detalhes de um armazenamento de dados

Para ver os detalhes de um armazenamento de dados, emita uma solicitação GET para a API /organizations/{org}/analytics/datastores/{datastore}.

Exemplo:

curl "https://apigee.googleapis.com/v1/organizations/myorg/analytics/datastores/c7d3b5aq-1c64-3389-9c43-b211b60de35b" \
  -X GET \
  -H "Authorization: Bearer $TOKEN"

Em que $TOKEN está definido como seu token de acesso OAuth 2.0, conforme descrito em Como receber um token de acesso OAuth 2.0. Para informações sobre as opções de curl usadas neste exemplo, consulte Como usar curl. Para uma descrição das variáveis de ambiente usadas, consulte Como configurar variáveis de ambiente para solicitações da API Apigee.

Veja a seguir um exemplo da resposta para um armazenamento de dados do Cloud Storage:

{
    "self": "/organizations/myorg/analytics/datastores/c7d3b5aq-1c64-3389-9c43-b211b60de35b",
    "displayName": "My Cloud Storage datastore",
    "org": "myorg",
    "targetType": "gcs",
    "createTime": "1535411583949",
    "lastUpdateTime": "1535411634291",
    "datastoreConfig": {
          "projectId": "my-project",
          "bucketName": "my-bucket",
          "path": "my/analytics/path"
    }
}

Para mais informações, consulte Receber API Data Store.

Como modificar um armazenamento de dados

Para modificar um armazenamento de dados, emita uma solicitação PUT para a API /organizations/{org}/analytics/datastores/{datastore}. Transmita todas ou um subconjunto das seguintes informações no corpo da solicitação:

Por exemplo, para atualizar um armazenamento de dados do Cloud Storage:

curl "https://apigee.googleapis.com/v1/organizations/myorg/analytics/datastores" \
  -X PUT \
  -H "Content-type:application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d \
  '{
    "displayName": "My Cloud Storage datastore",
    "datastoreConfig": {
      "projectId": "my-project",
      "bucketName": "my-bucket",
      "path": "my/analytics/path"
    }
  }'

Em que $TOKEN está definido como seu token de acesso OAuth 2.0, conforme descrito em Como receber um token de acesso OAuth 2.0. Para informações sobre as opções de curl usadas neste exemplo, consulte Como usar curl. Para uma descrição das variáveis de ambiente usadas, consulte Como configurar variáveis de ambiente para solicitações da API Apigee.

Veja a seguir um exemplo da resposta para um armazenamento de dados do Cloud Storage:

{
    "self": "/organizations/myorg/analytics/datastores/c7d3b5aq-1c64-3389-9c43-b211b60de35b",
    "displayName": "My Cloud Storage datastore",
    "org": "myorg",
    "targetType": "gcs",
    "createTime": "1535411583949",
    "lastUpdateTime": "1535411634291",
    "datastoreConfig": {
          "projectId": "my-project",
          "bucketName": "my-bucket",
          "path": "my/analytics/path"
    }
}

Para mais informações, consulte a API Update Data Store.

Como excluir um armazenamento de dados

Para excluir um armazenamento de dados, emita uma solicitação DELETE para a API /organizations/{org}/analytics/datastores/{datastore}.

Exemplo:

curl "https://apigee.googleapis.com/v1/organizations/myorg/analytics/datastores/c7d3b5aq-1c64-3389-9c43-b211b60de35b" \
  -X DELETE \
  -H "Authorization: Bearer $TOKEN"

Em que $TOKEN está definido como seu token de acesso OAuth 2.0, conforme descrito em Como receber um token de acesso OAuth 2.0. Para informações sobre as opções de curl usadas neste exemplo, consulte Como usar curl. Para uma descrição das variáveis de ambiente usadas, consulte Como definir variáveis de ambiente para solicitações de API da Apigee.

Veja a seguir um exemplo de resposta:

{}

Para mais informações, consulte Excluir API Data Store.

Como exportar dados de análise

Para exportar dados de análise, emita uma solicitação POST para a API /organizations/{org}/environments/{env}/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 armazenamento de dados

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": "20