Nguyên tắc cơ bản về báo cáo Tasks

Khi sử dụng các tác vụ báo cáo, bạn có thể bắt đầu một yêu cầu không đồng bộ chạy trong thời gian dài để tạo báo cáo tuỳ chỉnh về dữ liệu sự kiện Google Analytics.

Tất cả người dùng có quyền đọc đối với tài sản Google Analytics của bạn đều có thể sử dụng tài nguyên Tác vụ báo cáo được tạo từ yêu cầu này để truy cập vào các báo cáo tuỳ chỉnh.

Báo cáo tuỳ chỉnh sẽ có hiệu lực trong 72 giờ sau khi được tạo. Sau khoảng thời gian này, tài nguyên tác vụ báo cáo tương ứng và nội dung của tài nguyên đó sẽ tự động bị xoá.

Tạo việc cần làm liên quan đến báo cáo

API Dữ liệu Google Analytics phiên bản 1 sử dụng phương pháp không đồng bộ để tạo các Tác vụ báo cáo. Trước tiên, bạn cần phải có một yêu cầu đối với phương thức reportTasks.create để tạo một Tác vụ báo cáo. Sau đó, phương thức reportTasks.query được dùng để truy xuất báo cáo tuỳ chỉnh đã tạo.

Ngoài ra, bạn có thể sử dụng reportTasks.get để truy xuất siêu dữ liệu cấu hình về một Tác vụ báo cáo cụ thể và reportTasks.list để liệt kê tất cả Tác vụ báo cáo cho một tài sản.

Chọn một pháp nhân báo cáo

Tất cả các phương thức của Data API phiên bản 1 đều yêu cầu bạn chỉ định giá trị nhận dạng tài sản Google Analytics trong đường dẫn yêu cầu URL dưới dạng properties/GA_PROPERTY_ID, chẳng hạn như:

  POST  https://analyticsdata.googleapis.com/v1alpha/properties/GA_PROPERTY_ID/reportTasks

Báo cáo này được tạo dựa trên dữ liệu sự kiện Google Analytics được thu thập trong tài sản Google Analytics được chỉ định.

Nếu đang dùng một trong các thư viện ứng dụng Data API, bạn không cần phải thao tác với đường dẫn URL yêu cầu theo cách thủ công. Hầu hết ứng dụng API đều cung cấp tham số property yêu cầu một chuỗi ở dạng properties/GA_PROPERTY_ID. Hãy xem Hướng dẫn bắt đầu nhanh để biết ví dụ về cách sử dụng thư viện ứng dụng.

Yêu cầu tạo việc cần làm báo cáo

Để tạo một Report Task, hãy gọi phương thức reportTasks.create bằng đối tượng ReportTask trong một yêu cầu. Các tham số sau đây là bắt buộc:

Ví dụ về yêu cầu tạo Tác vụ báo cáo:

Yêu cầu HTTP

POST https://analyticsdata.googleapis.com/v1alpha/properties/1234567/reportTasks
{
  "reportDefinition": {
    "dateRanges": [{ "startDate": "2024-05-01"", "endDate": "2024-05-15" }],
    "dimensions": [{ "name": "country" }],
    "metrics": [{ "name": "activeUsers" }]
  }
}

Phản hồi của phương thức reportTasks.create chứa tên ReportTask trong trường name (chẳng hạn như properties/1234567/reportTasks/123). Bạn có thể dùng tên này trong các truy vấn tiếp theo để lấy trạng thái của ReportTask và truy xuất báo cáo kết quả.

Phản hồi HTTP

{
  "response": {
    "@type": "type.googleapis.com/google.analytics.data.v1alpha.ReportTask",
    "name": "properties/1234567/reportTasks/123",
    "reportDefinition": {
      "dimensions": [
        {
          "name": "country"
        }
      ],
      "metrics": [
        {
          "name": "activeUsers"
        }
      ],
      "dateRanges": [
        {
          "startDate": "2024-05-01",
          "endDate": "2024-05-15"
        }
      ]
    },
    "reportMetadata": {
      "state": "CREATING",
      "beginCreatingTime": "2024-05-16T00:00:01.133612336Z"
    }
  }
}

Lấy trạng thái sẵn sàng của Report Task

Có thể mất vài phút để tạo báo cáo sau lệnh gọi reportTasks.create. Bạn có thể lấy trạng thái sẵn sàng cho một Tác vụ báo cáo bằng cách gọi phương thức reportTasks.get.

Sử dụng tên Report Task (chẳng hạn như properties/1234567/reportTasks/123) mà bạn nhận được từ phản hồi reportTasks.create để chỉ định Report Task.

Ví dụ:

Yêu cầu HTTP

GET https://analyticsdata.googleapis.com/v1alpha/properties/1234567/reportTasks/123

Trạng thái sẵn sàng của một Report Task được trả về trong trường state của một phản hồi. Sau khi quá trình tạo báo cáo hoàn tất, trạng thái của một Tác vụ báo cáo sẽ thay đổi từ CREATING thành ACTIVE.

Trường reportMetadata chứa thông tin cấp cao về báo cáo đã tạo, chẳng hạn như số lượng hàng và số lượng mã thông báo hạn mức đã tính phí.

Phản hồi HTTP

{
  "reportDefinition": {
    "dimensions": [
      {
        "name": "country"
      }
    ],
    "metrics": [
      {
        "name": "activeUsers"
      }
    ],
    "dateRanges": [
      {
        "startDate": "2024-05-01",
        "endDate": "2024-05-15"
      }
    ]
  },
  "reportMetadata": {
    "state": "ACTIVE",
    "beginCreatingTime": "2024-05-16T00:00:01.133612336Z",
    "creationQuotaTokensCharged": 6,
    "taskRowCount": 167,
    "errorMessage": "",
    "totalRowCount": 167
  }
}

Bạn có thể lấy trạng thái của tất cả các Tác vụ báo cáo bằng cách gọi phương thức reportTasks.list.

Truy xuất báo cáo đã tạo

Sau khi Report Task được tạo bằng phương thức reportTasks.create, hãy gọi phương thức reportTasks.query và chỉ định tên Report Task (chẳng hạn như properties/1234567/reportTasks/123).

Yêu cầu HTTP

POST https://analyticsdata.googleapis.com/v1alpha/properties/1234567/reportTasks/123:query

Nếu Report Task đã sẵn sàng, hệ thống sẽ trả về một phản hồi chứa báo cáo đã tạo:

Phản hồi HTTP

{
  "dimensionHeaders": [
    {
      "name": "country"
    }
  ],
  "metricHeaders": [
    {
      "name": "activeUsers",
      "type": "TYPE_INTEGER"
    }
  ],
  "rows": [

...

  ],
  "rowCount": 167,
  "metadata": {
    "currencyCode": "USD",
    "timeZone": "America/Los_Angeles"
  }
}