Transmitir relatórios usando GoogleAdsService

Para recuperar entidades da API Google Ads e dados de relatórios, use um destes métodos:

Confira as principais diferenças entre os dois métodos:

GoogleAdsService.SearchStream GoogleAdsService.Search
Adequado para código de produção Sim Sim
Serviço GoogleAdsService GoogleAdsService
Cenário Buscando objetos e relatórios Buscando objetos e relatórios
Resposta Fluxo de objetos GoogleAdsRow Páginas de objetos GoogleAdsRow
Campos da resposta Apenas os especificados na consulta Apenas os especificados na consulta
Limites diários Limites diários com base nos níveis de acesso Limites diários com base nos níveis de acesso

Enquanto Search envia várias solicitações paginadas para baixar um relatório inteiro, SearchStream envia uma única solicitação e inicia uma conexão gRPC persistente com a API Google Ads independente do tamanho do relatório.

Para SearchStream, os pacotes de dados começam a ser baixados imediatamente em lotes de objetos SearchGoogleAdsStreamResponse. Seu código pode iterar sobre os lotes recebidos à medida que eles chegam, sem esperar que todo o fluxo seja concluído.

Ao eliminar o tempo de rede de ida e volta necessário para solicitar cada página individual de uma resposta Search, o SearchStream oferece melhor desempenho do que a paginação, especialmente para relatórios grandes.

Exemplo

Este exemplo analisa um relatório que consiste em 100,000 linhas. A tabela a seguir detalha as diferenças entre as solicitações e respostas dos dois métodos:

SearchStream Pesquisar
Tamanho da página Não aplicável 10.000 linhas por página
Número de solicitações de API 1 solicitação 10 solicitações
Número de respostas da API 1 stream contínuo 10 respostas

Fatores de performance

Na maioria dos casos de uso, recomendamos SearchStream em vez de Search pelos seguintes motivos:

  • Relatórios de página única (menos de 10.000 linhas): não há diferenças significativas de performance entre os dois métodos.
  • Relatórios de várias páginas:SearchStream geralmente é mais rápido porque evita várias viagens de ida e volta da rede, e a leitura ou gravação do cache em disco é menos importante.
  • Eficiência de memória:ao processar relatórios grandes com SearchStream, itere por partes de fluxo e processe as linhas à medida que elas chegam, em vez de armazenar todas as linhas na memória de uma só vez para evitar erros de falta de memória (OOM).
  • Resiliência da conexão:como o SearchStream depende de uma conexão persistente, fluxos de longa duração podem ser interrompidos por quedas de rede ou tempos limite de prazo. Configure tempos limite de RPC adequados e implemente uma lógica de novas tentativas para erros de fluxo temporários.

Limites de taxas

Os limites de operação diária para os dois métodos obedecem aos limites padrão e aos níveis de acesso do seu projeto do Google Cloud. Uma única consulta de relatório lógico é contabilizada como uma operação na sua cota diária, independente de o resultado ser transmitido com SearchStream ou recuperado em várias páginas armazenadas em cache usando Search com um page_token. No entanto, cada solicitação Search paginada ainda conta como uma chamada de RPC individual em relação aos limites de taxa de curto prazo.

Exemplo de código

O exemplo de código a seguir demonstra como executar uma consulta de relatório de streaming usando as bibliotecas de cliente:

Java

private void runExample(GoogleAdsClient googleAdsClient, long customerId) {
  try (GoogleAdsServiceClient googleAdsServiceClient =
      googleAdsClient.getLatestVersion().createGoogleAdsServiceClient()) {
    String query = "SELECT campaign.id, campaign.name FROM campaign ORDER BY campaign.id";
    // Constructs the SearchGoogleAdsStreamRequest.
    SearchGoogleAdsStreamRequest request =
        SearchGoogleAdsStreamRequest.newBuilder()
            .setCustomerId(Long.toString(customerId))
            .setQuery(query)
            .build();

    // Creates and issues a search Google Ads stream request that will retrieve all campaigns.
    ServerStream<SearchGoogleAdsStreamResponse> stream =
        googleAdsServiceClient.searchStreamCallable().call(request);

    // Iterates through and prints all of the results in the stream response.
    for (SearchGoogleAdsStreamResponse response : stream) {
      for (GoogleAdsRow googleAdsRow : response.getResultsList()) {
        System.out.printf(
            "Campaign with ID %d and name '%s' was found.%n",
            googleAdsRow.getCampaign().getId(), googleAdsRow.getCampaign().getName());
      }
    }
  }
}
      

C#

