从 Google Analytics（分析）中导出数据

您正在查看的是 Apigee Edge 文档。
转到 Apigee X 文档。 信息

为分配的服务代理设置权限

如需为已分配的服务代理设置权限，请执行以下步骤，为上述更改做好准备。

  1. 输入以下命令，查找 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'

    ORG 是您的组织。这将返回服务代理的名称和值，如下所示：

    "property" : [
  {
   "name" : "serviceAgent.analytics",
   "value" : "service-9q1ibk@gcp-sa-apigee-uap.iam.gserviceaccount.com"
   },
  2. 在 Google Cloud 控制台中打开 IAM 信息中心。
  3. 选择您的 Google Cloud 项目。
  4. 点击 IAM 窗格顶部的添加。
  5. 在新的主帐号字段中，输入第 1 步返回的服务代理 value。例如，第 1 步中显示的 value 为 service-9q1ibk@gcp-sa-apigee-uap.iam.gserviceaccount.com。
  6. 点击 +添加其他角色按钮，然后添加以下角色：
    • BigQuery 用户
    • Storage Admin
  7. 点击保存。

Apigee Analytics 数据

Apigee Analytics 会收集并分析流经您的 API 的各种各样的数据，并提供可视化工具，包括交互式信息中心、自定义报告和其他用于确定 API 代理性能趋势的工具。 现在，您可以通过将分析数据从 Apigee Analytics 导出到您自己的数据存储区（例如 Google Cloud Storage 或 Google BigQuery）来解锁这些丰富内容。然后，您可以利用 Google BigQuery 和 TensorFlow 提供的强大的查询和机器学习功能来执行您自己的数据分析。您还可以将导出的分析数据与其他数据（例如网站日志）相结合，从新的角度深入了解您的用户、API 和应用。

导出数据格式

将分析数据导出为以下格式之一：

  • 逗号分隔值 (CSV)

    默认分隔符是英文逗号 (,) 字符。支持的分隔符包括逗号 (,)、竖线 (|) 和制表符 (\t)。使用 csvDelimiter 属性配置值，如导出请求属性参考文档中所述。

  • JSON（以换行符分隔）

    允许将换行符用作分隔符。

导出的数据包括 Edge 中内置的所有分析指标和维度，以及您添加的任何自定义分析数据。如需了解导出数据的说明，请参阅分析指标、维度和过滤器参考文档。

您可以将分析数据导出至以下数据存储区：

导出流程概览

以下步骤汇总了用于导出分析数据的过程：

  1. 为数据导出配置数据存储区（Cloud Storage 或 BigQuery）。您必须确保已正确配置数据存储区，且用于将数据写入数据存储区的服务账号具有正确的权限。

  2. 创建数据存储区，用于定义您要从中导出数据的数据存储区（Cloud Storage 或 BigQuery）的属性，包括用于访问该数据存储区的凭据。

    创建数据存储区时，您需要将数据存储区凭据上传到边缘凭据保险柜，以便安全地存储这些凭据。然后，数据导出机制会使用这些凭据将数据写入您的数据存储区。

  3. 使用 Data Export API 启动数据导出。数据导出在后台异步运行。

  4. 使用 Data Export API 确定导出时间何时完成。

  5. 导出完成后，在数据存储区中访问导出的数据。

下面几个部分将详细介绍这些步骤。

配置数据存储区

分析数据导出机制会将数据写入 Cloud Storage 或 BigQuery。要执行写入操作，您必须：

  • 创建 Google Cloud Platform 服务帐号。
  • 设置服务帐号的角色，使其可以访问 Cloud Storage 或 BigQuery。

为 Cloud Storage 或 BigQuery 创建服务帐号

服务帐号是属于您的应用（而非个人用户）的一种 Google 帐号。然后，您的应用会使用该服务帐号来访问服务。

服务帐号具有以 JSON 字符串表示的服务帐号密钥。创建用于定义与数据存储区的连接的 Edge 数据存储区时，您会向其传递此键。然后，数据导出机制会使用该密钥访问您的数据存储区。

与密钥关联的服务账号必须是 Google Cloud Platform 项目所有者，并且对 Google Cloud Storage 存储分区拥有写入权限。如需创建服务密钥并下载所需的载荷，请参阅 Google Cloud Platform 文档中的创建和管理服务帐号密钥。

例如，当您首次下载密钥时，其格式会设置为 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" 
}

