Premiers pas

Ce guide vous explique brièvement comment commencer à utiliser la bibliothèque .NET de l'API Google Ads.

Installation

Les binaires de la bibliothèque cliente sont distribués à l'aide de NuGet. Ajoutez une référence NuGet au package Google.Ads.GoogleAds de votre projet pour utiliser la bibliothèque cliente.

Configurer les autorisations

Pour autoriser vos appels d'API, vous devez spécifier votre ID client, votre secret client, votre jeton d'actualisation et votre jeton de développeur dans la bibliothèque.

Si vous devez générer des identifiants

Si vous possédez déjà des identifiants

  • Copiez le nœud GoogleAdsApi et la section GoogleAdsApi sous le nœud configSections du fichier App.config sur GitHub dans votre fichier App.config / Web.config. Si vous avez utilisé NuGet pour installer le package, ces nœuds seront automatiquement insérés dans votre fichier App.config / Web.config.
  • Incluez le jeton de développeur, l'ID client, le secret client et le jeton d'actualisation dans App.config / Web.config de votre application.

Le fichier App.config inclus dans GitHub est bien documenté, mais vous pouvez également consulter le guide de configuration pour en savoir plus et utiliser d'autres méthodes de configuration de la bibliothèque cliente, telles que les variables d'environnement.

Effectuer un appel d'API

L'utilisation de base de la bibliothèque cliente est la suivante:

// Create a Google Ads client.
GoogleAdsClient client = new GoogleAdsClient();

// Create the required service.
CampaignServiceClient campaignService =
    client.GetService(Services.V18.CampaignService);

// Make more calls to service class.

Créer une instance GoogleAdsClient

La classe GoogleAdsClient est la plus importante de la bibliothèque .NET de l'API Google Ads. Il vous permet de créer une classe de service préconfigurée que vous pouvez utiliser pour effectuer des appels d'API. GoogleAdsClient fournit un constructeur par défaut qui crée un objet utilisateur à l'aide des paramètres spécifiés dans App.config / Web.config de votre application. Consultez le guide de configuration pour connaître les options de configuration.

// Create a new GoogleAdsClient with the App.config settings.
GoogleAdsClient user = new GoogleAdsClient();

Créer un service

GoogleAdsClient fournit une méthode GetService qui peut être utilisée pour créer un service Ads.

CampaignServiceClient campaignService = client.GetService(Services.V18.CampaignService);
// Now make calls to CampaignService.

Nous fournissons une classe Services qui énumère toutes les versions et services d'API compatibles. La méthode GetService accepte ces objets d'énumération comme argument lors de la création du service. Par exemple, pour créer une instance de CampaignServiceClient pour la version V18 de l'API Google Ads, vous devez appeler la méthode GoogleAdsClient.GetService avec Services.V18.CampaignService comme argument, comme indiqué dans l'exemple précédent.

Thread safety

Il n'est pas prudent de partager une instance GoogleAdsClient entre plusieurs threads, car les modifications de configuration que vous apportez à une instance dans un thread peuvent affecter les services que vous créez sur d'autres threads. Les opérations telles que l'obtention de nouvelles instances de service à partir d'une instance GoogleAdsClient et l'appel de plusieurs services en parallèle sont thread-safe.

Une application multithread se présente comme suit:

GoogleAdsClient client1 = new GoogleAdsClient();
GoogleAdsClient client2 = new GoogleAdsClient();

Thread userThread1 = new Thread(addAdGroups);
Thread userThread2 = new Thread(addAdGroups);

userThread1.start(client1);
userThread2.start(client2);

userThread1.join();
userThread2.join();

public void addAdGroups(object data) {
  GoogleAdsClient client = (GoogleAdsClient) data;
  // Do more operations here.
  ...
}

Éviter les blocages dans les applications .NET Framework

Les méthodes synchrones peuvent entraîner le blocage de certaines de vos applications .NET Framework. Un exemple courant consiste à effectuer des appels d'API à partir d'une méthode de gestionnaire d'événements d'une application WinForm.

