创建报告

这是 Analytics Reporting API v4 的开发者指南。有关该 API 的详细参考信息,请参阅 API 参考

报告

Analytics Reporting API v4 提供了用于访问报告资源的 batchGet 方法。以下各节说明了 batchGet请求正文结构以及 batchGet 中的响应正文结构。

请求正文

要使用 Analytics Reporting API v4 请求数据,您必须构建 ReportRequest 对象,该对象需要满足这些最低要求:

  • 用于 viewId 字段的有效数据视图 ID。
  • dateRanges 字段中至少有一个有效条目。
  • metrics 字段中至少有一个有效条目。

要查找数据视图 ID,请查询帐号摘要方法或使用帐号浏览器。如果没有提供日期范围,默认的日期范围是:{"startDate": "7daysAgo", "endDate": "yesterday"}

以下是满足所需字段最低要求的请求示例:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dateRanges": [{"startDate": "2014-11-01", "endDate": "2014-11-30"}],
      "metrics": [{"expression": "ga:users"}]
    }
  ]
}

batchGet 方法最多接受五个 ReportRequest 对象。所有请求都应该有相同的 dateRangeviewIdsegmentssamplingLevelcohortGroup

响应正文

API 请求的响应正文报告对象的数组。在 ColumnHeader 对象中定义报告的结构,其中说明了报告中的维度和指标及其数据类型。在数据字段中指定维度和指标的值。

以下是上文示例请求的示例响应:

{
    "reports": [
        {
            "columnHeader": {
                "metricHeader": {
                    "metricHeaderEntries": [
                        {
                            "name": "ga:users",
                            "type": "INTEGER"
                        }
                    ]
                }
            },
            "data": {
                "isDataGolden": true,
                "maximums": [
                    {
                        "values": [
                            "98"
                        ]
                    }
                ],
                "minimums": [
                    {
                        "values": [
                            "98"
                        ]
                    }
                ],
                "rowCount": 1,
                "rows": [
                    {
                        "metrics": [
                            {
                                "values": [
                                    "98"
                                ]
                            }
                        ]
                    }
                ],
                "totals": [
                    {
                        "values": [
                            "98"
                        ]
                    }
                ]
            }
        }
    ]
}

指标

指标是定量测量;每个请求至少需要一个指标对象。

在下面的例子中,会对 batchGet 方法提供 Sessions 指标,来获取指定日期范围内的会话总数:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dateRanges": [{"startDate": "2014-11-01", "endDate": "2014-11-30"}],
      "metrics": [{"expression": "ga:sessions"}]
    }
  ]
}

您可以使用维度和指标浏览器Metadata API 获取可用维度和指标的列表。

过滤

提交 batchGet 请求时,可以要求只返回符合特定条件的指标。要过滤指标,可在请求正文中指定一个或多个 MetricFilterClauses,并在每个 MetricFilterClause 中设定一个或多个 MetricFilters。在每个 MetricFilter 中,为以下各项指定值:

  • metricName
  • not
  • operator
  • comparisonValue

{metricName} 代表指标,{operator} 代表 operator{comparisonValue} 代表 comparisonValue。过滤条件的工作方式如下所示:

if {metricName} {operator} {comparisonValue}
   return the metric

如果对于 not 指定 true,则过滤条件的工作方式如下所示:

if {metricName} {operator} {comparisonValue}
   do not return the metric

在下面的例子中,batchGet 只返回值大于 2 的网页浏览量:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "metrics": [
        {"expression": "ga:pageviews"},
        {"expression": "ga:sessions"}
      ],
      "metricFilterClauses": [{
          "filters": [{
              "metricName": "ga:pageviews",
              "operator": "GREATER_THAN",
              "comparisonValue": "2"
          }]
      }]
  }]
}

表达式

指标表达式是对现有指标定义的数学表达式;其操作方式类似于动态计算指标。您可以定义代表指标表达式的别名,例如:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "metrics":
      [
        {
          "expression": "ga:goal1completions/ga:users",
          "alias": "completions per user"
        }
      ]
    }
  ]
}

排序方式

要按指标值对结果进行排序,请按以下步骤操作:

  • 通过 fieldName 字段提供其名称或别名。
  • 通过 sortOrder 字段指定排序顺序(ASCENDINGDESCENDING)。

