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

Bằng cách sử dụng 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.

Bạn 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 dành cho tất cả người dùng có quyền đọc đối với tài sản Google Analytics của bạn.

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

Tạo tác vụ báo cáo

Google Analytics Data API phiên bản 1 sử dụng phương pháp không đồng bộ để tạo Tác vụ báo cáo. Trước tiên, bạn cần yêu cầu phương thức reportTasks.create để tạo 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 thực thể 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 phải chỉ định giá trị nhận dạng thuộc tính Google Analytics 4 bên trong đường dẫn yêu cầu URL ở dạng properties/GA4_PROPERTY_ID, chẳng hạn như:

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

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

Nếu đang sử dụng một trong các thư viện ứng dụng Data API, thì bạn không cần phải thao tác trên đườ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 dự kiến sẽ có một chuỗi ở dạng properties/GA4_PROPERTY_ID. Hãy xem Hướng dẫn bắt đầu nhanh để biết các ví dụ về cách sử dụng thư viện ứng dụng.

Yêu cầu tạo Tác vụ báo cáo

Để tạo Tác vụ báo cáo, hãy gọi phương thức reportTasks.create bằng cách sử dụng đối tượng ReportTask trong 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 tác vụ báo cáo trong trường name (chẳng hạn như properties/1234567/reportTasks/123), có thể được dùng trong các truy vấn tiếp theo để lấy trạng thái của Tác vụ báo cáo 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"
    }
  }
}

Tải trạng thái sẵn sàng cho Nhiệm vụ trong báo cáo

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 Tác vụ báo cáo bằng cách gọi phương thức reportTasks.get.

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

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 cho Tác vụ báo cáo được trả về trong trường state của 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 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ố hàng và số lượng mã thông báo hạn mức được tính.

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ể biết trạng thái của tất 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 Tác vụ báo cáo đượ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 Tác vụ báo cáo (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 Nhiệm vụ báo cáo đã sẵn sàng, một phản hồi chứa báo cáo đã tạo sẽ được trả về:

Phản hồi HTTP

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

...

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