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

Tài liệu này mô tả danh sách đối tượng định kỳ, tính năng nâng cao của Google Analytics Data API v1. Để xem 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 ra danh sách đối tượng hằng ngày dưới dạng thay đổi tư cách thành viên của đối tượng, để đả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 về 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ần nhiều thời gian để xử lý và cập nhật dữ liệu đối tượng trong một ngày gói thành viên. 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 một danh sách đối tượng vào cùng một thời điểm mỗi ngày, vào một số ngày, danh sách đối tượng sẽ giống nhau 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 gó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 dựa trên dữ liệu sự kiện từ một ngày trước sự kiện gần đây nhất thay đổi về tư cách thành viên. Nếu bạn tạo danh sách đối tượng trước gói thành viên hằng ngày cập nhật diễn ra, báo cáo sẽ sử dụng dữ liệu từ hai ngày trước đó. Nếu bạn tạo một danh sách đối tượng sau khi cập nhật gói thành viên hằng ngày, danh sách này sẽ sử dụng dữ liệu từ hôm qua.

Định kỳ thăm dò ý kiến cho 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 một ngày đã có. Điều này giúp bạn không phải phỏng đoán về việc quyết định thời điểm tạo báo cáo mới Danh sách đối tượng. Thay vào đó, bạn có thể thăm dò Danh sách đối tượng định kỳ với chi phí thấp trong suốt cả ngày để xem liệu có thêm dữ liệu nào 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 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 audience được định dạng là properties/{propertyId}/audiences/{audienceId}. Bạn có thể sử dụng audiences.list của API Quản trị Google Analytics phiên bản 1 để có được giá trị này. Chiến lược phát hành đĩa đơn Audience.name trường của phản hồi audiences.list có chứa tên đối tượng.
  • Danh sách hợp lệ các phương diện trong dimensions . Bạn có thể tìm thấy danh sách phương diện được hỗ trợ bằng phương pháp này 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à 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 vào trường name (chẳng hạn như properties/1234567/recurringAudienceLists/123), 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 chứa tên tài nguyên cho các bản sao danh sách đối tượng đã 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 của cuộc thăm dò ý kiến

Sử dụng 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ỳ. 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 đã 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 bản sao của RecurringAudienceList được trả về để phản hồi. Tệp này chứa siêu dữ liệu về cấu hình, bao gồm tên tài nguyên cho các bản sao danh sách đối tượng đã 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ả cá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ì thăm dò siêu dữ liệu cấu hình theo định kỳ về một bằng cách sử dụng recurringAudienceLists.get bạn có thể nhận không đồng bộ thông báo Webhook khi đối tượng danh sách sẽ xuất hiện.

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

Làm theo hướng dẫn dành cho 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 tệp xuất đối tượng

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

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