דיווח על סטרימינג

יש שתי שיטות לאחזור ישויות ולדיווח על נתונים באמצעות Search Ads 360 Reporting API.

המדריך הזה מתמקד בעיקר בנתוני סטרימינג מ-SearchAds360Service. ריכזנו כאן את ההבדלים העיקריים בין שתי שיטות אחזור הנתונים:

SearchAds360Service.SearchStream SearchAds360Service.Search
מתאים לקוד בסביבת הייצור כן כן
שירות SearchAds360Service SearchAds360Service
תרחיש אחזור אובייקטים ודוחות אחזור אובייקטים ודוחות
תשובה מקור נתונים של אובייקטים מסוג SearchAds360Row דפים של אובייקטים מסוג SearchAds360Row
השדות של התשובה רק אלה שצוינו בשאילתה רק אלה שצוינו בשאילתה
מגבלות יומיות מגבלות ומכסות של ממשקי API מגבלות ומכסות של ממשקי API

בעוד ש-Search יכול לשלוח כמה בקשות עם חלוקה לדפים כדי להוריד את הדוח כולו, SearchStream שולח בקשה אחת ומתחיל חיבור מתמיד ל-Reporting API של Search Ads 360, ללא קשר לגודל הדוח.

ב-SearchStream, חבילות הנתונים מתחילות להוריד באופן מיידי, והתוצאה כולה מאוחסנת במטמון נתונים. הקוד יכול להתחיל לקרוא את הנתונים שנשמרו במאגר בלי לחכות לסיום כל הסטרימינג.

ה-SearchStream מאפשר לכם להימנע מזמני הלוך ושוב ברשת שנדרשים כדי לבקש כל דף בנפרד בתגובה ל-Search. בהתאם לאפליקציה שלכם, ה-SearchStream יכול לספק ביצועים משופרים בהשוואה לחלוקה לדפים, במיוחד בדוחות גדולים יותר.

דוגמה

ניקח לדוגמה דוח שמכיל 100,000 שורות. בטבלה הבאה מפורטים ההבדלים החשבונאיים בין שתי השיטות.

SearchStream חיפוש
גודל דף לא רלוונטי 10,000 שורות בכל דף
מספר בקשות ה-API בקשה אחת 10 בקשות
מספר התשובות מה-API שידור רצוף אחד 10 תשובות

גורמי ביצועים

באופן כללי, אנחנו ממליצים על SearchStream במקום על Search מהסיבות הבאות.

  • בדוחות של דף אחד (פחות מ-10,000 שורות): אין הבדלים משמעותיים בביצועים בין שתי השיטות.

  • בדוחות עם כמה דפים: בדרך כלל SearchStream מהיר יותר כי נמנעים מנסיעות הלוך ושוב מרובות, וקריאה/כתיבה מהמטמון בדיסק פחות משמעותית.

הגבלות קצב

המגבלות היומיות בשתי השיטות תואמות למגבלות ולמכסות הרגילות של ה-API. שאילתה או דוח יחידים נספרים כפעולה אחת, ללא קשר לאופן שבו התוצאה מוצגת (בחלוקה לדפים או בסטרימינג).

דוגמה לשידור

JavaPython

// 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());
      }
    }
  }
}

הורדת GetCampaignsStream.java 

#!/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()

הורדת get_campaigns_stream.py