Premiers pas

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

Installation

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

Configurer les autorisations

Pour autoriser vos appels d'API, vous devez spécifier votre ID client, votre code secret un jeton d'actualisation et un jeton de développeur à 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 Nœud configSections du fichier App.config dans GitHub dans votre fichier App.config / Web.config. Si vous avez utilisé NuGet pour installer 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 les App.config / Web.config de votre application.

App.config inclus dans GitHub est bien documenté, mais vous pouvez également vous référer au Guide de configuration pour en savoir plus et utiliser d'autres façons de configurer la bibliothèque cliente, comme 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.V17.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 GoogleAdsClient. Il vous permet de créer une classe de service préconfigurée permettant d'effectuer des appels d'API. GoogleAdsClient fournit une valeur par défaut qui crée un objet utilisateur à l'aide des paramètres spécifiés dans votre App.config / Web.config de l'application. Reportez-vous à la section Configuration d'assistance pour la configuration options.

// 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 Google Ads.

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

Nous fournissons une classe Services qui énumère toutes les versions d'API compatibles et services. 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 CampaignServiceClient pour la version V17 de l'API Google Ads vous devez appeler la méthode GoogleAdsClient.GetService avec Services.V17.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. Des opérations telles que l’obtention de nouvelles instances de service à partir d'une instance GoogleAdsClient et en effectuant des appels vers plusieurs services en parallèle sont thread-safe.

Une application multithread ressemblerait à 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 amener certaines de vos applications .NET Framework à figer. Un exemple courant consiste à effectuer des appels d'API à partir d'une méthode de gestionnaire d'événements. d'une application WinForm.

Vous pouvez résoudre ce problème 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 exhaustive sur les applications .NET Framework, donc cela pourrait ne pas résoudre le problème. Voici un exemple d'extrait:

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

    Vous trouverez sur la page d'assistance gRPC Informations détaillées 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 dans une vue sous forme de liste.

    private async void button1_Click(object sender, EventArgs e)
{
// Get the GoogleAdsService.
GoogleAdsServiceClient googleAdsService = client.GetService(
    Services.V17.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 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.V17.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 n'aboutissent pas. Le serveur peut générer des erreurs si vos appels d'API échouer pour une raison quelconque. Il est important de capturer les erreurs d'API et de les gérer en conséquence.

Une instance GoogleAdsException est générée lorsqu'une erreur d'API se produit. Il contient plus de détails pour vous aider à comprendre le problème:

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