从分析结果中导出数据

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

Apigee Analytics 会收集并分析流经您的 API 的大量数据，并提供直观的工具，包括互动式信息中心、自定义报告以及其他可标识 API 代理性能趋势的工具。

现在，您可以通过将分析数据从 Apigee Analytics 导出到您自己的数据存储区（例如 Google Cloud Storage 或 Google BigQuery）来解锁这些丰富内容。然后，您可以利用 Google BigQuery 和 TensorFlow 提供的强大的查询和机器学习功能来执行您自己的数据分析。您还可以将导出的分析数据和其他数据（如网络日志）合并，从而深入了解您的用户、API 和应用。

支持哪些导出数据格式？

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

逗号分隔值 (CSV)

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

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

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

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

导出分析数据的步骤

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

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

创建数据存储区，以定义用于导出数据的数据存储区（Cloud Storage 或 BigQuery）的属性。

导出分析数据。数据导出会在后台异步运行。

查看导出请求的状态以确定导出何时完成。

导出完成后，访问数据存储库中导出的数据。

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

配置数据存储区

配置 Cloud Storage 或 BigQuery，以启用通过分析数据导出的访问权限。

配置 Google Cloud Storage

在将数据导出到 Google Cloud Storage 之前，您需要执行以下操作：

创建 Google Cloud 存储桶。
确保您的 Google Cloud Platform 项目已启用 BigQuery API。导出到 Cloud Storage 时，Apigee 会使用 BigQuery API 来利用 BigQuery 导出功能。

如需了解相关说明，请参阅启用 API。
确保将电子邮件地址为 service-project-number@gcp-sa-apigee.iam.gserviceaccount.com 的 Apigee Service Agent 服务账号分配给以下角色：
- BigQuery 作业用户
- Storage Admin
注意：如果服务账号已存在，则无需创建新账号，只需根据需要更改现有账号的角色。

project-number 列在项目首页上，如下面所示。

请参阅授予、更改和撤消对资源的访问权限。

此外，如果您要修改现有角色或创建自定义角色，请在角色中添加以下权限：
- bigquery.jobs.create
- storage.objects.create
- storage.objects.delete
- storage.objects.list
注意：在更改服务账号的角色后，您必须等待一分钟或更长时间，以使更改生效。

配置 Google BigQuery

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

确保您已在 Google Cloud Platform 项目中启用 BigQuery。
确保您的 Google Cloud Platform 项目已启用 BigQuery API。如需了解相关说明，请参阅启用 API。
确保将电子邮件地址为 service-project-number@gcp-sa-apigee.iam.gserviceaccount.com 的 Apigee Service Agent 服务账号分配给以下角色：
- BigQuery 作业用户
- BigQuery 数据编辑者
注意：如果服务账号已存在，则无需创建新账号，只需根据需要更改现有账号的角色。

project-number 列在项目首页上，如下面所示。

请参阅授予、更改和撤消对资源的访问权限。

如果您要修改现有角色或创建自定义角色，请在角色中添加以下权限：
- bigquery.datasets.create
- bigquery.datasets.get
- bigquery.jobs.create
- bigquery.tables.create
- bigquery.tables.get
- bigquery.tables.updateData
注意：在更改服务账号的角色后，您必须等待一分钟或更长时间，以使更改生效。
创建 BigQuery 数据集。

将数据导出到美国或欧盟的个别区域的 BigQuery

由于美国或欧盟的分析数据存储在美国或欧盟多区域中，因此您无法将数据直接导出到 BigQuery 中的个别美国或欧盟区域。如需解决此问题，您可以先将数据导出到 Google Cloud Storage，然后将其转移到 BigQuery，如下所示：

创建 Cloud Storage 存储桶，并将位置设置为您要与 BigQuery 中的数据关联的美国或欧盟的个别区域。
使用上一步中创建的存储桶创建 Cloud Storage 数据存储区。
将数据导出到 Cloud Storage。如需查看示例，请参阅下面的示例 1：将数据导出到 Cloud Storage。
将数据加载到 BigQuery 中，如以下部分所述：
- 从 Cloud Storage 加载 CSV 数据
- 从 Cloud Storage 加载 JSON 数据

管理数据存储区

datastore数据存储区定义与导出数据存储库（Cloud Storage、BigQuery）的连接。

以下几个部分介绍了如何创建和管理数据存储区。创建数据存储区之前，建议您测试数据存储区配置。

测试数据存储区配置

创建数据存储区时，Apigee 不会测试或验证配置是否有效。这意味着您可以（在下一步）创建数据存储区，并且在运行首次数据导出之前不检测到任何错误。

由于数据导出过程需要很长时间才能完成，因此您可以测试数据存储区配置以确保它有效，并在创建数据存储区之前修复所有错误，从而尽快检测到错误。

如需测试数据存储区配置，请向 /organizations/{org}/analytics/datastores:test API 发出 POST 请求。在请求正文中传递以下信息：

显示名称
数据存储区类型
基于数据存储区类型的配置详细信息，如数据存储区请求属性参考文档中所述。

例如，下面测试 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"
    }
  }'

如果测试成功，下面将提供响应示例：

{
  "state": "completed",
}

如果测试失败，下面将提供响应示例：

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

在这种情况下，请解决错误消息中引发的问题，并重新测试数据存储区配置。成功测试后，按照下一部分所述方式创建数据存储区。

创建数据存储区