配置 Google Cloud Storage

在将数据导出到 Google Cloud Storage 之前，请先做好以下准备：

  • 确保您的 Google Cloud Platform 项目中启用了 BigQuery 和 Cloud Resource Manager API。如需查看相关说明，请参阅启用 API。在将数据导出至 Cloud Storage 时，Apigee 使用 BigQuery API 利用 BigQuery Export 功能，并使用 Cloud Resource Manager API 在每次导出前检查权限。

  • 确保将服务帐号分配给以下角色：

    • BigQuery Job User
    • Storage Object Creator
    • Storage Admin（仅在测试数据存储区时需要该权限，如测试数据存储区配置中所述）。如果此角色过于宽泛，您可以改为向现有角色添加 storage.buckets.get 权限。）

    此外，如果您要修改现有角色或创建自定义角色，请在角色中添加以下权限：

    • bigquery.jobs.create
    • storage.objects.create
    • storage.buckets.get（仅在测试数据存储区时需要，如测试数据存储区配置中所述）

配置 Google BigQuery

在将数据导出到 Google BigQuery 之前，请先做好以下准备：

  • 确保您的 Google Cloud Platform 项目中启用了 BigQuery 和 Cloud Resource Manager API。如需查看相关说明，请参阅启用 API。在每次导出之前，Apigee 都会使用 Cloud Resource Manager API 检查权限。
  • 确保您的 Google Cloud Platform 项目中启用了 BigQuery API。如需查看相关说明，请参阅启用和停用 API。

  • 确保将服务帐号分配给以下角色：

    • BigQuery Job User
    • BigQuery 数据编辑者

    如果您要修改现有角色或创建自定义角色，请在角色中添加以下权限：

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

创建数据存储区

数据存储区定义与导出数据存储区（Cloud Storage、BigQuery）的连接，包括用于访问数据存储区的凭据。

关于边缘凭据保险柜

Edge 使用凭据保险柜安全地存储用于访问导出数据代码库的凭据。为使服务能够访问边缘凭据保险柜中的凭据，您必须定义凭据使用方。

使用 Edge 界面创建数据存储区时（如下所述），Edge 会自动创建用于访问凭据的使用方。

测试数据存储区配置

当您创建数据存储区时，Edge 不会测试或验证您的凭据和数据存储区配置是否有效。也就是说，您可以创建数据存储区，并且在运行首次数据导出之前不会检测到任何错误。

或者，在创建数据存储区配置之前，对其进行测试。测试非常有用，因为执行大型数据导出流程可能需要很长时间。通过在开始下载大量数据之前测试您的凭据和数据存储区配置，您可以快速解决所有设置问题。

如果测试成功，则创建数据存储区。如果测试失败，请修复错误，然后重新测试配置。只有在测试成功后，才能创建数据存储区。

如需启用该测试功能，您必须：

  • 确保您的 Google Cloud Platform 项目中启用了 Cloud Resource Manager API。如需查看相关说明，请参阅启用和停用 API。

创建数据存储区

