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. Để biết 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 danh sách đối tượng.

Danh sách đối tượng định kỳ tạo danh sách đối tượng hằng ngày khi tư cách thành viên của đố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 tĩnh gồm những người dùng trong đối tượng đó tại thời điểm tạo danh sách.

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

Có thể mất một khoảng thời gian khác nhau để xử lý dữ liệu về đối tượng và cập nhật gói thành viên trong một ngày. 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 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 như ngày hôm trước, và 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 thành viên.

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

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

Định kỳ thăm dò ý kiến về một 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 nữa. Điều này sẽ loại bỏ việc phỏng đoán về việc quyết định thời điểm tạo Danh sách đối tượng mới. Thay vào đó, bạn có thể thăm dò Danh sách đối tượng định kỳ với giá rẻ trong suốt cả ngày để xem có dữ liệu nào khác 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 cách sử dụng đối tượng RecurringAudienceList trong 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 properties/{propertyId}/audiences/{audienceId}. Bạn có thể sử dụng phương thức audiences.list của API Quản trị Google Analytics 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.
  • Danh sách phương diện hợp lệ trong trường dimensions. Bạn có thể tìm thấy danh sách các phương diện mà phương thức này hỗ trợ trong tài liệu về 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.

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

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). Trường này có thể được 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 còn chứa tên tài nguyên cho các phiên bản 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 cấu hình của 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 bản sao 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. Tệp này chứa siêu dữ liệu cấu hình, bao gồm cả tên tài nguyên cho các phiên bản 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ể sử dụng recurringAudienceLists.list để liệt kê tất cả danh sách đối tượng định kỳ của 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ì thăm dò siêu dữ liệu cấu hình định kỳ 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 được 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.

Làm theo tài liệu về WebhookNotification để biết thêm thông tin về cách sử dụng Webhook trong API Dữ liệu Google Analytics phiên bản 1.

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

Để truy xuất người dùng trong một tính năng Xuất đối tượng, hãy gọi phương thức audienceExports.query và chỉ định tên của tính nă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ì hệ thống sẽ trả về phản hồi chứa danh sách người dùng thuộc một đối tượng:

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
}