Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Truy vấn dữ liệu báo cáo

Phương thức reportData.query cung cấp một cách đồng bộ để truy xuất dữ liệu báo cáo. Không giống như dịch vụ Reports tiêu chuẩn (tạo báo cáo dựa trên tệp CSV hoặc Excel), phương thức này trả về dữ liệu JSON có cấu trúc trực tiếp trong phản hồi. Bạn không cần phải xác định, tạo và lưu tài nguyên Report trước đó, nhờ vậy, phương thức này rất phù hợp để truy xuất và khám phá dữ liệu theo thời gian thực.

Tổng quan

Hãy tham khảo hướng dẫn này để làm quen với việc sử dụng điểm cuối này nhằm truy vấn dữ liệu báo cáo của Campaign Manager 360.

Chuẩn bị yêu cầu

Tạo ReportDataQueryRequest chỉ định các phương diện, chỉ số, phạm vi ngày, bộ lọc và tiêu chí sắp xếp.

REST

{
  "body": {
    "dateRange": "LAST_7_DAYS",
    "dimensionNames": [
      "advertiser",
      "campaign"
    ],
    "metricNames": [
      "impressions",
      "clicks"
    ],
    "sortBys": [
      {
        "name": "clicks",
        "sortOrder": "DESCENDING"
      }
    ],
    "maxResults": 100
  }
}

dateRange: Đối tượng DateRange chỉ định khoảng thời gian cho truy vấn. Đây có thể là phạm vi ngày tuỳ chỉnh hoặc phạm vi ngày tương đối.
dimensionNames: Danh sách tên phương diện tiêu chuẩn để nhóm theo.
metricNames: Bắt buộc. Danh sách tên chỉ số tiêu chuẩn cần đưa vào.
dimensionFilters: Danh sách các đối tượng DimensionValue dùng để lọc dữ liệu báo cáo. Sử dụng danh sách này để giới hạn kết quả truy vấn theo các giá trị cụ thể của một phương diện.
sortBys: Cấu hình sắp xếp cho phương diện hoặc chỉ số. Mỗi cấu hình bao gồm tên trường và thứ tự sắp xếp.
maxResults: Số hàng tối đa cần trả về trên mỗi trang (Mặc định: 100, Tối đa: 1000).

Phân trang

Trường maxResults kiểm soát số lượng kết quả được trả về trong một phản hồi. Ví dụ: nếu bạn đặt maxResults thành 10, thì API sẽ trả về tối đa 10 kết quả. Có thể API sẽ trả về ít hơn 10 kết quả nếu có ít hơn 10 kết quả phù hợp với yêu cầu của bạn.

Nếu có thêm kết quả, phản hồi sẽ bao gồm nextPageToken. Để truy xuất trang kết quả tiếp theo, hãy gửi lại cùng một yêu cầu với trường pageToken được đặt thành mã thông báo này. Giữ nguyên tất cả các tham số yêu cầu khác.

Gửi yêu cầu

Gửi yêu cầu HTTP POST đến reportdata/query điểm cuối:

POST https://dfareporting.googleapis.com/dfareporting/v5/userprofiles/{profileId}/reportdata/query

Đảm bảo yêu cầu của bạn được xác thực bằng thông tin đăng nhập OAuth 2.0 tiêu chuẩn và các phạm vi cần thiết. Xem phần Uỷ quyền cho các yêu cầu để biết thêm thông tin.

Phản hồi thành công

Truy vấn thành công sẽ trả về phản hồi 200 OK HTTP với tải trọng JSON chứa columnHeaders, rows và totalRow.

{
  "columnHeaders": [
    { "name": "advertiser", "type": "DIMENSION" },
    { "name": "campaign", "type": "DIMENSION" },
    { "name": "impressions", "type": "METRIC" },
    { "name": "clicks", "type": "METRIC" }
  ],
  "rows": [
    {
      "values": [ "Test Advertiser", "Summer Campaign", "148672", "420" ]
    },
    {
      "values": [ "Test Advertiser", "Fall Campaign", "2159", "2" ]
    }
  ],
  "totalRow": {
    "values": [ "", "", "150831", "422" ]
  },
  "nextPageToken": "1234567890"
}

columnHeaders: Tên và loại (DIMENSION hoặc METRIC) của các trường được trả về.
rows: Danh sách các đối tượng ReportDataRow chứa kết quả truy vấn. Các giá trị chuỗi trong mỗi hàng sẽ căn chỉnh theo vị trí với columnHeaders.
totalRow: Một hàng tổng hợp duy nhất đại diện cho tổng của tất cả các chỉ số phù hợp. Các trường phương diện và chỉ số không thể được tổng hợp (ví dụ: các chỉ số về phạm vi tiếp cận như uniqueReachTotalReach) sẽ trống ("") trong hàng này.
nextPageToken: Mã thông báo được dùng trong yêu cầu tiếp theo để truy xuất trang tiếp theo nếu có thêm hàng.

Độ trễ và thời gian chờ

Vì đây là điểm cuối đồng bộ, nên các truy vấn sẽ thực thi ngay lập tức và dữ liệu được trả về trực tiếp trong phản hồi (tối đa theo hạn mức phân trang maxResults). Các truy vấn có thời gian thực thi tối đa là 60 giây. Nếu một truy vấn vượt quá hạn mức này, API sẽ chấm dứt thao tác và trả về lỗi HTTP 503 Service Unavailable.

Nếu bạn gặp lỗi này, hãy thử thu hẹp phạm vi ngày, thu hẹp bộ lọc (chẳng hạn như lọc theo nhà quảng cáo hoặc chiến dịch cụ thể) hoặc giảm số lượng phương diện và chỉ số được yêu cầu. Ngoài ra, hãy chạy Report bằng reports.run để tạo tệp báo cáo có thể tải xuống một cách không đồng bộ.

Hạn mức và ràng buộc về truy vấn

Điểm cuối reportdata.query áp dụng một số hạn mức để đảm bảo phản hồi đáng tin cậy. Các yêu cầu vi phạm những ràng buộc này sẽ bị từ chối kèm theo phản hồi HTTP 400 Bad Request.

Hạn mức phạm vi ngày

Đối với phạm vi ngày tuỳ chỉnh, startDate phải nằm trong khoảng thời gian có sẵn dữ liệu cho loại dữ liệu báo cáo được yêu cầu. Để biết thông tin chi tiết, hãy xem phần Tính sẵn có của dữ liệu.

Ràng buộc về chỉ số và phương diện

Bạn phải cung cấp ít nhất một chỉ số trong metricNames.
Các chỉ số và phương diện trong danh sách metricNames và dimensionNames phải là duy nhất.
Bạn không thể sử dụng các chỉ số và phương diện được gắn nhãn Chỉ tải xuống trong các truy vấn này.

Hạn mức

Các yêu cầu đến điểm cuối này sẽ tiêu thụ các hạn mức sau:

Hạn mức người dùng: 120 yêu cầu mỗi phút trên mỗi người dùng (2 QPS)
Hạn mức hằng ngày trên mỗi dự án: 10.000 yêu cầu mỗi ngày trên mỗi dự án

Các yêu cầu vượt quá những hạn mức này sẽ không thành công và trả về lỗi HTTP 429 Too Many Requests. Nếu bạn phân trang kết quả, thì mỗi yêu cầu cho một trang mới (sử dụng tham số pageToken) sẽ được tính là một truy vấn riêng và tiêu thụ hạn mức này.

Truy vấn dữ liệu báo cáo Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.