数据导入 - 开发者指南

本文向开发者解释了一些有关如何使用 Management API 将数据导入 Google Analytics(分析)帐户的高级概念。

简介

通过 Management API 中的“数据导入”功能,您可以为自己的 Google Analytics(分析)帐户上传、列出、删除和获取导入数据。要阅读相关概览并详细了解“数据导入”功能所带来的好处,请查看数据导入简介

Management API 中对“数据导入”功能提供支持的两项资源是:

  • 自定义数据源资源,在网络接口中又称为“数据集”,用作存储上传文件的容器。自定义数据源集合代表与某项 Google Analytics(分析)媒体资源相关联的所有数据源。
  • 上传”资源,代表一个上传文件。“上传”资源的集合代表您向某个自定义数据源/数据集上传的所有文件。

开始之前

所有 Google Analytics(分析)API 的访问方法都基本相同。在开始使用 Management API 之前,请阅读:

  • 客户端库页面,查看与该 API 配合使用的编程语言专用客户端库的完整列表。
  • 参考指南,熟悉该 API 的接口,并了解如何在没有客户端库的情况下访问数据。

每个客户端库提供单个 Analytics 服务对象来访问所有的 Management API 数据。要创建服务对象,请执行以下操作:

  1. Google Developers Console 中注册您的应用。
  2. 授予访问 Google Analytics(分析)数据的权限。
  3. 创建一个 Analytics 服务对象。

如果您未能完成上述步骤,请停止操作,并阅读了解 Google Analytics(分析)API 教程。该教程将为您详细介绍构建 Google Analytics(分析)API 应用的最初几个步骤。完成这些步骤后,您将了解如何访问 Google Analytics(分析)API 以执行实际任务。

使用情形

可以使用“数据导入”功能将您的业务数据与 Google Analytics(分析)数据进行整合。例如,您可以使用

匹配数据导入

退款数据

您可以将已经全额或部分退款的电子商务交易上传到 Google Analytics(分析)。这样就能轻松实现在您的 Google Analytics(分析)电子商务报告中对照已处理的退款自动调整数据。

要了解如何将退款数据导入 Google Analytics(分析),请参阅退款数据导入示例

扩展数据导入

用户数据

您可以上传来自外部客户关系管理工具的不会识别个人身份的用户数据,并针对您最有价值的细分用户群创建 AdWords 再营销受众群体。

要了解如何将用户数据导入 Google Analytics(分析)以创建 AdWords 再营销列表,请参阅导入用户数据以创建 AdWords 再营销受众群体

广告系列数据

您可以将广告系列数据导入 Google Analytics(分析),来定制针对您业务的广告系列效果分析。

要了解如何将广告系列数据导入 Google Analytics(分析),请参阅使用 Management API 导入广告系列数据

地理位置数据

您可以导入地理位置 ID 与各个区域的映射表,以针对按自定义区域划分的 Google Analytics(分析)数据生成报告。例如,在美国,公司可能会开设在各个州的东部、中部和西部;在欧洲,公司可能会开设在各个国家/地区的北部、中部和南部。导入数据时,您可以使用 ga:regionIdga:cityIdga:countryIsoCodega:subContinentCode 作为键。地理位置定位表格中列出了城市 ID 和国家/地区 ID。ISO-3166-1 alpha-2UN M.49 表格中分别列出了国家/地区 ISO 代码和次大陆代码。

要详细了解如何导入地理位置数据,请参阅地理位置数据导入示例

内容数据

您可以上传与内容相关的元数据,比如作者和主题,以利用 Google Analytics(分析)对发布在网站上的文章进行深入分析。

要了解如何将内容数据导入 Google Analytics(分析),请参阅内容数据导入示例

产品数据

将产品数据导入 Google Analytics(分析)可以简化和减少您需要与匹配数据(如网页浏览量和事件)一起发送的电子商务数据量。可以将单个产品 ID 或 SKU 与导入的产品数据合并,从而将产品维度和指标填充到报告中。

要了解如何将产品数据导入 Google Analytics(分析),请参阅使用 Management API 导入产品数据

摘要数据导入

费用数据

您可以为非 Google 的付费广告系列上传费用数据,利用 Google Analytics(分析)平台执行投资回报率分析,并比较所有在线广告和营销投资的广告系列效果。

