Tạo báo cáo

Đây là hướng dẫn cho nhà phát triển về API Báo cáo Analytics phiên bản 4. Để tham khảo chi tiết về API, hãy xem Tài liệu tham khảo API.

Báo cáo

API Báo cáo Analytics phiên bản 4 cung cấp phương thức batchGet để truy cập vào tài nguyên Báo cáo. Các phần sau đây mô tả cấu trúc của nội dung yêu cầu cho batchGet và cấu trúc của nội dung phản hồi từ batchGet.

Nội dung yêu cầu

Để sử dụng API Báo cáo Analytics phiên bản 4 nhằm yêu cầu dữ liệu, bạn phải tạo đối tượng ReportRequest. Đối tượng này có các yêu cầu tối thiểu sau:

  • Mã chế độ xem hợp lệ cho trường viewId.
  • Ít nhất một mục nhập hợp lệ trong trường dateRanges.
  • Ít nhất một mục nhập hợp lệ trong trường metrics.

Để tìm mã chế độ xem, hãy truy vấn phương thức tóm tắt tài khoản hoặc sử dụng Trình khám phá tài khoản. Nếu bạn không cung cấp phạm vi ngày, phạm vi ngày mặc định sẽ là: {"startDate": "7daysAgo", "endDate": "yesterday"}.

Dưới đây là một yêu cầu mẫu có các trường bắt buộc tối thiểu:

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

Phương thức batchGet chấp nhận tối đa 5 đối tượng ReportRequest. Tất cả các yêu cầu phải có cùng dateRange, viewId, segments, samplingLevel và cohortGroup.

Nội dung phản hồi

Nội dung phản hồi của yêu cầu API là một mảng các đối tượng Báo cáo. Cấu trúc báo cáo được xác định trong đối tượng ColumnHeader mô tả các phương diện và chỉ số cũng như kiểu dữ liệu của các phương diện và chỉ số đó trong báo cáo. Các giá trị của phương diện và chỉ số được chỉ định trong trường dữ liệu.

Dưới đây là phản hồi mẫu cho yêu cầu mẫu ở trên:

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

Chỉ số

Chỉ số là các phép đo định lượng; mỗi yêu cầu cần có ít nhất một đối tượng Chỉ số.

Trong ví dụ sau, chỉ số Sessions được cung cấp cho phương thức batchGet để nhận tổng số phiên trong phạm vi ngày đã chỉ định:

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

Bạn có thể sử dụng trình khám phá phương diện và chỉ số hoặc API siêu dữ liệu để nhận danh sách các phương diện và chỉ số có sẵn.

Lọc

Khi gửi yêu cầu batchGet, bạn có thể yêu cầu yêu cầu chỉ trả về các chỉ số đáp ứng các tiêu chí cụ thể. Để lọc chỉ số, trong nội dung yêu cầu, hãy chỉ định một hoặc nhiều MetricFilterClauses và trong mỗi MetricFilterClause, hãy xác định một hoặc nhiều MetricFilters. Trong mỗi MetricFilter, hãy chỉ định giá trị cho các tham số sau:

  • metricName
  • not
  • operator
  • comparisonValue

Hãy cho {metricName} đại diện cho chỉ số, {operator} là operator và {comparisonValue} là comparisonValue. Sau đó, bộ lọc sẽ hoạt động như sau:

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

Nếu bạn chỉ định true cho not, thì bộ lọc sẽ hoạt động như sau:

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

Trong ví dụ sau, batchGet chỉ trả về những lượt xem trang có giá trị lớn hơn 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"
          }]
      }]
  }]
}

Biểu thức

Biểu thức chỉ số là một biểu thức toán học mà bạn xác định cho các chỉ số hiện có; biểu thức này hoạt động giống như chỉ số được tính linh động. Bạn có thể xác định một bí danh để đại diện cho biểu thức chỉ số, ví dụ:

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

Thứ tự sắp xếp

Cách sắp xếp kết quả theo giá trị chỉ số:

  • Cung cấp tên hoặc email đại diện của tổ chức đó thông qua trường fieldName.
  • Hãy chỉ định thứ tự sắp xếp (ASCENDING hoặc DESCENDING) thông qua trường sortOrder.

Trong ví dụ sau, batchGet trả về các chỉ số được sắp xếp theo số phiên trước tiên, sau đó theo số lượt xem trang theo thứ tự giảm dần:

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

Kích thước

Tham số mô tả các đặc tính của người dùng, các phiên và hành động của họ. Ví dụ: thứ nguyên Thành phố mô tả một đặc điểm của các phiên và cho biết thành phố ("Paris" hoặc "New York") mà mỗi phiên bắt nguồn từ đó. Trong yêu cầu batchGet, bạn có thể chỉ định số không hoặc nhiều đối tượng phương diện, ví dụ:

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

Lọc

Khi gửi yêu cầu batchGet, bạn có thể yêu cầu yêu cầu chỉ trả về những phương diện đáp ứng các tiêu chí cụ thể. Để lọc kích thước, trong nội dung yêu cầu, hãy chỉ định một hoặc nhiều DimensionsFilterClauses và trong mỗi DimensionsFilterClause, hãy xác định một hoặc nhiều DimensionsFilters. Trong mỗi DimensionsFilters, hãy chỉ định giá trị cho các tham số sau:

  • dimensionName
  • not
  • operator
  • expressions
  • caseSensitive

Giả sử {dimensionName} đại diện cho phương diện, {operator} là operator và {expressions} là expressions. Sau đó, bộ lọc sẽ hoạt động như sau:

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