如需创建数据存储区，请向 /organizations/{org}/analytics/datastores API 发出 POST 请求。在请求正文中传递以下信息：

显示名称
数据存储区类型
基于数据存储区类型的配置详细信息，如数据存储区请求属性参考文档中所述。

下面针对每个数据存储区类型提供示例。

下面提供 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"
    }
}

使用 self 属性中返回的网址查看数据存储区详细信息，如查看数据存储区的详细信息中所述。

如需了解详情，请参阅 Create Data Store API。

示例 1：创建 Cloud Storage 数据存储区

以下请求会创建一个 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"
    }
  }'

按照获取 OAuth 2.0 访问令牌中的说明，将 $TOKEN 设置为您的 OAuth 2.0 访问令牌。如需了解此示例中使用的 curl 选项，请参阅使用 curl。如需了解所使用的环境变量，请参阅为 Apigee API 请求设置环境变量。

示例 2：创建 BigQuery 数据存储区

以下请求会创建一个 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"
    }
  }'

查看所有数据存储区

如需查看贵组织的所有数据存储区，请向 /organizations/{org}/analytics/datastores API 发出 GET 请求。

例如：

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

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

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

如需了解详情，请参阅 List Data Stores API。

查看数据存储区的详细信息

如需查看数据存储区的详细信息，请向 /organizations/{org}/analytics/datastores/{datastore} API 发出 GET 请求。

例如：

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

下面提供 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"
    }
}

如需了解详情，请参阅 Get Data Store API。

修改数据存储区

如需修改数据存储区，请向 /organizations/{org}/analytics/datastores/{datastore} API 发出 PUT 请求。在请求正文中传递以下部分或全部信息：

数据存储区显示名
基于数据存储区类型的配置详细信息，如数据存储区请求属性参考文档中所述。

例如，如需更新 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"
    }
  }'

下面提供 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"
    }
}

如需了解详情，请参阅 Update Data Store API。

删除数据存储区

如需删除数据存储区，请向 /organizations/{org}/analytics/datastores/{datastore} API 发出 DELETE 请求。

例如：

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

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

{}

如需了解详情，请参阅 Delete Data Store API。

导出分析数据

如需导出分析数据，请向 /organizations/{org}/environments/{env}/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。然后，您便可以访问数据存储区中的分析数据。

如需了解详情，请参阅 Create Data Export API。

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

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

curl "https://apigee.googleapis.com/v1/organizations/myorg/environments/test/analytics/exports" \
  -X POST \
  -H "Content-type:application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d \
  '{
    "name": "Export raw results to Cloud Storage",
    "description": "Export raw results to Cloud Storage for last 24 hours",
    "dateRange": {
      "start": "2020-06-08",
      "end": "2020-06-09"
    },
    "outputFormat": "json",
    "datastoreName": "My Cloud Storage data repository"
  }'

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

示例 2：将数据导出到 BigQuery

注意：BigQuery 数据集的数据位置必须与 analytics_location 相同。对于位于美国或欧盟的分析区域：

如果该区域属于美国，请将数据位置设置为 us（美国的多个区域）。
如果分析区域属于欧盟，请将数据位置设置为 eu（欧盟的多个区域）。

以下示例将以英文逗号分隔的 CSV 文件导出到 BigQuery：

curl "https://apigee.googleapis.com/v1/organizations/myorg/environments/test/analytics/exports" \
  -X POST \
  -H "Content-type:application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -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"
  }'

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

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

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

Export API 配额简介

为防止过度使用昂贵的数据导出 API 调用，Apigee 强制规定每个组织每天最多只能对 organizations/{org}/environments/{env}/analytics/exports API 进行 15 次调用。

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

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

如需查看所有分析导出请求的状态，请向 /organizations/{org}/environments/{env}/analytics/exports 发出 GET 请求。

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

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

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

[
  {
    "self":
"/v1/organizations/myorg/environments/test/analytics/exports/e8b8db22-fe03-4364-aaf2-6d4f110444ba",
    "name": "Export results To Cloud Storage",
    "description": "One-time export to Cloud Storage",
    "userId": "my@email.com",
    "datastoreName": "My datastore",
    "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",
    ... 
  }
]

如需了解详情，请参阅 List Data Exports API。

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

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

注意：提交导出请求时，系统会在 self 属性中返回检查请求状态的网址。如需获取分析导出请求的 ID，请查看所有分析导出请求及其关联 ID 的列表，如查看所有分析导出请求的状态中所述。

例如，以下请求将返回 ID 为 4d6d94ad-a33b-4572-8dba-8677c9c4bd98 的分析导出请求的状态。

curl "https://apigee.googleapis.com/v1/organizations/myorg/environments/test/analytics/exports/4d6d94ad-a33b-4572-8dba-8677c9c4bd98" \
  -X GET \
  -H "Authorization: Bearer $TOKEN"

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

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

如需了解详情，请参阅 Get Data Export API。

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

数据存储区请求属性参考文档

下表介绍了在根据数据存储区类型创建数据存储区时，您可以在请求正文中以 JSON 格式传递的属性。

对于 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 数据集中的分析数据创建的表名称的前缀。	是

导出请求属性参考文档

下表介绍了您可以在导出分析数据时，在请求正文中以 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) 结束。注意：为了确保获取前一天的数据，您可能需要延迟导出请求的开始时间（例如，00:05:00 AM 世界协调时间 (UTC)）。	是
`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",
  "datastoreName": "My Cloud Storage datastore"
}