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 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 tư cách thành viên của đối tượng thay đổi để đảm bảo bạn đang sử dụng 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

Quá trình xử lý dữ liệu đối tượng trong một ngày và cập nhật gói thành viên sẽ mất một khoảng thời gian không cố định. Không có cách nào để chắc chắn rằng dữ liệu danh sách đối tượng sẽ đượ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 đối tượng của ngày hôm trước, còn vào một số ngày khác, danh sách đối tượng sẽ khác và chứa thêm một ngày thay đổi về trạng thái thành viên.

Danh sách đối tượng được tạo dựa trên dữ liệu sự kiện từ một ngày trước khi có 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 hệ thống cập nhật gói thành viên hằng ngày, thì danh sách đó 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 quá trình cập nhật gói thành viên hằng ngày diễn ra, thì danh sách đó sẽ sử dụng dữ liệu từ hôm qua.

Định kỳ thăm dò ý kiến 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ó thêm dữ liệu của một ngày. Nhờ đó, bạn không cần phải phỏng đoán thời điểm tạo Danh sách đối tượng mới. Thay vào đó, bạn có thể thăm dò ý kiến Danh sách đối tượng định kỳ trong suốt cả ngày để xem có dữ liệu bổ sung hay không.

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 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ể xem danh sách các phương diện được phương thức này hỗ trợ trong tài liệu về Giản đồ xuất đối tượng. Danh sách đối tượng chỉ chứa dữ liệu cho những phương diện được đề cập trong trường này.

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

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). Bạn có thể sử dụng tên này 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.

{
  "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ụ:

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

Hệ thống sẽ trả về một thực thể của RecurringAudienceList. 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 thực thể danh sách đối tượng được tạo cho danh sách đối tượng định kỳ này.

{
  "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ỳ 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ò ý kiến 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 về Async audience lists with webhooks để 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ệp Xuất đối tượng, hãy gọi phương thức audienceExports.query và chỉ định tên tệp 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.

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, hệ thống sẽ trả về một phản hồi chứa danh sách người dùng trong một đối tượng:

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