Nếu bạn chỉ định true cho not, thì bộ lọc sẽ hoạt động như sau:

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

Trong ví dụ sau, batchGet trả về số lượt xem trang và phiên trong trình duyệt 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"]
            }
          ]
        }
      ]
    }
  ]
}

Thứ tự sắp xếp

Cách sắp xếp kết quả theo giá trị phương diện:

  • Cung cấp tên thông qua trường fieldName.
  • Hãy chỉ định thứ tự sắp xếp (ASCENDING hoặc DESCENDING) thông qua trường sortOrder.

Ví dụ: batchGet sau đây trả về các phương diện được sắp xếp theo quốc gia và sau đó theo trình duyệt:

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

Nhóm biểu đồ

Đối với các thứ nguyên có giá trị số nguyên, sẽ dễ dàng hơn để hiểu đặc điểm của chúng bằng cách nhóm giá trị của chúng thành các phạm vi. Sử dụng trường histogramBuckets để xác định phạm vi cho các bộ chứa tổng hợp và chỉ định HISTOGRAM_BUCKET làm loại thứ tự, ví dụ:

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

Nhiều phạm vi ngày

API Báo cáo Google Analytics phiên bản 4 cho phép bạn nhận dữ liệu ở nhiều phạm vi ngày trong một yêu cầu duy nhất. Cho dù yêu cầu của bạn chỉ định một hoặc hai phạm vi ngày, dữ liệu vẫn được trả về trong đối tượng dateRangeValue, ví dụ:

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

Sắp xếp theo phương thức delta

Khi yêu cầu giá trị chỉ số trong hai phạm vi ngày, bạn có thể sắp xếp kết quả theo sự chênh lệch giữa các giá trị của chỉ số trong các phạm vi ngày đó, ví dụ:

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

Hành vi của phương diện ngày

Nếu bạn yêu cầu phương diện liên quan đến ngày hoặc giờ, thì đối tượng DateRangeValue sẽ chỉ lưu giữ giá trị cho những ngày thuộc phạm vi tương ứng; tất cả các giá trị khác không nằm trong phạm vi ngày được chỉ định sẽ là 0.

Ví dụ: hãy xem xét yêu cầu về phương diện ga:date và chỉ số ga:sessions trong hai phạm vi ngày: Tháng 1 và tháng 2. Khi phản hồi dữ liệu được yêu cầu trong tháng 1, giá trị trong tháng 2 sẽ là 0; và để phản hồi dữ liệu được yêu cầu trong tháng 2, giá trị trong tháng 1 sẽ là 0.

Báo cáo tháng 1

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

Báo cáo tháng 2

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

Phân đoạn

Để yêu cầu một tập hợp con dữ liệu Analytics, hãy sử dụng phân đoạn. Ví dụ: bạn có thể xác định người dùng ở một quốc gia hoặc thành phố cụ thể trong một phân khúc và những người dùng truy cập vào một phần cụ thể trên trang web của bạn ở một phân khúc khác. Bộ lọc chỉ trả về những hàng đáp ứng điều kiện, trong khi phân đoạn trả về tập hợp con người dùng, phiên hoặc sự kiện đáp ứng điều kiện chứa phân đoạn.

Khi đưa ra yêu cầu với phân khúc, hãy đảm bảo rằng:

  • Mỗi ReportRequest trong phương thức batchGet phải chứa các định nghĩa phân đoạn giống nhau.
  • Bạn thêm ga:segment vào danh sách phương diện.

Ví dụ:

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

Xem phần Mẫu để biết thêm các yêu cầu mẫu với phân đoạn.

Mã phân đoạn

Sử dụng trường segmentId để yêu cầu phân khúc. Bạn không thể sử dụng cả segmentId và dynamicSegment để yêu cầu phân khúc.

Ví dụ:

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

Lấy mẫu

Việc lấy mẫu có thể ảnh hưởng đến kết quả dữ liệu của bạn và là lý do phổ biến khiến các giá trị được trả về từ API không khớp với giao diện web. Sử dụng trường samplingLevel để đặt kích thước mẫu mong muốn.

  • Thiết lập giá trị thành SMALL cho phản hồi nhanh với quy mô lấy mẫu nhỏ hơn.
  • thiết lập giá trị thành LARGE để phản hồi chính xác hơn nhưng chậm hơn.
  • đặt giá trị thành DEFAULT để phản hồi cân bằng giữa tốc độ và độ chính xác.

Ví dụ:

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

nếu báo cáo chứa dữ liệu được lấy mẫu, thì API Báo cáo Analytics phiên bản 4 sẽ trả về các trường samplesReadCounts và các trường samplingSpaceSizes. Nếu kết quả không được lấy mẫu thì các trường này sẽ không được xác định.

Dưới đây là phản hồi mẫu chứa dữ liệu được lấy mẫu của một yêu cầu có 2 phạm vi ngày. Kết quả được tính toán từ gần 500 nghìn mẫu có quy mô không gian lấy mẫu khoảng 15 triệu phiên:

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

Phân trang

API Báo cáo Analytics phiên bản 4 sử dụng các trường pageToken và pageSize để phân trang thông qua kết quả phản hồi trên nhiều trang. Bạn sẽ nhận được pageToken từ tham số nextPageToken trong phản hồi cho yêu cầu reports.batchGet:

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

Bước tiếp theo

Giờ đây, khi bạn đã nắm được các thông tin cơ bản về cách tạo báo cáo, hãy xem các tính năng nâng cao của API v4.