建立報表

這份 Analytics (分析) Reporting API v4 開發人員指南如需 API 的詳細參考資料,請參閱 API 參考資料

報表

Analytics Reporting API v4 提供 batchGet 方法,用於存取 Reports 資源。 以下各節說明 batchGet要求主體結構以及 batchGet回應主體結構。

要求主體

如要使用 Analytics Reporting API v4 要求資料,您必須建構 ReportRequest 物件,其必須符合下列最低需求:

  • viewId 欄位的有效資料檢視 ID。
  • dateRanges 欄位中至少有一個有效項目。
  • 在「metrics」欄位中至少有一個有效項目。

如要找出資料檢視 ID,請查詢帳戶摘要方法,或使用 Account Explorer。如未提供日期範圍,則預設日期範圍為:{"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 要求的回應主體Report 物件的陣列。報表結構是在 ColumnHeader 物件定義,該物件會說明報表中的維度和指標及其資料類型。維度和指標的值是在「data」欄位中指定。

以下是上述要求範例的回應範例:

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

指標

指標是量化測量資料;每個要求至少需要一個 Metric 物件。

在以下範例中,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"}
      ]
    }
  ]
}

尺寸

維度表示使用者的特徵、工作階段和動作。 舉例來說,「城市」維度會描述工作階段的特徵,並指出每個工作階段的來源城市 (「巴黎」或「紐約」)。在 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"
            ]
        }
    ]
},
...

路段

如要要求部分 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 中的取樣資料,則 Analytics (分析) Reporting API v4 會傳回 samplesReadCountssamplingSpaceSizes 欄位。如果結果沒有取樣,這些欄位就不會定義。

以下回應範例包含來自兩個日期範圍的要求取樣資料。結果計算依據為約 1,500 萬個工作階段的取樣空間大小將近 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 的進階功能