Transmisión del informe

Existen dos métodos para recuperar entidades y datos de informes con la API de informes de Search Ads 360.

Esta guía se enfoca principalmente en los datos de transmisión de SearchAds360Service. A continuación, se muestran distinciones de alto nivel para los dos métodos de recuperación de datos:

SearchAds360Service.SearchStream SearchAds360Service.Search
Adecuado para código de producción Sí Sí
Servicio SearchAds360Service SearchAds360Service
Situación Recupera informes y objetos Recupera informes y objetos
Respuesta Transmisión de objetos SearchAds360Row Páginas de objetos SearchAds360Row
Campos de la respuesta Solo aquellos especificados en la consulta Solo aquellos especificados en la consulta
Límites diarios Consulta los límites y cuotas de la API. Consulta los límites y cuotas de la API.

Si bien Search puede enviar varias solicitudes paginadas para descargar el informe completo, SearchStream envía una sola solicitud e inicia una conexión persistente con la API de informes de Search Ads 360, independientemente del tamaño del informe.

En el caso de SearchStream, los paquetes de datos comienzan a descargarse de inmediato con todo el resultado almacenado en caché en un búfer de datos. Tu código puede comenzar a leer los datos almacenados en búfer sin tener que esperar a que termine toda la transmisión.

Si eliminas el tiempo de ida y vuelta de red necesario para solicitar cada página individual de una respuesta Search, según tu app, SearchStream puede ofrecer un mejor rendimiento en comparación con la paginación, en especial para informes más grandes.

Ejemplo

Toma un informe que contenga 100,000 filas, por ejemplo. En la siguiente tabla, se desglosan las diferencias de contabilización entre los dos métodos.

SearchStream Buscar
Tamaño de la página No aplicable 10,000 filas por página
Cantidad de solicitudes a la API 1 solicitud 10 solicitudes
Cantidad de respuestas de la API 1 transmisión continua 10 respuestas

Factores de rendimiento

En general, recomendamos SearchStream en lugar de Search por los siguientes motivos.

  • Para informes de una sola página (menos de 10,000 filas): No hay diferencias de rendimiento significativas entre los dos métodos.

  • Para informes de varias páginas, SearchStream suele ser más rápido, ya que se evitan múltiples recorridos y la lectura/escritura desde la caché del disco es menos importante.

Límites de frecuencia

Los límites diarios de ambos métodos cumplen con los límites y las cuotas de la API estándar. Una sola consulta o informe se cuenta como una operación, sin importar el resultado que se pagina o se transmite.

Ejemplo de transmisió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());
      }
    }
  }
}

Descargar GetCampaignsStream.java

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()

Descargar get_campaigns_stream.py