API Báo cáo Search Ads 360 cũ sẽ ngừng hoạt động và ngừng hoạt động từ ngày 30 tháng 6 năm 2024. Xin lưu ý rằng API Lượt chuyển đổi Search Ads 360 không bị ảnh hưởng và sẽ tiếp tục được hỗ trợ. Mọi hoạt động phát triển báo cáo mới đều phải sử dụng API Báo cáo Search Ads 360 mới.

Kể từ tháng 4 năm 2024, hệ thống sẽ trả về lỗi supportedApiVersion trong khi yêu cầu báo cáo. Xem chi tiết tại đây.

Bạn cũng nên di chuyển mọi hoạt động triển khai Search Ads 360 hiện có sang API mới. Hãy xem Bắt đầu và Hướng dẫn di chuyển API Báo cáo Search Ads 360 mới để biết thêm thông tin.

Trang này được dịch bởi Cloud Translation API.

Reports: request

Chèn yêu cầu báo cáo vào hệ thống báo cáo. Thử ngay.

Yêu cầu

Yêu cầu HTTP

POST https://www.googleapis.com/doubleclicksearch/v2/reports

Ủy quyền

Yêu cầu này cần được cho phép với phạm vi sau:

Phạm vi
`https://www.googleapis.com/auth/doubleclicksearch`

Để biết thêm thông tin, hãy xem trang xác thực và uỷ quyền.

Nội dung yêu cầu

Trong phần nội dung yêu cầu, hãy cung cấp dữ liệu với cấu trúc sau:

{
  "reportScope": {
    "agencyId": long,
    "advertiserId": long,
    "engineAccountId": long,
    "campaignId": long,
    "adGroupId": long,
    "keywordId": long,
    "adId": long
  },
  "reportType": string,
  "columns": [
    {
      "columnName": string,
      "savedColumnName": string,
      "customDimensionName": string,
      "customMetricName": string,
      "headerText": string,
      "startDate": string,
      "endDate": string,
      "groupByColumn": boolean,
      "platformSource": string,
      "productReportPerspective": string
    }
  ],
  "timeRange": {
    "startDate": string,
    "endDate": string,
    "changedMetricsSinceTimestamp": datetime,
    "changedAttributesSinceTimestamp": datetime
  },
  "filters": [
    {
      "column": {
        "columnName": string,
        "savedColumnName": string,
        "customDimensionName": string,
        "customMetricName": string,
        "headerText": string,
        "startDate": string,
        "endDate": string,
        "groupByColumn": boolean,
        "platformSource": string,
        "productReportPerspective": string
      },
      "operator": string,
      "values": [
        (value)
      ]
    }
  ],
  "orderBy": [
    {
      "column": {
        "columnName": string,
        "savedColumnName": string,
        "customDimensionName": string,
        "customMetricName": string,
        "headerText": string,
        "startDate": string,
        "endDate": string,
        "groupByColumn": boolean,
        "platformSource": string,
        "productReportPerspective": string
      },
      "sortOrder": string
    }
  ],
  "includeDeletedEntities": boolean,
  "includeRemovedEntities": boolean,
  "verifySingleTimeZone": boolean,
  "downloadFormat": string,
  "statisticsCurrency": string,
  "startRow": integer,
  "rowCount": integer,
  "maxRowsPerFile": integer
}