在下面的例子中,batchGet 返回的指标会先根据会话次数、再根据网页浏览量进行降序排序:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "metrics":
      [
        {"expression": "ga:pageviews"},
        {"expression": "ga:sessions"}
      ],
      "orderBys":
      [
        {"fieldName": "ga:sessions", "sortOrder": "DESCENDING"},
        {"fieldName": "ga:pageviews", "sortOrder": "DESCENDING"}
      ]
    }
  ]
}

维度

维度用于描述用户及其会话和操作的特征。例如,City 维度说明会话的特征,并指明每个会话的发起城市(“Paris”或“New York”)。在 batchGet 请求中,您可以指定零个或多个维度对象,例如:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dateRanges":
      [
        {"endDate": "2014-11-30", "startDate": "2014-11-01"}
      ],
      "metrics":
      [
        {"expression": "ga:users"}
      ],
      "dimensions":
      [
        {"name": "ga:city"}
      ]
    }
  ]
}

过滤

提交 batchGet 请求时,可以要求只返回符合特定条件的维度。要过滤维度,可在请求正文中指定一个或多个 DimensionsFilterClauses,并在每个 DimensionsFilterClause 中设定一个或多个 DimensionsFilters。在每个 DimensionsFilters 中,为以下各项指定值:

  • dimensionName
  • not
  • operator
  • expressions
  • caseSensitive

{dimensionName} 代表维度,{operator} 代表 operator{expressions} 代表 expressions。过滤条件的工作方式如下所示:

if {dimensionName} {operator} {expressions}
    return the dimension

如果对于 not 指定 true,则过滤条件的工作方式如下所示:

if {dimensionName} {operator} {expressions}
    do not return the dimension

在下面的例子中,batchGet 返回 Chrome 浏览器中的网页浏览量和会话次数:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dateRanges": [
        {"endDate": "2014-11-30", "startDate": "2014-11-01"}
      ],
      "metrics": [
        {"expression": "ga:pageviews"},
        {"expression": "ga:sessions"}
      ],
      "dimensions": [{"name": "ga:browser"}, {"name": "ga:country"}],
      "dimensionFilterClauses": [
        {
          "filters": [
            {
              "dimensionName": "ga:browser",
              "operator": "EXACT",
              "expressions": ["Chrome"]
            }
          ]
        }
      ]
    }
  ]
}

排序方式

要通过维度值对结果进行排序,请按以下步骤操作:

  • 通过 fieldName 字段提供其名称。
  • 通过 sortOrder 字段指定排序顺序(ASCENDINGDESCENDING)。

例如,下面的 batchGet 返回先根据国家/地区、再根据浏览器排序的维度:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "metrics": [{"expression": "ga:sessions"}],
      "dimensions": [{"name": "ga:country"},{"name": "ga:browser"}],
      "orderBys": [
        {"fieldName": "ga:country"},
        {"fieldName": "ga:browser"}
      ]
    }
  ]
}

直方图范围

对于整数值的各种维度,通过将其值划分为不同的范围,可以更轻松地了解这些维度的特性。使用 histogramBuckets 字段设定所得范围的划分方式,并将 HISTOGRAM_BUCKET 指定为排序类型,例如:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "metrics": [{"expression": "ga:sessions"}],
      "dimensions": [
        {
          "name": "ga:sessionCount",
          "histogramBuckets": ["1","10","100","200","400"]
        }
      ],
      "orderBys": [
        {
          "fieldName": "ga:sessionCount",
          "orderType": "HISTOGRAM_BUCKET"
        }
      ]
    }
  ]
}

多个日期范围

Google Analytics(分析)Reporting API v4 允许您在单个请求中获得多个日期范围的数据。无论您的请求是指定一个还是两个日期范围,都会在 dateRangeValue 对象中返回数据,例如:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dateRanges": [
        {"startDate": "2014-11-01", "endDate": "2014-11-30"},
        {"startDate": "2014-10-01", "endDate": "2014-10-30"}
      ],
      "metrics": [
        {"expression": "ga:pageviews"},
        {"expression": "ga:sessions"}
      ],
      "dimensions": [{"name": "ga:pageTitle"}]
    }
  ]
}

变动量排序

当请求两个日期范围中的指标值时,您可以根据日期范围中指标值之差对结果进行排序:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dateRanges": [
        {"startDate": "2014-11-01", "endDate": "2014-11-30"},
        {"startDate": "2014-10-01", "endDate": "2014-10-30"}
      ],
      "metrics": [
        {"expression": "ga:pageviews"},
        {"expression": "ga:sessions"}
      ],
      "dimensions": [{"name": "ga:pageTitle"}],
      "orderBys": [
        {
          "fieldName": "ga:sessions",
          "orderType": "DELTA"
        }
      ]
    }
  ]
}

