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 một 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 sử dụng để truy cập các báo cáo được tuỳ chỉnh bởi tất cả người dùng có quyền đọc dữ liệu Google Analytics của bạn thuộc tính này.

Một báo cáo tuỳ chỉnh sẽ có sẵn trong vòng 72 giờ sau khi sẵn sàng. Sau này một kỳ, thì tài nguyên công việc báo cáo tương ứng và nội dung trong đó sẽ là bị xoá tự động.

Tạo nhiệm vụ báo cáo

Google Analytics Data API v1 sử dụng phương pháp không đồng bộ để tạo Tác vụ báo cáo. Đầu tiên là yêu cầu đối với reportTasks.create để tạo Tác vụ báo cáo. Sau đó, reportTasks.query được sử 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 Mã nhận dạng tài sản Google Analytics được chỉ định bên 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 được tạo dựa trên sự kiện Google Analytics dữ liệu được thu thập trong tài sản Google Analytics được chỉ định.

Nếu bạn đang sử dụng một trong các thư viện ứng dụng Data API, bạn không cần thao tác đườ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 ở dạng properties/GA_PROPERTY_ID. Xem Hướng dẫn bắt đầu nhanh để biết các ví dụ khi 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 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 việc cần làm trong 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 Báo cáo Tên việc cần làm 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"
    }
  }
}

Nhận trạng thái sẵn sàng của Nhiệm vụ báo cáo

Có thể mất vài phút để tạo báo cáo sau khi 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 trong một phản hồi reportTasks.create để chỉ định Báo cáo việc cần làm.

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 state của một trường phản hồi. Sau khi tạo xong báo cáo, trạng thái của Nhiệm vụ báo cáo sẽ thay đổi từ CREATING thành ACTIVE.

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 đượ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ả Tác vụ báo cáo bằng cách gọi hàm 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 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ì 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"
  }
}