Danh sách đối tượng định kỳ

Tài liệu này mô tả danh sách đối tượng định kỳ, đây là một tính năng nâng cao của API Dữ liệu Google Analytics phiên bản 1. Để xem thông tin giới thiệu về tính năng xuất danh sách đối tượng, hãy xem hướng dẫn cơ bản về tính năng xuất đối tượng.

Danh sách đối tượng định kỳ tạo danh sách đối tượng hằng ngày khi thành viên đối tượng thay đổi, để đảm bảo bạn đang làm việc với dữ liệu mới nhất.

Danh sách đối tượng thông thường (không định kỳ) là danh sách cố định gồm những người dùng trong đối tượng tại thời điểm danh sách được tạo.

Tạo danh sách đối tượng mới mỗi ngày

Thời gian xử lý dữ liệu đối tượng trong một ngày và cập nhật tư cách thành viên có thể thay đổi. Không có cách nào để đảm bảo rằng dữ liệu danh sách đối tượng được cập nhật trong vòng 24 giờ.

Ví dụ: ngay cả khi bạn yêu cầu danh sách đối tượng vào cùng một thời điểm mỗi ngày, thì vào một số ngày, danh sách đối tượng sẽ giống với danh sách của ngày hôm trước, còn vào những ngày khác, danh sách đối tượng sẽ khác và có thêm một ngày thay đổi về trạng thái thành viên.

Tạo Danh sách đối tượng mới mỗi ngày

Danh sách đối tượng dựa trên dữ liệu sự kiện từ một ngày trước khi có những thay đổi gần đây nhất về thành viên. Nếu bạn tạo danh sách đối tượng trước khi có các bản cập nhật hằng ngày về thành viên, thì danh sách đó sẽ sử dụng dữ liệu từ 2 ngày trước. Nếu bạn tạo danh sách đối tượng sau khi có thông tin cập nhật hằng ngày về thành viên, thì danh sách đó sẽ sử dụng dữ liệu của ngày hôm qua.

Định kỳ thăm dò ý kiến về danh sách đối tượng định kỳ

Danh sách đối tượng định kỳ chỉ tạo Danh sách đối tượng khi có dữ liệu của một ngày bổ sung. Điều này giúp bạn không phải đoán xem khi nào nên tạo Danh sách đối tượng mới. Thay vào đó, bạn có thể thăm dò ý kiến về Danh sách đối tượng định kỳ một cách rẻ tiền trong suốt cả ngày để xem có dữ liệu bổ sung hay không.

Định kỳ thăm dò một Danh sách đối tượng định kỳ trong ngày

Tạo Danh sách đối tượng định kỳ

Để tạo danh sách đối tượng định kỳ, hãy gọi phương thức recurringAudienceLists.create bằng đối tượng RecurringAudienceList trong một yêu cầu. Các tham số sau đây là bắt buộc:

  • Tên đối tượng hợp lệ trong trường audience, được định dạng là properties/{propertyId}/audiences/{audienceId}. Bạn có thể sử dụng phương thức audiences.list của Google Analytics Admin API phiên bản 1 để lấy giá trị này. Trường Audience.name của phản hồi audiences.list chứa tên đối tượng.
  • Một danh sách phương diện hợp lệ trong trường dimensions. Bạn có thể xem danh sách các phương diện được phương thức này hỗ trợ trong tài liệu Giản đồ xuất đối tượng. Chỉ dữ liệu cho các phương diện được đề cập trong trường này mới được đưa vào Danh sách đối tượng.

Sau đây là một yêu cầu mẫu để tạo danh sách đối tượng định kỳ:

Yêu cầu HTTP

POST https://analyticsdata.googleapis.com/v1alpha/properties/1234567/recurringAudienceLists
{
  "audience": "properties/1234567/audiences/12345",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ]
}

