Tạo dữ liệu xuất đối tượng

Đối tượng trong Google Analytics giúp bạn phân đoạn người dùng theo những cách quan trọng đối với hoạt động kinh doanh của bạn. Với đối tượng, bạn có thể nhóm người dùng trang web hoặc ứng dụng của mình dựa trên các thuộc tính chung.

Bạn có thể xuất đối tượng, bao gồm cả ảnh chụp nhanh người dùng của đối tượng, bằng Data API.

Hãy tham khảo hướng dẫn Yêu cầu về dữ liệu xuất đối tượng để biết thông tin quan trọng về dữ liệu bạn thấy trong dữ liệu xuất đối tượng.

Tổng quan

Đưa ra các yêu cầu sau đây đối với Data API để tạo và truy vấn một yêu cầu xuất đối tượng:

  1. Gọi phương thức audienceExports.create để tạo một tệp xuất đối tượng.
  2. Gọi phương thức audienceExports.query để truy xuất người dùng trong đối tượng.

Để biết thêm thông tin, bạn có thể gọi audienceExports.get để truy xuất siêu dữ liệu cấu hình về một hoạt động xuất đối tượng cụ thể và audienceExports.list để liệt kê tất cả các hoạt động xuất đối tượng cho một tài sản cụ thể.

Chọn một pháp nhân báo cáo

Tất cả các phương thức Data API đều yêu cầu bạn chỉ định Giá trị nhận dạng tài sản Google Analytics trong đường dẫn yêu cầu URL, dưới dạng properties/GA_PROPERTY_ID. Ví dụ:

  POST  https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID/audienceExports

Báo cáo này được tạo dựa trên dữ liệu sự kiện của Google Analytics được thu thập trong tài sản Google Analytics đã chỉ định.

Nếu đang sử dụng một trong các thư viện ứng dụng Data API, bạn không cần thay đổi đường dẫn URL của yêu cầu. Hầu hết ứng dụng API đều cung cấp một tham số property. Tham số này yêu cầu một chuỗi dưới dạng properties/GA_PROPERTY_ID. Hãy xem Hướng dẫn bắt đầu nhanh để biết ví dụ về cách sử dụng thư viện ứng dụng.

Tạo bản xuất đối tượng

Để tạo một bản xuất đối tượng, hãy gọi phương thức audienceExports.create bằng đối tượng AudienceExport trong yêu cầu của bạn. 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.
  • 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 một lượt xuất đối tượng.

Sau đây là yêu cầu mẫu để tạo một lượt xuất đối tượng:

Yêu cầu HTTP

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

Phản hồi của phương thức audienceExports.create chứa tên của hoạt động xuất đối tượng trong trường name, ví dụ: properties/1234567/audienceExports/123. Sau đây là một phản hồi mẫu:

Phản hồi HTTP

{
  "response": {
    "@type": "type.googleapis.com/google.analytics.data.v1alpha.AudienceExport",
    "name": "properties/1234567/audienceExports/123",
    "audience": "properties/1234567/audiences/12345",
    "audienceDisplayName": "Purchasers",
    "dimensions": [
      {
        "dimensionName": "deviceId"
      }
    ],
    "state": "CREATING",
    "beginCreatingTime": "2023-06-22T23:35:28.787910949Z"
  }
}

Bạn có thể sử dụng name để truy vấn người dùng từ dữ liệu xuất đối tượng.

Truy vấn trạng thái sẵn sàng của hoạt động xuất đối tượng

Có thể mất vài phút để tạo bản xuất đối tượng sau lệnh gọi audienceExports.create.

Bạn có thể kiểm tra trạng thái sẵn sàng của một hoạt động xuất đối tượng bằng cách gọi phương thức audienceExports.get.

Sử dụng tên xuất đối tượng từ phản hồi audienceExports.create để chỉ định đối tượng xuất trong yêu cầu của bạn.

Sau đây là một yêu cầu mẫu:

Yêu cầu HTTP

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

Trạng thái sẵn sàng của một lượt xuất đối tượng được trả về trong trường state của phản hồi. Sau khi quá trình tạo tệp xuất đối tượng hoàn tất, trạng thái của tệp sẽ thay đổi từ CREATING thành ACTIVE.

Sau đây là một phản hồi mẫu:

Phản hồi HTTP

{
  "name": "properties/1234567/audienceExports/123",
  "audience": "properties/1234567/audiences/12345",
  "audienceDisplayName": "Purchasers",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ],
  "state": "CREATING",
  "beginCreatingTime": "2023-06-22T23:35:28.787910949Z"
}

Bạn có thể lấy trạng thái của tất cả các lượt xuất đối tượng bằng cách gọi phương thức audienceExports.list.

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

Sau khi tạo dữ liệu xuất đối tượng mục tiêu, hãy gọi phương thức audienceExports.query và chỉ định name của dữ liệu xuất đối tượng mục tiêu trong yêu cầu.

Sau đây là một yêu cầu mẫu:

Yêu cầu HTTP

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

Nếu quá trình xuất đối tượng đã sẵn sàng, lệnh gọi này sẽ trả về danh sách người dùng trong đối tượng.

Sau đây là một phản hồi mẫu:

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
}