日期维度行为

如果您请求与日期或时间相关的维度,则 DateRangeValue 对象只会保留日期落在相应范围中的值;不在指定日期范围内的所有其他值都是 0

例如,考虑 1 月和 2 月这两个日期范围中对 ga:date 维度和 ga:sessions 指标的请求。在对 1 月份所请求数据的响应中,2 月的数值是 0;在对 2 月份所请求数据的响应中,1 月的数值是 0

1 月份的报告

{
    "dimensions": [
        "20140101" # `ga:date` dimension value for January 1, 2014.
    ],
    "metrics": [
        {
            "values": [ # January DateRangeValue.
                "8"
            ]
        },
        {
            "values": [ # February DateRangeValue.
                "0"
            ]
        }
    ]
},
...

2 月份的报告

{
    "dimensions": [
        "20140201"  # `ga:date` dimension value for February 1, 2014.
    ],
    "metrics": [
        {
            "values": [ # January DateRangeValue.
                "0"
            ]
        },
        {
            "values": [ # February DateRangeValue.
                "7"
            ]
        }
    ]
},
...

细分

要请求 Google Analytics(分析)数据的子集,请使用细分。例如,您可以将来自特定国家/地区或城市的用户定义为一个细分,将访问您网站特定部分的用户定义为另一个细分。过滤条件只返回满足条件的行,而细分所返回的用户、会话或事件的子集是满足包含细分这类条件。

使用细分发出请求时,请确保:

  • batchGet 方法中的每个 ReportRequest 都必须包含同样的细分定义。
  • ga:segment 添加到维度列表。

例如:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests": [
    {
      "viewId": "XXXX",
      "dimensions": [{"name": "ga:segment"}, {"name": "ga:browser"}],
      "metrics": [{"expression": "ga:sessions"}],
      "segments": [
        {
          "dynamicSegment":
          {
            "name": "Sessions with Safari browser",
            "userSegment":
            {
              "segmentFilters": [
                {
                  "simpleSegment":
                  {
                    "orFiltersForSegment": [
                      {
                        "segmentFilterClauses": [
                          {
                            "dimensionFilter":
                            {
                              "dimensionName": "ga:browser",
                              "operator": "EXACT",
                              "expressions": ["Safari"]
                            }
                        }]
                    }]
                  }
              }]
            }
          }
      }]
  }]
}

有关使用细分的请求的更多示例,请参阅示例

细分 ID

使用 segmentId 字段请求细分。您不能同时使用 segmentIddynamicSegment 请求细分。

例如:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dimensions": [{"name": "ga:medium"}, {"name": "ga:segment"}],
      "metrics": [{"expression": "ga:users"}],
      "segments":  [{"segmentId": "gaid::-3"}]
    }
  ]
}

抽样

抽样可能会影响数据的结果,也经常造成 API 返回的值与网页界面上的值不一样。使用 samplingLevel 字段设置所需的样本规模。

  • 将该值设为 SMALL 可以以较小的抽样规模快速做出响应。
  • 将该值设为 LARGE 可以得到更准确的响应,但速度较慢。
  • 将该值设为 DEFAULT 可以实现响应速度与准确度的平衡。

例如:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dimensions": [{"name": "ga:medium"}],
      "metrics": [{"expression": "ga:sessions"}],
      "samplingLevel":  "LARGE"
    }
  ]
}

如果报告包含抽样数据,Analytics Reporting API v4 会返回 samplesReadCountssamplingSpaceSizes 字段。如果未对结果进行抽样,将不会定义这些字段。

下例中的响应所包含的抽样数据来自有两个日期范围的请求。这些结果计算自约 1500 万个会话的抽样空间中的约 50 万个样本

{
  "reports":
  [
    {
      "columnHeader": {
        ...
      },
      "data": {
        ...
        "samplesReadCounts": [ "499630","499630"],
        "samplingSpaceSizes": ["15328013","15328013"],
      }
    }
  ]
}

分页

Analytics Reporting API v4 使用 pageTokenpageSize 字段对跨多个页面的响应结果进行分页。您可以从 reports.batchGet 请求的响应中的 nextPageToken 参数里获取 pageToken

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":[
  {
    ...
    # Taken from `nextPageToken` of a previous response.
    "pageToken": "10000",
    "pageSize": "10000",
  }]
}

后续步骤

您已经了解了创建报告的基础知识,不妨看看 API v4 的高级功能