数据导入开发者指南

利用 Google Analytics(分析)Management API,可通过编程方式访问 Google Analytics(分析)的数据导入功能。

简介

借助 Management API,您可以上传、列出、删除和获取上传文件以及列表数据集。有关数据导入功能的优点概述,请参阅数据导入简介这一帮助中心文章。

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

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

使用情形

数据导入功能具有三个顶级类别,每个类别都有各自的使用情形。具体的组织结构如下所示:

匹配数据导入

退款数据

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

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

扩展数据导入

用户数据

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

要了解如何将用户数据导入 Google Analytics(分析)中以创建 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."
  ]
}

费用数据总计与覆盖

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

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

要确定对数据集设置的具体类型,应使用自定义数据源 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