Pour récupérer les entités et les données de rapport de l'API Google Ads, utilisez l'une des méthodes suivantes :
Voici les principales différences entre les deux méthodes :
| GoogleAdsService.SearchStream | GoogleAdsService.Search | |
|---|---|---|
| Convient au code de production | Oui | Oui |
| Service | GoogleAdsService |
GoogleAdsService |
| Scénario | Récupérer des objets et des rapports | Récupérer des objets et des rapports |
| Réponse | Flux de GoogleAdsRow objets |
Pages d'objets GoogleAdsRow |
| Champs de la réponse | Uniquement ceux spécifiés dans la requête | Uniquement ceux spécifiés dans la requête |
| Limites quotidiennes | Limites quotidiennes en fonction des niveaux d'accès | Limites quotidiennes en fonction des niveaux d'accès |
SearchStream contre Search
Alors que Search envoie plusieurs requêtes paginées pour télécharger un rapport complet, SearchStream envoie une seule requête et établit une connexion gRPC persistante avec l'API Google Ads, quelle que soit la taille du rapport.
Pour SearchStream, les paquets de données commencent à être téléchargés immédiatement par lots de SearchGoogleAdsStreamResponse objets. Votre code peut itérer sur les lots entrants à mesure qu'ils arrivent, sans attendre la fin du flux entier.
En éliminant le temps de trajet aller-retour du réseau nécessaire pour demander chaque page individuelle d'une réponse Search, SearchStream offre de meilleures performances que la pagination, en particulier pour les grands rapports.
Exemple
Cet exemple examine un rapport composé de 100,000 lignes. Le tableau suivant détaille les différences entre les deux méthodes en termes de requêtes et de réponses :
| SearchStream | Rechercher | |
|---|---|---|
| Format de page | Non applicable | 10 000 lignes par page |
| Nombre de requêtes API | 1 requête | 10 requêtes |
| Nombre de réponses de l'API | 1 flux continu | 10 réponses |
Facteurs de performances
Dans la plupart des cas d'utilisation, nous recommandons SearchStream plutôt que Search pour les raisons suivantes :
- Rapports d'une seule page (moins de 10 000 lignes) : il n'existe aucune différence significative en termes de performances entre les deux méthodes.
- Rapports multipages :
SearchStreamest généralement plus rapide, car plusieurs allers-retours réseau sont évités, et la lecture ou l'écriture à partir du cache du disque est moins un facteur. - Efficacité de la mémoire : lorsque vous traitez des rapports volumineux avec
SearchStream, parcourez les blocs de flux et traitez les lignes à mesure qu'elles arrivent plutôt que de mettre en mémoire tampon toutes les lignes à la fois pour éviter les erreurs de mémoire insuffisante (OOM). - Résilience de la connexion : comme
SearchStreamrepose sur une connexion persistante, les flux de longue durée peuvent être interrompus par des pertes de réseau ou des délais d'inactivité. Configurez les délais avant expiration RPC appropriés et implémentez une logique de réessai pour les erreurs de flux temporaires.
Limites de débit
Les limites d'opérations quotidiennes pour les deux méthodes respectent les limites standards et les niveaux d'accès de votre projet Google Cloud. Une seule requête de rapport logique est comptabilisée comme une opération dans votre quota d'opérations quotidiennes, que le résultat soit diffusé en flux continu avec SearchStream ou récupéré sur plusieurs pages mises en cache à l'aide de Search avec un page_token. Toutefois, chaque requête Search paginée est toujours comptabilisée comme un appel RPC individuel par rapport aux limites de fréquence à court terme.
Exemple de code
L'exemple de code suivant montre comment exécuter une requête de rapport en flux continu à l'aide des bibliothèques clientes :
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; }