Bibliothèques clientes

Les bibliothèques clientes de l'API Google Ads fournissent des vues de haut niveau et des blocs de construction de base des fonctionnalités de l'API Google Ads, ce qui facilite le développement rapide d'applications. Si vous ne connaissez pas l'API, commencez par une bibliothèque cliente.

Bibliothèques développées par les communautés

Nous connaissons plusieurs bibliothèques gérées par la communauté Open Source. Nous tenons à jour cette liste pour aider les développeurs intéressés à les trouver. Nous ne testons pas ces bibliothèques, n'y contribuons pas et ne les gérons pas. Utilisez-les à vos risques et périls. Si vous avez des questions, veuillez les adresser aux propriétaires des projets Open Source.

Si vous connaissez une bibliothèque que nous avons oubliée, cliquez sur Envoyer des commentaires en haut de la page pour nous en informer.

• Node.js : google-ads-api sur npm
• Go : google-ads-pb sur GitHub

Versions d'API compatibles

Le tableau indique les bibliothèques clientes compatibles avec les différentes versions de l'API.

La version minimale de la bibliothèque cliente indiquée est suffisante pour la version majeure de l'API Google Ads (par exemple, la version 25). Pour connaître la version requise de la bibliothèque cliente pour les versions mineures, consultez le journal des modifications associé.

Configuration

Chaque bibliothèque cliente de l'API Google Ads fournit différents paramètres de configuration et méthodes de chargement que vous pouvez utiliser pour personnaliser son comportement.

Voici les variables d'environnement standards que vous pouvez utiliser pour configurer les bibliothèques clientes :

• Bibliothèque cliente
  • GOOGLE_ADS_CONFIGURATION_FILE_PATH : chemin d'accès au fichier de configuration (lu automatiquement lors du chargement à partir d'un fichier de configuration sans argument de chemin d'accès explicite dans Java (fromPropertiesFile()), Perl (Client->new()), PHP (fromFile()), Python (load_from_storage(), et également vérifié par load_from_env()) et Ruby (GoogleAdsClient.new) ; dans .NET, chargez cette variable de manière explicite à l'aide de config.TryLoadFromEnvironmentFilePath ou chargez les fichiers de configuration à l'aide de LoadFromSettingsJson, LoadFromConfigurationSection ou LoadFromConfigurationRoot).
