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 |
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 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:
SearchStreamgeralmente é 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
SearchStreamdepende 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; }