Transmitir relatórios usando GoogleAdsService

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

• GoogleAdsService.SearchStream
• GoogleAdsService.Search

Confira as principais distinções entre os dois métodos:

	GoogleAdsService.SearchStream	GoogleAdsService.Search
Adequado para código de produção	Sim	Sim
Serviço	GoogleAdsService	GoogleAdsService
Cenário	Buscar objetos e relatórios	Buscar objetos e relatórios
Resposta	Transmissão de GoogleAdsRow objetos	Páginas de GoogleAdsRow objetos
Campos da resposta	Apenas aqueles especificados na consulta	Apenas aqueles 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

SearchStream x Search

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 SearchGoogleAdsStreamResponse objetos. O código pode iterar sobre os lotes recebidos à medida que chegam, sem esperar que toda a transmissão termine.

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

Exemplo

Este exemplo mostra 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	Search
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 transmissão contínua	10 respostas

Fatores de performance

Para a 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 desempenho entre os dois métodos.
• Relatórios de várias páginas:SearchStream geralmente é mais rápido porque evita várias viagens de rede de ida e volta, e a leitura ou gravação do cache em disco é um fator menor.
• Eficiência de memória:ao processar relatórios grandes com SearchStream, itere os blocos de transmissão e processe as linhas à medida que 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 SearchStream depende de uma conexão persistente, as transmissões de longa duração podem ser interrompidas por quedas de rede ou tempos limite. Configure tempos limite de RPC adequados e implemente a lógica de repetição para erros de transmissão temporários.

Limitação de taxa

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 na nuvem do Google Cloud. Uma única consulta de relatório lógico é contada como uma operação na sua cota de operação 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 é contada como uma chamada de RPC individual em relação aos limites de limitação 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 transmissão 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.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;
    }
}
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::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;
}
get_campaigns.pl
      

curl

Observação:embora um exemplo de código REST direto para esta etapa não seja fornecido aqui, é 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 do proto.

Recursos principais:

• Como usar o 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.