Nguyên tắc cơ bản về báo cáo nhiệm vụ

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

Tất cả người dùng có quyền đọc 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 tùy chỉnh.

Báo cáo tùy chỉnh sẽ có sẵn trong 72 giờ sau khi được tạo xong. 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 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 nhiệm vụ báo cáo. Trước tiên, bạn cần gửi yêu cầu đến phương thức reportTasks.create để tạo một nhiệm vụ báo cáo. Sau đó, phương thức reportTasks.query được dùng để truy xuất báo cáo tùy 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ả phương thức của API Dữ liệu phiên bản 1 đều yêu cầu bạn chỉ định mã 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 của Google Analytics được thu thập trong tài sản Google Analytics được chỉ định.

Nếu đang sử dụng một trong các thư viện ứng dụng API dữ liệu, bạn không cần phải thao tác thủ công với đường dẫn URL của yêu cầu. 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. 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 tác vụ báo cáo

Để tạo một 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 một yêu cầu. Bạn phải cung cấp các tham số sau:

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 Nhiệm vụ báo cáo trong trường name (chẳng hạn như properties/1234567/reportTasks/123). Bạn có thể sử dụng tên này trong các truy vấn tiếp theo để lấy trạng thái của một nhiệm 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"
    }
  }
}

Lấy trạng thái sẵn sàng của tác vụ 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 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 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 một tác vụ báo cáo đượ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 được 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í.

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ả nhiệm 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

Khi tác vụ báo cáo được tạo bằng phương thức reportTasks.create được tạo, 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 tác vụ báo cáo đã sẵn sàng, thì 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"
  }
}

Các bước tiếp theo