如需在界面中创建数据存储区，请执行以下操作：

  1. 以组织管理员身份登录 https://apigee.com/edge，然后选择您的组织。

    注意：您必须是 Edge 组织管理员才能创建数据存储区。

  2. 从左侧导航栏中依次选择管理 > Analytics Datastore。随即会显示 Analytics（分析）数据存储区页面。

  3. 选择 + 添加 Datastore 按钮。系统会提示您选择数据存储区类型：

  4. 选择导出数据目标类型：

    • Google Cloud Storage
    • Google BigQuery

    配置页面即会显示：

  5. 输入数据存储区的名称。

  6. 选择一个用于访问数据存储库的凭据。系统会显示可用凭据的下拉列表。

    凭据特定于某个数据存储区类型。如需了解详情，请参阅为 Cloud Storage 或 BigQuery 创建服务帐号。

    • 如果您已上传了凭据，请从下拉列表中选择凭据。请确保选择适合数据存储类型的凭据。

    • 如果您要向数据存储区添加新凭据，请选择新增。在对话框中，输入：

      1. 凭据名称。
      2. 凭据内容是特定于您的数据存储区的 JSON 服务帐号密钥（如为 Cloud Storage 或 BigQuery 创建服务帐号所定义）。
      3. 选择 Create。

  7. 输入特定于数据存储类型的属性：

    • 对于 Google Cloud Storage：
      媒体资源 说明 是否必需？
      项目 ID Google Cloud Platform 项目 ID。

      如需创建 Google Cloud Platform 项目，请参阅 Google Cloud Platform 文档中的创建和管理项目。

      		是
      存储分区名称 您要将分析数据导出到的 Cloud Storage 存储分区的名称。在导出数据之前，该存储分区必须已存在。

      如需创建 Cloud Storage 存储分区，请参阅 Google Cloud Platform 文档中的创建存储分区。

      		 是
      路径 要在其中将分析数据存储在 Cloud Storage 存储分区中的目录。 是
    • 对于 BigQuery：
      媒体资源 说明 是否必需？
      项目 ID Google Cloud Platform 项目 ID。

      如需创建 Google Cloud Platform 项目，请参阅 Google Cloud Platform 文档中的创建和管理项目。

      		 是
      数据集名称 您希望将分析数据导出到其中的 BigQuery 数据集的名称。确保在请求导出数据之前已创建数据集。

      如需创建 BigQuery 数据集，请参阅 Google Cloud Platform 文档中的创建和使用数据集。

      		 是
      表前缀 为 BigQuery 数据集中分析数据创建的表名称的前缀。 是

  8. 选择测试连接，确保凭据可用于访问数据存储区。

    如果测试成功，请保存您的数据存储区。

    如果测试失败，请修复所有问题并重试测试。将鼠标悬停在界面中的错误消息上，即可在提示中显示更多信息。

  9. 连接测试通过后，保存数据存储区。

修改数据存储区

如需修改数据存储区，请执行以下操作：

  1. 以组织管理员身份登录 https://apigee.com/edge，然后选择您的组织。

  2. 从左侧导航栏中依次选择管理 > Analytics Datastore。随即会显示 Analytics（分析）数据存储区页面。

  3. 将鼠标指针移到要修改的报告的已修改列上。系统会显示修改和删除图标。

  4. 修改或删除数据存储区。

  5. 如果您修改了数据存储区，请选择测试连接，以确保凭据可用于访问数据存储区。

    如果测试成功，您就可以在数据存储区中查看示例数据。

    如果测试失败，请修复所有问题并重试测试。

  6. 连接测试通过后，更新数据存储区。

导出分析数据

如需导出分析数据，请向 /analytics/exports API 发出 POST 请求。在请求正文中传递以下信息：

  • 导出请求的名称和说明
  • 所导出数据的日期范围（值只能跨越一天）
  • 所导出数据的格式
  • 数据存储区名称
  • 组织是否启用了获利功能

下面提供了导出请求的示例。如需请求正文属性的完整说明，请参阅导出请求属性参考文档。

来自 POST 的响应格式如下：

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

请注意，响应中的 state 属性设置为 enqueued。POST 请求是异步运行的。这表示请求在返回响应后会继续在后台运行。state 可能的值包括：enqueued、running、completed、failed。