要了解如何将费用数据导入 Google Analytics(分析),请参阅使用 Management API 导入费用数据

概念

处理状态

在您上传文件后,上传状态将变为 PENDING,直到上传文件得到验证和处理。如果处理成功,状态将变为 COMPLETED

如果在处理过程中发生错误,上传未成功,上传状态将变为 FAILED。系统将提供错误列表,帮助您找出上传文件所存在的问题。下面是对于一个验证失败的上传文件的响应示例:

{
  id: "YU4DersR_ORzyzXC_AoWw",
  kind: "analytics#upload",
  accountId: "12345",
  customDataSourceId: "poaU7EPcR4WGU-dkNghYKQ",
  status: "FAILED",
  errors:
  [
    "Invalid cell data 12.99 at row 1 column 6. expected data type LONG.",
    "Invalid cell data 12.99 at row 2 column 6. expected data type LONG.",
    "Invalid cell data 23.81 at row 3 column 6. expected data type LONG.",
    "Invalid cell data 199.99 at row 4 column 6. expected data type LONG."
  ]
}

费用数据总计与覆盖

创建费用数据的自定义数据源/数据集时,如果上传文件包含的某行数据带有与现有行匹配的键(例如日期、来源、媒介),您可以使用选项来指定如何处理这种情形。选项包括:

  • 总计(默认选项)- 新数据将添加到先前的任何匹配数据中,相应的指标值将进行加总。
  • 覆盖 - 新数据将覆盖先前的任何匹配数据。

要了解自定义数据源/数据集被设置为采取何种处理,请使用 custom data source list 方式,查看 importBehavior 属性是被设置为 OVERWRITE 还是 SUMMATION

费用数据的行级总计与覆盖

您还可以通过在标题中包含 ga:importBehavior 列,为您上传的每个文件选择是否覆盖自定义数据源/数据集行为。您可以在每一行将 ga:importBehaviour 的值设置为 SUMMATIONOVERWRITE

例如,以下文件将覆盖 Facebook/cpc 和 Yahoo/cpc 中任何先前的费用数据,但 Bing/cpc 这一行将被添加到任何现有的匹配该特定日期和来源/媒介组合的费用数据中。

ga:date,ga:source, ga:medium,ga:adCost,ga:importBehavior
20140604,facebook,cpc,12.23,OVERWRITE
20140604,bing,cpc,3.23,SUMMATION
20140604,yahoo,cpc,11.23,OVERWRITE

数据导入格式和限制

上传到 Google Analytics(分析)的数据必须采用格式正确的 CSV 文件形式。本节介绍了此类文件需要满足的限制条件,对于所有数据导入类型来说,只有满足了这些条件,CSV 文件才会被视为有效的上传文件。

如果以下任一限制条件未能得到满足,或者如果有解析错误,则上传请求将会失败并发出错误消息。该 API 在每个响应中会报告最多 10 个错误,以帮助用户减少无效上传的数量。

文件限制

  • 编码:UTF-8
  • 文件大小限制:1 GB
  • 第一行会被视为列标题,属于必需项。
  • 列标题必须定义特定列将包含的维度和指标。

行限制

  • 行限制为 1 MB。

单元格格式

  • 单元格内容的长度上限为 2048 个字符。
  • 单元格中开头和末尾的空格都将被移除。
  • 要在单元格内指定逗号,该单元格的值必须以双引号括住。例如,source1,"medium,ether",group1,100 — 第二个单元格的值为 medium,ether。
  • 要在单元格内指定双引号,除了值开头和末尾的双引号以外,还需要以一个双引号来对此双引号做转义处理。例如,source1,"medium""ether",group1,100 — 第二个单元格的值为 medium"ether。

代码示例

通过 upload 资源,授权用户可以上传、列出、获取和删除导入的数据。通过 customDataSource 资源,授权用户可以列出任何自定义数据源。要进行这些操作,您需要创建一个 Analytics 服务对象,如开始之前部分所述。

要查看代码示例,了解如何使用“上传”资源,请访问下面的方式参考。

上传

  • list — 列出用户有访问权限的上传文件。
  • get — 获取用户有访问权限的上传文件。
  • deleteUploadData — 删除与先前上传相关的数据。
  • uploadData - 上传用于自定义数据源的数据。

自定义数据源/数据集

  • list — 列出用户有访问权限的自定义数据源。