Tên tài sản	Giá trị	Mô tả
`reportScope`	`object`	reportScope là một tập hợp mã được dùng để xác định tập hợp con thực thể nào sẽ được trả về trong báo cáo. Bắt buộc phải cung cấp đầy đủ các mã nhận dạng ở cấp thấp nhất mà đại lý muốn giới thiệu.
`reportScope.agencyId`	`long`	ID đại lý DS.
`reportScope.advertiserId`	`long`	ID nhà quảng cáo DS.
`reportScope.engineAccountId`	`long`	Mã tài khoản công cụ DS.
`reportScope.campaignId`	`long`	Mã chiến dịch DS.
`reportScope.adGroupId`	`long`	Mã nhóm quảng cáo DS.
`reportScope.keywordId`	`long`	ID từ khóa DS.
`reportScope.adId`	`long`	ID quảng cáo DS.
`reportType`	`string`	Xác định loại hàng được trả về trong báo cáo. Ví dụ: nếu bạn chỉ định `reportType: keyword`, mỗi hàng trong báo cáo sẽ chứa dữ liệu về một từ khoá. Hãy xem phần tham khảo Loại báo cáo để biết các cột có sẵn cho mỗi loại.
`columns[]`	`list`	Các cột bạn muốn đưa vào báo cáo. Dữ liệu này bao gồm cả cột DoubleClick Search và cột đã lưu. Đối với cột DoubleClick Search, chỉ cần có thông số `columnName`. Đối với các cột đã lưu, bạn chỉ cần sử dụng tham số `savedColumnName`. Không thể đặt cả `columnName` và `savedColumnName` trong cùng một khổ thơ. Số cột tối đa cho mỗi yêu cầu là 300.
`columns[].columnName`	`string`	Tên của một cột DoubleClick Search để đưa vào báo cáo.
`columns[].savedColumnName`	`string`	Tên của một cột đã lưu để đưa vào báo cáo. Báo cáo phải nằm trong phạm vi nhà quảng cáo hoặc thấp hơn và cột đã lưu này phải được tạo trong giao diện người dùng DoubleClick Search.
`columns[].headerText`	`string`	Văn bản dùng để xác định cột này trong kết quả báo cáo; mặc định là `columnName` hoặc `savedColumnName` khi không được chỉ định. Bạn có thể sử dụng công cụ này để ngăn xung đột giữa các cột DoubleClick Search và các cột đã lưu có cùng tên.
`columns[].startDate`	`string`	Ngày trọn gói ở định dạng YYYY-MM-DD. Khi được cung cấp, thông tin này sẽ ghi đè phạm vi thời gian tổng thể của báo cáo chỉ cho cột này. Phải được cung cấp cùng với `endDate`.
`columns[].endDate`	`string`	Ngày trọn gói ở định dạng YYYY-MM-DD. Khi được cung cấp, thông tin này sẽ ghi đè phạm vi thời gian tổng thể của báo cáo chỉ cho cột này. Phải được cung cấp cùng với `startDate`.
`columns[].groupByColumn`	`boolean`	Chỉ báo cáo đồng bộ. Hãy đặt thành `true` để nhóm theo cột này. Giá trị mặc định là `false`.
`timeRange`	`object`	Nếu các chỉ số được yêu cầu trong một báo cáo, đối số này sẽ được dùng để hạn chế các chỉ số trong một phạm vi thời gian cụ thể.
`timeRange.startDate`	`string`	Ngày trọn gói ở định dạng YYYY-MM-DD.
`timeRange.endDate`	`string`	Ngày trọn gói ở định dạng YYYY-MM-DD.
`timeRange.changedMetricsSinceTimestamp`	`datetime`	Dấu thời gian UTC tổng hợp ở định dạng RFC, ví dụ: `2013-07-16T10:16:23.555Z`. Xem thêm thông tin tham khảo về cách hoạt động của báo cáo chỉ số được thay đổi.
`timeRange.changedAttributesSinceTimestamp`	`datetime`	Dấu thời gian UTC tổng hợp ở định dạng RFC, ví dụ: `2013-07-16T10:16:23.555Z`. Xem thêm tài liệu tham khảo về cách hoạt động của báo cáo thuộc tính đã thay đổi.
`filters[]`	`list`	Danh sách các bộ lọc sẽ áp dụng cho báo cáo. Số lượng bộ lọc tối đa cho mỗi yêu cầu là 300.
`filters[].column`	`nested object`	Cột để thực hiện bộ lọc. Đây có thể là cột DoubleClick Search hoặc cột đã lưu.
`filters[].column.columnName`	`string`	Tên của một cột DoubleClick Search để đưa vào báo cáo.
`filters[].column.savedColumnName`	`string`	Tên của một cột đã lưu để đưa vào báo cáo. Báo cáo phải nằm trong phạm vi nhà quảng cáo hoặc thấp hơn và cột đã lưu này phải được tạo trong giao diện người dùng DoubleClick Search.
`filters[].operator`	`string`	Toán tử để sử dụng trong bộ lọc. Hãy tham khảo bộ lọc để biết danh sách các toán tử có sẵn.
`filters[].values[]`	`list`	Danh sách các giá trị để lọc giá trị của cột. Số lượng giá trị bộ lọc tối đa cho mỗi yêu cầu là 300.
`orderBy[]`	`list`	Chỉ báo cáo đồng bộ. Danh sách các cột và hướng dẫn xác định cách sắp xếp sẽ được thực hiện trên các hàng báo cáo. Số lượng đơn đặt hàng tối đa mỗi yêu cầu là 300.
`orderBy[].column`	`nested object`	Cột để sắp xếp. Đây có thể là cột do DoubleClick Search xác định hoặc cột đã lưu.
`orderBy[].column.columnName`	`string`	Tên của một cột DoubleClick Search để đưa vào báo cáo.
`orderBy[].column.savedColumnName`	`string`	Tên của một cột đã lưu để đưa vào báo cáo. Báo cáo phải nằm trong phạm vi nhà quảng cáo hoặc thấp hơn và cột đã lưu này phải được tạo trong giao diện người dùng DoubleClick Search.
`orderBy[].sortOrder`	`string`	Hướng sắp xếp, đó là `ascending` hoặc `descending`.
`includeDeletedEntities`	`boolean`	Xác định xem có nên đưa các thực thể đã xoá vào báo cáo hay không. Giá trị mặc định là `false`. Đã ngừng sử dụng, vui lòng sử dụng `includeRemovedEntities`.
`verifySingleTimeZone`	`boolean`	Nếu `true`, báo cáo sẽ chỉ được tạo nếu tất cả dữ liệu thống kê được yêu cầu được lấy từ một múi giờ duy nhất. Giá trị mặc định là `false`.
`downloadFormat`	`string`	Định dạng mà báo cáo được trả về. Hiện tại, chúng tôi hỗ trợ `csv` hoặc `tsv`.
`statisticsCurrency`	`string`	Chỉ định đơn vị tiền tệ mà tiền sẽ được trả lại. Các giá trị có thể là: `usd`, `agency` (có hiệu lực nếu báo cáo nằm trong phạm vi đại lý trở xuống), `advertiser` (có hiệu lực nếu báo cáo nằm trong phạm vi * nhà quảng cáo trở xuống) hoặc `account` (có hiệu lực nếu báo cáo nằm trong phạm vi tài khoản công cụ hoặc thấp hơn).
`startRow`	`integer`	Chỉ báo cáo đồng bộ. Chỉ mục dựa trên 0 của hàng đầu tiên sẽ trả về. Giá trị được chấp nhận là từ `0` đến `50000`, bao gồm cả hai giá trị này. Mặc định là `0`.
`rowCount`	`integer`	Chỉ báo cáo đồng bộ. Số hàng tối đa cần trả về; hàng bổ sung bị loại bỏ. Giá trị được chấp nhận là từ `0` đến `10000`, bao gồm cả hai giá trị này. Mặc định là `10000`.
`maxRowsPerFile`	`integer`	Chỉ báo cáo không đồng bộ. Số hàng tối đa cho mỗi tệp báo cáo. Một báo cáo lớn được chia thành nhiều tệp dựa trên trường này. Giá trị được chấp nhận là từ `1000000` đến `100000000`, bao gồm cả hai giá trị này.
`includeRemovedEntities`	`boolean`	Xác định xem có nên đưa các thực thể đã xoá vào báo cáo hay không. Giá trị mặc định là `false`.
`columns[].customDimensionName`	`string`	Phân đoạn báo cáo theo phương diện tùy chỉnh. Báo cáo phải được giới hạn cho một nhà quảng cáo hoặc thấp hơn và phương diện tùy chỉnh phải được thiết lập trong DoubleClick Search. Tên phương diện tùy chỉnh, xuất hiện trong DoubleClick Search, có phân biệt chữ hoa chữ thường. Nếu được sử dụng trong báo cáo lượt chuyển đổi, thì trường này sẽ trả về giá trị của phương diện tùy chỉnh đã chỉ định cho lượt chuyển đổi nhất định (nếu có). Cột này không phân đoạn báo cáo lượt chuyển đổi.
`columns[].platformSource`	`string`	Nền tảng được dùng để cung cấp dữ liệu cho phương diện tuỳ chỉnh. Các giá trị được chấp nhận là "lũ lụt".
`filters[].column.customDimensionName`	`string`	Phân đoạn báo cáo theo phương diện tùy chỉnh. Báo cáo phải được giới hạn cho một nhà quảng cáo hoặc thấp hơn và phương diện tùy chỉnh phải được thiết lập trong DoubleClick Search. Tên phương diện tùy chỉnh, xuất hiện trong DoubleClick Search, có phân biệt chữ hoa chữ thường. Nếu được sử dụng trong báo cáo lượt chuyển đổi, thì trường này sẽ trả về giá trị của phương diện tùy chỉnh đã chỉ định cho lượt chuyển đổi nhất định (nếu có). Cột này không phân đoạn báo cáo lượt chuyển đổi.
`filters[].column.headerText`	`string`	Văn bản dùng để xác định cột này trong kết quả báo cáo; mặc định là `columnName` hoặc `savedColumnName` khi không được chỉ định. Bạn có thể sử dụng công cụ này để ngăn xung đột giữa các cột DoubleClick Search và các cột đã lưu có cùng tên.
`filters[].column.startDate`	`string`	Ngày trọn gói ở định dạng YYYY-MM-DD. Khi được cung cấp, thông tin này sẽ ghi đè phạm vi thời gian tổng thể của báo cáo chỉ cho cột này. Phải được cung cấp cùng với `endDate`.
`filters[].column.endDate`	`string`	Ngày trọn gói ở định dạng YYYY-MM-DD. Khi được cung cấp, thông tin này sẽ ghi đè phạm vi thời gian tổng thể của báo cáo chỉ cho cột này. Phải được cung cấp cùng với `startDate`.
`filters[].column.groupByColumn`	`boolean`	Chỉ báo cáo đồng bộ. Hãy đặt thành `true` để nhóm theo cột này. Giá trị mặc định là `false`.
`filters[].column.platformSource`	`string`	Nền tảng được dùng để cung cấp dữ liệu cho phương diện tuỳ chỉnh. Các giá trị được chấp nhận là "lũ lụt".
`orderBy[].column.customDimensionName`	`string`	Phân đoạn báo cáo theo phương diện tùy chỉnh. Báo cáo phải được giới hạn cho một nhà quảng cáo hoặc thấp hơn và phương diện tùy chỉnh phải được thiết lập trong DoubleClick Search. Tên phương diện tùy chỉnh, xuất hiện trong DoubleClick Search, có phân biệt chữ hoa chữ thường. Nếu được sử dụng trong báo cáo lượt chuyển đổi, thì trường này sẽ trả về giá trị của phương diện tùy chỉnh đã chỉ định cho lượt chuyển đổi nhất định (nếu có). Cột này không phân đoạn báo cáo lượt chuyển đổi.
`orderBy[].column.headerText`	`string`	Văn bản dùng để xác định cột này trong kết quả báo cáo; mặc định là `columnName` hoặc `savedColumnName` khi không được chỉ định. Bạn có thể sử dụng công cụ này để ngăn xung đột giữa các cột DoubleClick Search và các cột đã lưu có cùng tên.
`orderBy[].column.startDate`	`string`	Ngày trọn gói ở định dạng YYYY-MM-DD. Khi được cung cấp, thông tin này sẽ ghi đè phạm vi thời gian tổng thể của báo cáo chỉ cho cột này. Phải được cung cấp cùng với `endDate`.
`orderBy[].column.endDate`	`string`	Ngày trọn gói ở định dạng YYYY-MM-DD. Khi được cung cấp, thông tin này sẽ ghi đè phạm vi thời gian tổng thể của báo cáo chỉ cho cột này. Phải được cung cấp cùng với `startDate`.
`orderBy[].column.groupByColumn`	`boolean`	Chỉ báo cáo đồng bộ. Hãy đặt thành `true` để nhóm theo cột này. Giá trị mặc định là `false`.
`orderBy[].column.platformSource`	`string`	Nền tảng được dùng để cung cấp dữ liệu cho phương diện tuỳ chỉnh. Các giá trị được chấp nhận là "lũ lụt".
`columns[].customMetricName`	`string`	Tên của một chỉ số tuỳ chỉnh cần đưa vào báo cáo. Báo cáo phải được giới hạn cho một nhà quảng cáo trở xuống và chỉ số tùy chỉnh phải được thiết lập trong DoubleClick Search. Tên chỉ số tuỳ chỉnh xuất hiện trong DoubleClick Search có phân biệt chữ hoa chữ thường.
`filters[].column.customMetricName`	`string`	Tên của một chỉ số tuỳ chỉnh cần đưa vào báo cáo. Báo cáo phải được giới hạn cho một nhà quảng cáo trở xuống và chỉ số tùy chỉnh phải được thiết lập trong DoubleClick Search. Tên chỉ số tuỳ chỉnh xuất hiện trong DoubleClick Search có phân biệt chữ hoa chữ thường.
`orderBy[].column.customMetricName`	`string`	Tên của một chỉ số tuỳ chỉnh cần đưa vào báo cáo. Báo cáo phải được giới hạn cho một nhà quảng cáo trở xuống và chỉ số tùy chỉnh phải được thiết lập trong DoubleClick Search. Tên chỉ số tuỳ chỉnh xuất hiện trong DoubleClick Search có phân biệt chữ hoa chữ thường.
`columns[].productReportPerspective`	`string`	Chỉ trả về những chỉ số cho một loại hoạt động sản phẩm cụ thể. Các giá trị được chấp nhận là: "`sold`": chỉ trả về những chỉ số cho các sản phẩm đã bán được "`advertised`": chỉ trả về những chỉ số cho các sản phẩm được quảng cáo trong chiến dịch Mua sắm và có thể hoặc không được bán
`filters[].column.productReportPerspective`	`string`	Chỉ trả về những chỉ số cho một loại hoạt động sản phẩm cụ thể. Các giá trị được chấp nhận là: "`sold`": chỉ trả về những chỉ số cho các sản phẩm đã bán được "`advertised`": chỉ trả về những chỉ số cho các sản phẩm được quảng cáo trong chiến dịch Mua sắm và có thể hoặc không được bán
`orderBy[].column.productReportPerspective`	`string`	Chỉ trả về những chỉ số cho một loại hoạt động sản phẩm cụ thể. Các giá trị được chấp nhận là: "`sold`": chỉ trả về những chỉ số cho các sản phẩm đã bán được "`advertised`": chỉ trả về những chỉ số cho các sản phẩm được quảng cáo trong chiến dịch Mua sắm và có thể hoặc không được bán

Phản hồi

Nếu thành công, phương thức này sẽ trả về một Tài nguyên báo cáo trong nội dung phản hồi.

Hãy dùng thử!

Hãy dùng API Explorer bên dưới để gọi phương thức này trên dữ liệu trực tiếp và xem phản hồi. Ngoài ra, hãy dùng thử Trình khám phá độc lập.