• OAuth2
  • Mode Application
    • GOOGLE_ADS_CLIENT_ID : définissez cette valeur sur votre ID client OAuth2.
    • GOOGLE_ADS_CLIENT_SECRET : définissez cette valeur sur le code secret de votre client OAuth2.
    • GOOGLE_ADS_REFRESH_TOKEN : définissez cette valeur sur un jeton d'actualisation OAuth2 pré-généré si vous souhaitez réutiliser des jetons OAuth2. Ce paramètre est facultatif.
  • Mode Compte de service
    • GOOGLE_ADS_JSON_KEY_FILE_PATH : définissez cette valeur sur le chemin d'accès à votre fichier de clé JSON OAuth2 (dans .NET, définissez également GOOGLE_ADS_OAUTH2_MODE sur SERVICE_ACCOUNT, car OAuth2Mode est défini par défaut sur APPLICATION ; dans les versions PHP antérieures à v32.1.0 ou lorsque vous utilisez des niveaux d'accès personnalisés, définissez également [OAUTH2] scopes dans google_ads_php.ini ou appelez withScopes(), car fromEnvironmentVariables() ne lit pas les niveaux d'accès OAuth2 à partir d'une variable d'environnement).
    • GOOGLE_ADS_IMPERSONATED_EMAIL : définissez cette valeur sur l'adresse e-mail du compte que vous usurpez lorsque vous utilisez la délégation à l'échelle du domaine Google Workspace. Ce paramètre est facultatif.
  • Mode Identifiants par défaut de l'application
    • GOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS : définissez cette valeur sur true pour vous authentifier à l'aide des identifiants par défaut de l'application (ADC). Pris en charge dans Java v41.1.0 et versions ultérieures, Python v28.3.0 et versions ultérieures, et Ruby v36.1.0 et versions ultérieures (dans .NET v24.1.0 et versions ultérieures, LoadFromEnvironmentVariables() lit plutôt la variable USE_APPLICATION_DEFAULT_CREDENTIALS sans préfixe, ou définit UseApplicationDefaultCredentials = true sur GoogleAdsConfig ; dans PHP, OAuth2TokenBuilder revient automatiquement à ADC lorsqu'aucune identifiants OAuth2 explicites n'est défini ; Perl n'est pas compatible avec ADC).
• API Google Ads
  • GOOGLE_ADS_DEVELOPER_TOKEN : Facultatif dans les dernières versions (Java v46.0.0 et versions ultérieures, .NET v27.3.0 et versions ultérieures, PHP v35.0.0 et versions ultérieures, Python v32.0.0 et versions ultérieures, Ruby v45.0.0 et versions ultérieures, et Perl v35.0.0 et versions ultérieures). Les jetons de développeur ont été abandonnés le 9 septembre 2026. Les serveurs API ignorent l'en-tête developer-token, quelle que soit la version de la bibliothèque cliente (jusqu'à ce qu'une future version majeure de l'API Google Ads le refuse). Les versions antérieures de la bibliothèque cliente nécessitent toujours une valeur non vide pour la validation locale côté client. Pour en savoir plus sur les versions spécifiques, consultez le guide de configuration de chaque bibliothèque.
  • GOOGLE_ADS_LOGIN_CUSTOMER_ID : ID client du client autorisé à utiliser dans la requête, sans tirets (-).
  • GOOGLE_ADS_LINKED_CUSTOMER_ID : cet en-tête n'est requis que pour les méthodes qui mettent à jour les ressources d'une entité lorsque l'autorisation est accordée via les comptes associés dans l'UI Google Ads (ressource AccountLink dans l'API Google Ads). Définissez cette valeur sur l'ID client du fournisseur de données qui met à jour les ressources de l'ID client spécifié. Il doit être défini sans tirets (-). Pour en savoir plus sur les comptes associés, consultez le Centre d'aide.

Les variables d'environnement sont généralement définies dans un fichier de configuration bash tel qu'un fichier .bashrc ou .bash_profile situé dans le répertoire $HOME. Ils peuvent également être définis à l'aide de la ligne de commande.

Voici quelques étapes de base pour définir une variable d'environnement à l'aide d'un fichier .bashrc dans un terminal :

# Append the line "export GOOGLE_ADS_CLIENT_ID=1234567890" to
# the bottom of your .bashrc file.
echo "export GOOGLE_ADS_CLIENT_ID=1234567890" >> ~/.bashrc

# Update your bash environment to use the most recently updated
# version of your .bashrc file.
source ~/.bashrc

Vous pouvez également définir des variables d'environnement dans votre instance de terminal directement à partir de la ligne de commande :

export GOOGLE_ADS_CLIENT_ID=1234567890

Vous pouvez également définir des variables d'environnement lorsque vous appelez la commande qui les utilise :

GOOGLE_ADS_CLIENT_ID=1234567890 php /path/to/script/that/uses/envvar.php

Récupérer des entités

GoogleAdsService.SearchStream est généralement utilisé pour extraire des entités, et les résultats sont renvoyés sous forme de flux de lignes. Vous pouvez également utiliser GoogleAdsService.Search pour récupérer des entités via une connexion Internet peu fiable. GoogleAdsService.Search renvoie les résultats sous forme de pages de taille fixe de 10 000 lignes par page.

Les bibliothèques clientes implémentent automatiquement la pagination lorsque vous parcourez les résultats. Vous pouvez ainsi les télécharger et les traiter séquentiellement en une seule fois.

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
      

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
      

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
      

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
      

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
      

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
      

Exemples de code

Consultez nos exemples de code pour découvrir quelques fonctions courantes de l'API Google Ads.