Transmitir relatórios usando GoogleAdsService

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

• GoogleAdsService.SearchStream
• GoogleAdsService.Search

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	Stream de objetos GoogleAdsRow	Páginas de objetos GoogleAdsRow
Campos da resposta	Somente as especificadas na consulta	Somente as especificadas 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

SearchStream x Search

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

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

Ao eliminar o tempo de ida e volta da rede necessário para solicitar cada página individual de uma resposta Search, o SearchStream oferece um desempenho melhor 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 de solicitação e resposta entre os dois métodos:

	SearchStream	Pesquisar
Tamanho da página	Não relevante	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

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

• Relatórios de uma única página (menos de 10.000 linhas): não há diferenças significativas de desempenho entre os dois métodos.
• Relatórios de várias páginas: o SearchStream geralmente é mais rápido porque várias viagens de ida e volta de rede são evitadas, e a leitura ou gravação do cache em disco é menos importante.
• Eficiência de memória: ao processar relatórios grandes com SearchStream, itera os blocos de stream e processa as linhas conforme 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, na sigla em inglês).
• Resiliência da conexão: como o SearchStream depende de uma conexão persistente, os streams de longa duração podem ser interrompidos por quedas de rede ou tempos limite. Configure tempos limite de RPC adequados e implemente uma lógica de nova tentativa para erros de stream temporários.

Limites de taxas

Os limites diários de operação para os dois métodos seguem os limites padrão e os 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 de operações, independentemente 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 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());
      }
    }
  }
}
GetCampaigns.java
      

C#

public void Run(GoogleAdsClient client, long customerId)
{
    // Get the GoogleAdsService.
    GoogleAdsServiceClient googleAdsService = client.GetService(
        Services.V26.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;
    }
}
GetCampaigns.cs
      

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
        );
    }
}
GetCampaigns.php
      

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.'
            )
get_campaigns.py
      

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
get_campaigns.rb
      

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::V26::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;
}
get_campaigns.pl
      

curl

Observação: embora não seja fornecido um exemplo de código REST direto para esta etapa, é possível fazer isso usando uma solicitação REST manual.

Consulte a documentação da interface REST da API Google Ads e as páginas de referência específicas do método. Você precisará criar o payload JSON com base nas definições de proto.

Principais recursos:

• Como usar REST
• Estrutura da interface REST
• Mapeamentos de campos JSON
• Consulte a Referência da API REST para o serviço e o método específicos.