API Báo cáo Search Ads 360 mới hiện đã ra mắt. Tham gia nhóm Google searchads-api-announcements để luôn được cập nhật về những cải tiến và bản phát hành sắp tới.

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

Truyền trực tuyến báo cáo

Có hai phương thức để truy xuất thực thể và báo cáo dữ liệu bằng API Báo cáo Search Ads 360.

Hướng dẫn này chủ yếu tập trung vào việc truyền trực tuyến dữ liệu từ SearchAds360Service. Dưới đây là những điểm khác biệt cơ bản giữa hai phương thức truy xuất dữ liệu:

	SearchAds360Service.SearchStream	SearchAds360Service.Search
Phù hợp với mã phát hành công khai	Có	Có
Dịch vụ	`SearchAds360Service`	`SearchAds360Service`
Trường hợp	Tìm nạp đối tượng và báo cáo	Tìm nạp đối tượng và báo cáo
Phản hồi	Luồng đối tượng `SearchAds360Row`	Các trang của đối tượng `SearchAds360Row`
Các trường của phản hồi	Chỉ những thuộc tính được chỉ định trong truy vấn	Chỉ những thuộc tính được chỉ định trong truy vấn
Giới hạn hằng ngày	Xem các giới hạn và hạn mức API.	Xem các giới hạn và hạn mức API.

SearchStream so với Search

Mặc dù Search có thể gửi nhiều yêu cầu phân trang để tải toàn bộ báo cáo xuống, nhưng SearchStream chỉ gửi một yêu cầu và bắt đầu kết nối liên tục với API Báo cáo Search Ads 360, bất kể kích thước báo cáo.

Đối với SearchStream, các gói dữ liệu bắt đầu tải xuống ngay lập tức với toàn bộ kết quả được lưu vào bộ đệm dữ liệu. Mã của bạn có thể bắt đầu đọc dữ liệu được lưu vào bộ đệm mà không cần phải đợi toàn bộ luồng kết thúc.

Bằng cách loại bỏ thời gian mạng khứ hồi cần thiết để yêu cầu từng trang riêng lẻ của phản hồi Search, tuỳ thuộc vào ứng dụng của bạn, SearchStream có thể cải thiện hiệu suất so với phân trang, đặc biệt là đối với các báo cáo lớn hơn.

Ví dụ:

Ví dụ: một báo cáo bao gồm 100,000 hàng. Bảng sau đây trình bày chi tiết sự khác biệt về cách tính toán giữa hai phương pháp.

	SearchStream	Tìm kiếm
Kích thước trang	Không áp dụng	10.000 hàng mỗi trang
Số lượng yêu cầu API	1 yêu cầu	10 yêu cầu
Số lượt phản hồi API	1 luồng liên tục	10 phản hồi

Các yếu tố về hiệu suất

Nói chung, bạn nên sử dụng SearchStream thay vì Search vì những lý do sau.

Đối với báo cáo trang đơn (dưới 10.000 hàng): Không có sự khác biệt đáng kể về hiệu suất giữa hai phương thức.
Đối với báo cáo nhiều trang: SearchStream thường nhanh hơn vì tránh được nhiều lượt đi và về và việc đọc/ghi từ bộ nhớ đệm ổ đĩa ít ảnh hưởng hơn.

Giới hạn số lượng yêu cầu

Giới hạn hằng ngày cho cả hai phương thức tuân thủ hạn mức và hạn mức API tiêu chuẩn. Một truy vấn hoặc báo cáo được tính là một thao tác bất kể kết quả được phân trang hay truyền trực tuyến.

Ví dụ về truyền trực tuyến

Java

// Copyright 2022 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     https://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package sample;

import com.beust.jcommander.Parameter;
import com.google.ads.searchads360.v0.lib.SearchAds360Client;
import com.google.ads.searchads360.v0.services.SearchAds360Row;
import com.google.ads.searchads360.v0.services.SearchAds360ServiceClient;
import com.google.ads.searchads360.v0.services.SearchSearchAds360StreamRequest;
import com.google.ads.searchads360.v0.services.SearchSearchAds360StreamResponse;
import com.google.api.gax.rpc.ServerStream;

/** Get campaign details using SearchStream. */
public class GetCampaignsStream {
  private static class GetCampaignsStreamParams extends CodeSampleParams {

