Premiers pas

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

Installation

Les binaires des bibliothèques clientes sont distribués à l’aide de NuGet. Ajoutez une référence Nuget au package Google.Ads.GoogleAds dans 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 code secret de client, votre jeton d'actualisation et votre jeton de développeur dans la bibliothèque.

Si vous disposez déjà d'identifiants...

  • Copiez le nœud GoogleAdsApi et la section GoogleAdsApi sous le nœud configSections du fichier App.config dans 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 code secret du client et le jeton d'actualisation dans le fichier 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 pour utiliser d'autres paramètres de configuration.

Si vous devez générer des identifiants...

  • Suivez le guide des jetons de développeur pour obtenir votre jeton de développeur, si vous n'en avez pas déjà un.
  • Suivez le guide sur le flux d'applications de bureau OAuth pour générer un ID et un code secret de client, ainsi qu'un jeton d'actualisation.
  • Copiez le nœud GoogleAdsApi et la section GoogleAdsApi sous le nœud configSections du fichier App.config dans 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 code secret du client et le jeton d'actualisation dans le fichier 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 pour utiliser d'autres paramètres de configuration.

Effectuer un appel d'API

L'utilisation de base de la bibliothèque cliente est présentée ci-dessous:

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

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

// Make more calls to service class.

Créer une instance GoogleAdsClient

Les classes les plus importantes de la bibliothèque .NET de l'API Google Ads sont la classe GoogleAdsClient. Elle vous permet de créer une classe de service préconfigurée pouvant être utilisée 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. Reportez-vous au guide de configuration pour connaître les différentes 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.V16.CampaignService);
// Now make calls to CampaignService.

Nous fournissons une classe Services qui énumère toutes les versions d'API et tous les services compatibles. La méthode GetService accepte ces objets d'énumération en tant qu'arguments lors de la création du service. Par exemple, pour créer une instance de CampaignServiceClient pour la version V16 de l'API Google Ads, vous devez appeler la méthode GoogleAdsClient.GetService avec Services.V16.CampaignService comme argument, comme indiqué ci-dessus.

Thread safety

Il est risqué 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, les appels à plusieurs services en parallèle, etc. sont thread-safe.

Une application multithread ressemblera à ceci:

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 figer 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.

Il existe deux façons de résoudre ce problème:

  1. Utiliser 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 peut donc ne pas résoudre le problème. Voici un exemple d'extrait de code:

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

  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 affichés sous forme de liste.

    private async void button1_Click(object sender, EventArgs e)
{
// Get the GoogleAdsService.
GoogleAdsServiceClient googleAdsService = client.GetService(
    Services.V16.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 s'affiche à l'aide d'une alerte MessageBox.

    private async void button2_Click(object sender, EventArgs e)
{
// Get the BudgetService.
CampaignBudgetServiceClient budgetService = client.GetService(
    Services.V16.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);
}

Annuler des méthodes asynchrones

Pour la programmation asynchrone, vous pouvez utiliser le paramètre callSettings pour transmettre un CancellationToken:

CancellationTokenSource cancellationTokenSource = new CancellationTokenSource();
cancellationTokenSource.CancelAfter(3000);
CallSettings callSettings = CallSettings.FromCancellationToken(cancellationTokenSource.Token);

string query = "SELECT campaign.name FROM campaign";
var request = new SearchGoogleAdsStreamRequest()
{
    CustomerId = customerId.ToString(),
    Query = query,
};

GoogleAdsServiceClient googleAdsService = client.GetService(
    Services.V16.GoogleAdsService);

googleAdsService.SearchStream(request,
    delegate (SearchGoogleAdsStreamResponse resp)
    {
        foreach (GoogleAdsRow googleAdsRow in resp.Results)
        {
            // Process the row.
        }
    }, callSettings
);

Gestion des exceptions

Tous les appels d'API ne aboutissent 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 pour vous aider à comprendre ce qui s'est mal passé:

// Get the CampaignService.
CampaignServiceClient campaignService = client.GetService(Services.V16.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}");
}