Pour résoudre ce problème, vous pouvez procéder de deux façons:

  1. Utilisez l'ancienne bibliothèque Grpc.

    Vous pouvez définir la propriété UseGrpcCore de GoogleAdsConfig pour utiliser l'ancienne bibliothèque Grpc.Core au lieu de la bibliothèque Grpc.Net.Client par défaut. Cette méthode n'a pas été testée de manière approfondie sur les applications .NET Framework. Elle risque donc de ne pas résoudre le problème. Voici un exemple d'extrait:

    GoogleAdsConfig config = new GoogleAdsConfig();
config.UseGrpcCore = true;
GoogleAdsClient client = new GoogleAdsClient(config);

    La page d'assistance gRPC fournit plus d'informations sur les différences entre l'ancienne bibliothèque Grpc.Core et la bibliothèque Grpc.Net.Client par défaut.

  2. Utilisez des méthodes asynchrones.

    Vous pouvez utiliser des méthodes asynchrones pour éviter les blocages. Voici quelques exemples :

    SearchStream

    Un appel à SearchStream() est effectué, et les résultats sont insérés dans une vue sous forme de liste.

    private async void button1_Click(object sender, EventArgs e)
{
// Get the GoogleAdsService.
GoogleAdsServiceClient googleAdsService = client.GetService(
    Services.V18.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";
 
List items = new List();
Task t =  googleAdsService.SearchStreamAsync(customerId.ToString(), query,
    delegate (SearchGoogleAdsStreamResponse resp)
    {
        foreach (GoogleAdsRow googleAdsRow in resp.Results)
        {
            ListViewItem item = new ListViewItem();
            item.Text = googleAdsRow.Campaign.Id.ToString();
            item.SubItems.Add(googleAdsRow.Campaign.Name);
            items.Add(item);
        }
    }
);
await t;
listView1.Items.AddRange(items.ToArray());
}

    Budget de la campagne

    Un appel CampaignBudget est créé, et le nom de la ressource du nouveau budget est affiché à l'aide d'une alerte MessageBox.

    private async void button2_Click(object sender, EventArgs e)
{
// Get the BudgetService.
CampaignBudgetServiceClient budgetService = client.GetService(
    Services.V18.CampaignBudgetService);
 
// Create the campaign budget.
CampaignBudget budget = new CampaignBudget()
{
    Name = "Interplanetary Cruise Budget #" + ExampleUtilities.GetRandomString(),
    DeliveryMethod = BudgetDeliveryMethod.Standard,
    AmountMicros = 500000
};
 
// Create the operation.
CampaignBudgetOperation budgetOperation = new CampaignBudgetOperation()
{
    Create = budget
};
 
// Create the campaign budget.
Task t = budgetService.MutateCampaignBudgetsAsync(
    customerId.ToString(), new CampaignBudgetOperation[] { budgetOperation });
 
await t;
MutateCampaignBudgetsResponse response = t.Result;
MessageBox.Show(response.Results[0].ResourceName);
}

Gestion des exceptions

Tous les appels d'API ne réussissent pas. Le serveur peut générer des erreurs si vos appels d'API échouent pour une raison quelconque. Il est important de capturer les erreurs d'API et de les gérer de manière appropriée.

Une instance GoogleAdsException est générée lorsqu'une erreur d'API se produit. Il contient des informations qui vous aideront à comprendre ce qui ne va pas:

// Get the CampaignService.
CampaignServiceClient campaignService = client.GetService(Services.V18.CampaignService);

// Create a campaign for update.
Campaign campaignToUpdate = new Campaign()
{
    ResourceName = ResourceNames.Campaign(customerId, campaignId),
    // More fields to update.
    // ...
};

// Create the operation.
CampaignOperation operation = new CampaignOperation()
{
    Update = campaignToUpdate,
    UpdateMask = FieldMasks.AllSetFieldsOf(campaignToUpdate)
};

try
{
    // Update the campaign.
    MutateCampaignsResponse response = campaignService.MutateCampaigns(
        customerId.ToString(), new CampaignOperation[] { operation });

    // Display the results.
    // ...
}
catch (GoogleAdsException e)
{
    Console.WriteLine("Failure:");
    Console.WriteLine($"Message: {e.Message}");

    // Can examine to get more error details.
    Console.WriteLine($"Failure: {e.Failure}");

    // Can be shared with Google for further troubleshooting.
    Console.WriteLine($"Request ID: {e.RequestId}");
}