Transmisión del informe

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

Esta guía se centra principalmente en la transmisión de datos de SearchAds360Service. A continuación, se muestran las 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 Cómo recuperar objetos e informes Cómo recuperar objetos e informes
Respuesta Flujo de objetos SearchAds360Row Páginas de objetos SearchAds360Row
Campos de la respuesta Solo los que se especifican en la consulta Solo los especificados en la consulta
Límites diarios Consulta los límites y las cuotas de la API. Consulta Límites y cuotas de la API.

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

En el caso de SearchStream, los paquetes de datos comienzan a descargarse de inmediato con el resultado completo 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 finalice toda la transmisión.

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

Ejemplo

Por ejemplo, toma un informe que consta de 100,000 filas. 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 significativas de rendimiento entre los dos métodos.

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

Límites de frecuencia

Los límites diarios de ambos métodos se adhieren a los límites y cuotas de la API estándar. Una sola consulta o informe se cuenta como una operación, independientemente de si el resultado 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());
      }
    }
  }
}

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

Descarga get_campaigns_stream.py.