    @Parameter(names = "--customerId", required = true)
    private String customerId;

    @Parameter(names = "--loginCustomerId")
    private String loginCustomerId;
  }

  public static void main(String[] args) {
    GetCampaignsStreamParams params = new GetCampaignsStreamParams();
    if (!params.parseArguments(args)) {
      // Optional: You may pass the loginCustomerId on the command line or specify a loginCustomerId
      // here (10 digits, no dashes). If neither are set, customerId will be used as
      // loginCustomerId.
      // params.loginCustomerId = Long.parseLong("INSERT_LOGIN_CUSTOMER_ID_HERE");
    }
    final String loginCustomerId = params.loginCustomerId;
    final String customerId = params.customerId;

    try {
      // Creates a SearchAds360Client with the specified loginCustomerId. If there's
      // no loginCustomerId, customerId will be used instead.
      final SearchAds360Client searchAds360Client =
          SearchAds360Client.newBuilder()
              .setLoginCustomerId(loginCustomerId == null ? customerId : loginCustomerId)
              .fromPropertiesFile()
              .build();
      // Creates the Search Ads 360 Service client.
      SearchAds360ServiceClient client = searchAds360Client.create();
      new GetCampaignsStream().runExample(client, customerId);
    } catch (Exception exception) {
      System.err.printf("Failed with exception: %s%n", exception);
      exception.printStackTrace();
      System.exit(1);
    }
  }

  private void runExample(SearchAds360ServiceClient searchAds360ServiceClient, String customerId) {
    // Creates a query that retrieves all campaigns under the customerId.
    String query = "SELECT campaign.name, campaign.id, campaign.status FROM campaign";
    SearchSearchAds360StreamRequest request =
        SearchSearchAds360StreamRequest.newBuilder()
            .setCustomerId(customerId)
            .setQuery(query)
            .build();

    // Issues a search stream request.
    ServerStream<SearchSearchAds360StreamResponse> stream =
        searchAds360ServiceClient.searchStreamCallable().call(request);

    for (SearchSearchAds360StreamResponse response : stream) {
      for (SearchAds360Row element : response.getResultsList()) {
        System.out.printf(
            "Campaign found with name '%s', ID %d, and status: %s.%n",
            element.getCampaign().getName(),
            element.getCampaign().getId(),
            element.getCampaign().getStatus());
      }
    }
  }
}

Tải GetCampaignsStream.java xuống

Python

#!/usr/bin/env python
# Copyright 2022 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     https://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
"""Retrieves campaigns for a customer using a stream request."""

import argparse
import traceback
from google.ads.searchads360.v0.services.types.search_ads360_service import SearchSearchAds360StreamRequest
from util_searchads360 import SearchAds360Client


def main(client, customer_id) -> None:
  search_ads_360_service = client.get_service()

  query = """
      SELECT
        campaign.name,
        campaign.id,
        campaign.status
      FROM campaign"""

  request = SearchSearchAds360StreamRequest()
  request.customer_id = customer_id
  request.query = query

  # Issues a search stream request.
  results = search_ads_360_service.search_stream(request=request)

  for response in results:
    for result in response.results:
      campaign = result.campaign
      print(
          f'campaign "{campaign.name}" has id {campaign.id} and status {campaign.status.name}'
      )


if __name__ == "__main__":
  # SearchAds360Client will read the search-ads-360.yaml configuration file in
  # the home directory if none is specified.
  search_ads_360_client = SearchAds360Client.load_from_file()

  parser = argparse.ArgumentParser(
      description=("Retrieves campaigns for a customer."))
  # Arguments to provide to run the example.
  parser.add_argument(
      "-c",
      "--customer_id",
      type=str,
      required=True,
      help="The Search Ads 360 customer ID (10 digits, no dashes).",
  )

  parser.add_argument(
      "-l",
      "--login_customer_id",
      type=str,
      required=False,
      help="The Search Ads 360 login customer ID (10 digits, no dashes).",
  )

  args = parser.parse_args()

  search_ads_360_client.set_ids(args.customer_id, args.login_customer_id)

  try:
    main(search_ads_360_client, args.customer_id)
  except Exception:  # pylint: disable=broad-except
    traceback.print_exc()

Tải get_campaigns_stream.py xuống