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

Khi 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.

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

Báo cáo tuỳ chỉnh sẽ có trong 72 giờ sau khi báo cáo đó sẵn sàng. 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 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 Tác vụ báo cáo. Trước tiên, bạn cần có một yêu cầu đến phương thức reportTasks.create để tạo một Tác vụ báo cáo. Sau đó, phương thức reportTasks.query sẽ đượ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ả phương thức của Data API phiên bản 1 đều yêu cầu bạn phải chỉ định mã nhận dạng tài sản Google Analytics bên trong đường dẫn yêu cầu URL ở 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 đã chỉ định.

Nếu bạn đ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 theo cách thủ công với đường dẫn URL yêu cầu. Hầu hết các ứ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 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. 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 Báo cáo tác vụ 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 để biết trạng thái của Báo cáo tác vụ và truy xuất báo cáo thu được.

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

Nhận trạng thái sẵn sàng của Báo cáo công việc

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 Báo cáo tác vụ (chẳng hạn như properties/1234567/reportTasks/123) mà bạn nhận được từ phản hồi reportTasks.create để chỉ định Báo cáo tác vụ.

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 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 tạo Tác vụ báo cá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 Tác vụ báo cáo đã 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"
  }
}