Phản hồi của phương thức recurringAudienceLists.create chứa tên trong trường name (chẳng hạn như properties/1234567/recurringAudienceLists/123), có thể dùng trong các truy vấn tiếp theo để truy xuất siêu dữ liệu cấu hình cho danh sách đối tượng định kỳ này. Ngoài ra, siêu dữ liệu cấu hình chứa tên tài nguyên cho các thực thể danh sách đối tượng được tạo cho danh sách đối tượng định kỳ này.

Phản hồi HTTP

{
  "name": "properties/1234567/recurringAudienceLists/123",
  "audience": "properties/1234567/audiences/12345",
  "audienceDisplayName": "Purchasers",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ],
  "activeDaysRemaining": 180,
  "audienceLists": [
    "properties/1234567/audienceLists/45678"
  ]
}

Siêu dữ liệu về cấu hình cuộc thăm dò ý kiến

Sử dụng phương thức recurringAudienceLists.get để truy xuất siêu dữ liệu cấu hình về một danh sách đối tượng định kỳ cụ thể. Siêu dữ liệu cấu hình chứa tên tài nguyên cho các thực thể danh sách đối tượng được tạo cho danh sách đối tượng định kỳ này.

Ví dụ:

Yêu cầu HTTP

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

Một thực thể của RecurringAudienceList sẽ được trả về để phản hồi. Nội dung này chứa siêu dữ liệu cấu hình, bao gồm tên tài nguyên cho các thực thể danh sách đối tượng được tạo cho danh sách đối tượng định kỳ này.

Phản hồi HTTP

{
  "name": "properties/1234567/recurringAudienceLists/123",
  "audience": "properties/1234567/audiences/12345",
  "audienceDisplayName": "Purchasers",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ],
  "activeDaysRemaining": 180,
  "audienceLists": [
    "properties/1234567/audienceLists/45678"
  ]
}

Bạn có thể dùng recurringAudienceLists.list để liệt kê tất cả danh sách đối tượng định kỳ cho một tài sản.

Sử dụng Webhook để nhận thông báo không đồng bộ về danh sách đối tượng mới

Thay vì định kỳ thăm dò siêu dữ liệu cấu hình về một danh sách đối tượng định kỳ cụ thể bằng phương thức recurringAudienceLists.get, bạn có thể nhận thông báo Webhook không đồng bộ khi có danh sách đối tượng.

Để định cấu hình thông báo Webhook, hãy chỉ định trường webhookNotification khi tạo danh sách đối tượng định kỳ mới.

Hãy làm theo hướng dẫn Async audience lists with webhooks để biết thêm thông tin về cách sử dụng Webhook trong Google Analytics Data API phiên bản 1.

Truy xuất người dùng trong một tệp xuất đối tượng

Để truy xuất người dùng trong một hoạt động Xuất đối tượng, hãy gọi phương thức audienceExports.query và chỉ định tên của hoạt động Xuất đối tượng được truy xuất từ siêu dữ liệu cấu hình do recurringAudienceLists.get hoặc recurringAudienceLists.list cung cấp.

Yêu cầu HTTP

POST https://analyticsdata.googleapis.com/v1beta/properties/1234567/audienceExports/123:query

Nếu tính năng Xuất đối tượng đã sẵn sàng, thì một phản hồi chứa danh sách người dùng trong một đối tượng sẽ được trả về:

Phản hồi HTTP

{
  "audienceExport": {
    "name": "properties/1234567/audienceExports/123",
    "audience": "properties/1234567/audiences/12345",
    "audienceDisplayName": "Purchasers",
    "dimensions": [
      {
        "dimensionName": "deviceId"
      }
    ],
    "state": "ACTIVE",
    "beginCreatingTime": "2023-06-22T23:35:28.787910949Z"
  },
  "audienceRows": [
    {
      "dimensionValues": [
        {
          "value": "1000276123.1681742376"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1000374452.1668627377"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1000391956.1652750758"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1000410539.1682018694"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1000703969.1666725875"
        }
      ]
    }
  ],
  "rowCount": 5
}