public void Run(GoogleAdsClient client, long customerId)
{
    // Get the GoogleAdsService.
    GoogleAdsServiceClient googleAdsService = client.GetService(
        Services.V25.GoogleAdsService);

    // Create a query that will retrieve all campaigns.
    string query = @"SELECT
                    campaign.id,
                    campaign.name,
                    campaign.network_settings.target_content_network
                FROM campaign
                ORDER BY campaign.id";

    try
    {
        // Issue a search request.
        googleAdsService.SearchStream(customerId.ToString(), query,
            delegate (SearchGoogleAdsStreamResponse resp)
            {
                foreach (GoogleAdsRow googleAdsRow in resp.Results)
                {
                    Console.WriteLine("Campaign with ID {0} and name '{1}' was found.",
                        googleAdsRow.Campaign.Id, googleAdsRow.Campaign.Name);
                }
            }
        );
    }
    catch (GoogleAdsException e)
    {
        Console.WriteLine("Failure:");
        Console.WriteLine($"Message: {e.Message}");
        Console.WriteLine($"Failure: {e.Failure}");
        Console.WriteLine($"Request ID: {e.RequestId}");
        throw;
    }
}
      

PHP

public static function runExample(GoogleAdsClient $googleAdsClient, int $customerId)
{
    $googleAdsServiceClient = $googleAdsClient->getGoogleAdsServiceClient();
    // Creates a query that retrieves all campaigns.
    $query = 'SELECT campaign.id, campaign.name FROM campaign ORDER BY campaign.id';
    // Issues a search stream request.
    /** @var GoogleAdsServerStreamDecorator $stream */
    $stream = $googleAdsServiceClient->searchStream(
        SearchGoogleAdsStreamRequest::build($customerId, $query)
    );

    // Iterates over all rows in all messages and prints the requested field values for
    // the campaign in each row.
    foreach ($stream->iterateAllElements() as $googleAdsRow) {
        /** @var GoogleAdsRow $googleAdsRow */
        printf(
            "Campaign with ID %d and name '%s' was found.%s",
            $googleAdsRow->getCampaign()->getId(),
            $googleAdsRow->getCampaign()->getName(),
            PHP_EOL
        );
    }
}
      

Python

def main(client: GoogleAdsClient, customer_id: str) -> None:
    ga_service: GoogleAdsServiceClient = client.get_service("GoogleAdsService")

    query: str = """
        SELECT
          campaign.id,
          campaign.name
        FROM campaign
        ORDER BY campaign.id"""

    # Issues a search request using streaming.
    stream: Iterator[SearchGoogleAdsStreamResponse] = ga_service.search_stream(
        customer_id=customer_id, query=query
    )

    for batch in stream:
        rows: List[GoogleAdsRow] = batch.results
        for row in rows:
            print(
                f"Campaign with ID {row.campaign.id} and name "
                f'"{row.campaign.name}" was found.'
            )
      

Ruby

def get_campaigns(customer_id)
  # GoogleAdsClient will read a config file from
  # ENV['HOME']/google_ads_config.rb when called without parameters
  client = Google::Ads::GoogleAds::GoogleAdsClient.new

  responses = client.service.google_ads.search_stream(
    customer_id: customer_id,
    query: 'SELECT campaign.id, campaign.name FROM campaign ORDER BY campaign.id',
  )

  responses.each do |response|
    response.results.each do |row|
      puts "Campaign with ID #{row.campaign.id} and name '#{row.campaign.name}' was found."
    end
  end
end
      

Perl

sub get_campaigns {
  my ($api_client, $customer_id) = @_;

  # Create a search Google Ads stream request that will retrieve all campaigns.
  my $search_stream_request =
    Google::Ads::GoogleAds::V25::Services::GoogleAdsService::SearchGoogleAdsStreamRequest
    ->new({
      customerId => $customer_id,
      query      =>
        "SELECT campaign.id, campaign.name FROM campaign ORDER BY campaign.id"
    });

  # Get the GoogleAdsService.
  my $google_ads_service = $api_client->GoogleAdsService();

  my $search_stream_handler =
    Google::Ads::GoogleAds::Utils::SearchStreamHandler->new({
      service => $google_ads_service,
      request => $search_stream_request
    });

  # Issue a search request and process the stream response to print the requested
  # field values for the campaign in each row.
  $search_stream_handler->process_contents(
    sub {
      my $google_ads_row = shift;
      printf "Campaign with ID %d and name '%s' was found.\n",
        $google_ads_row->{campaign}{id}, $google_ads_row->{campaign}{name};
    });

  return 1;
}
      

curl