使用 self 属性中返回的网址查看数据导出请求的状态，如查看分析导出请求的状态中所述。请求完成后，响应中的 state 属性的值设置为 completed。然后，您便可以访问数据存储区中的分析数据。

示例 1：将数据导出到 Cloud Storage

以下请求会从 myorg 组织的 test 环境中导出过去 24 小时内的完整一组原始数据。内容会以 JSON 格式导出到 Cloud Storage：

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

使用 self 属性指定的 URI 来监控作业状态，如查看分析导出请求的状态中所述。

示例 2：将数据导出到 BigQuery

以下请求会将逗号分隔的 CSV 文件导出到 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

注意：导出的 CSV 文件会创建一个具有以下前缀的 BigQuery 表：

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

使用 self 属性指定的 URI 来监控作业状态，如查看分析导出请求的状态中所述。

示例 3：导出获利数据

如果在组织的环境中启用了获利功能，您可以执行两种类型的数据导出：

  • 标准数据导出（如前面的两个示例所示）。
  • 获利数据导出，以导出特定于获利的数据。

如需执行获利数据导出，请在请求载荷中指定 "dataset":"mint"。组织和环境必须支持获利，才能设置此选项，否则将从载荷中省略 dataset 属性：

  '{
    "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"
  }'

Export API 配额简介

为防止过度使用昂贵的数据导出 API 调用，Edge 会对 /analytics/exports API 的调用强制执行配额限制：

  • 对于尚未启用获利功能的组织和环境，配额如下：

    • 每个组织/环境每月 70 次调用。

    例如，如果贵组织中有两个环境（prod 和 test），则每个环境每月可以进行 70 次 API 调用。

  • 对于已启用获利功能的组织和环境，配额为：

    • 对于标准数据，每个组织和环境每月 70 次调用。
    • 对于获利数据，每个组织和环境每月 70 次调用。

    例如，如果您为 prod 组织启用了获利功能，您可以对标准数据进行 70 次 API 调用，以及针对获利数据再进行 70 次调用。

如果超过调用配额，API 将返回 HTTP 429 响应。

查看所有分析导出请求的状态

如需查看所有分析导出请求的状态，请向 /analytics/exports 发出 GET 请求。

例如，以下请求将返回 myorg 组织中 test 环境的所有分析导出请求的状态：

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

下面提供一个响应示例，其中列出两个导出请求，即一个已加入队列的请求（在队列中创建），以及一个已完成的请求：

[
  {
    "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",
    ... 
  }
]

查看一个分析导出请求的状态

如需查看特定分析导出请求的状态，请向 /analytics/exports/{exportId} 发出 GET 请求，其中 {exportId} 是与分析导出请求关联的 ID。

例如，以下请求将返回 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

以下提供了一个响应示例：

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

如果分析导出未返回分析数据，则 executionTime 设置为“0 秒”。

导出请求属性参考文档

下表介绍了您可以在导出分析数据时，在请求正文中以 JSON 格式传递的属性。

属性 说明 重启？
description 导出请求的说明。 否
name 导出请求的名称。 是
dateRange

以 yyyy-mm-dd 格式指定要导出的数据的 start 和 end 日期。例如：

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

dateRange 值只能横跨一天。日期范围从 start 日期的 00:00:00 世界协调时间 (UTC) 开始，在 end 日期的 00:00:00 世界协调时间 (UTC) 结束。

注意：为确保捕获前一天的所有数据，您可能需要延迟导出请求的开始时间（例如，世界协调时间 (UTC) 上午 00:05:00）。

 是
outputFormat 指定为 json 或 csv。 是
csvDelimiter

如果将 outputFormat 设置为 csv，则为 CSV 输出文件中使用的分隔符。默认为 ,（逗号）字符。支持的分隔符包括逗号 (,)、竖线 (|) 和制表符 (\t)。

 否
datastoreName 包含数据存储区定义的数据存储区的名称。 是

例如：

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