Utilisation de base

Voici l'utilisation de base de la bibliothèque cliente .NET :

// Initialize a GoogleAdsConfig instance.
GoogleAdsConfig config = new GoogleAdsConfig()
{
    OAuth2Mode = OAuth2Flow.SERVICE_ACCOUNT,
    OAuth2SecretsJsonPath = "PATH_TO_CREDENTIALS_JSON",
    LoginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"
};

// Initialize a GoogleAdsClient instance.
GoogleAdsClient client = new GoogleAdsClient(config);

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

// Make calls to the service client.

Initialiser le client et les services

Pour interagir avec l'API Google Ads, commencez par configurer et instancier un GoogleAdsClient, puis utilisez-le pour créer les clients de service d'API spécifiques dont vous avez besoin.

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 un client de service préconfiguré qui peut être utilisé pour effectuer des appels d'API. Pour configurer un objet GoogleAdsClient, créez un objet GoogleAdsConfig et définissez les propriétés requises. Pour en savoir plus, consultez le guide de configuration.

// Initialize a GoogleAdsConfig instance.
GoogleAdsConfig config = new GoogleAdsConfig()
{
    OAuth2Mode = OAuth2Flow.SERVICE_ACCOUNT,
    OAuth2SecretsJsonPath = "PATH_TO_CREDENTIALS_JSON",
    LoginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"
};

// Initialize a GoogleAdsClient instance.
GoogleAdsClient client = new GoogleAdsClient(config);

// Modify the GoogleAdsClient configuration afterwards if needed.
client.Config.LoginCustomerId = "INSERT_UPDATED_LOGIN_CUSTOMER_ID_HERE";

Créer un service

GoogleAdsClient fournit une méthode GetService qui peut être utilisée pour créer un client de service d'API.

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

La bibliothèque fournit une classe Services qui énumère toutes les versions d'API compatibles (où les versions mineures telles que v25.1 utilisent leur énumération de version majeure, Services.V25) et les services. 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 V25 de l'API Google Ads, appelez la méthode GoogleAdsClient.GetService avec Services.V25.CampaignService comme argument, comme indiqué dans l'exemple précédent.

Gestion des exceptions

Tous les appels d'API ne sont pas couronnés de succès. Le serveur peut renvoyer 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 n'a pas fonctionné :

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;
    }
}

Thread safety

La modification de l'état de configuration d'une instance GoogleAdsClient partagée sur plusieurs threads n'est pas thread-safe, 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. Toutefois, les opérations en lecture seule, comme l'obtention de nouvelles instances de service à partir d'une instance GoogleAdsClient immuable et l'appel de plusieurs services en parallèle, sont thread-safe.

Pour isoler les modifications de configuration par thread, instanciez un GoogleAdsClient distinct par tâche ou thread de nœud de calcul :

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

Task task1 = Task.Run(() => AddAdGroups(client1));
Task task2 = Task.Run(() => AddAdGroups(client2));

await Task.WhenAll(task1, task2);

public void AddAdGroups(GoogleAdsClient client)
{
    // Perform operations with client.
}

Préserver la réactivité de votre application

Les appels de méthode de l'API Google Ads peuvent prendre un certain temps, en fonction de la taille des requêtes. Pour que votre application reste réactive, procédez comme suit :

Utiliser la bibliothèque Grpc.Core pour les anciens frameworks d'UI

Si vous développez une application ciblant .NET Framework et utilisant une ancienne technologie d'UI telle qu'ASP.NET Web Forms ou WinForms, vous pouvez activer l'ancienne bibliothèque de transport Grpc.Core comme suit :

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

Utiliser des méthodes asynchrones

Vous pouvez utiliser des méthodes asynchrones pour que votre application reste réactive. Voici quelques exemples.

Récupérer la liste des campagnes et remplir un ListView

private async void OnRetrieveCampaignsButtonClick(object sender, EventArgs e)
{
    try
    {
        // 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";

        List<ListViewItem> items = new List<ListViewItem>();
        await googleAdsService.SearchStreamAsync(
            customerId.ToString(),
            query,
            (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);
                }
            }
        );
        listView1.Items.AddRange(items.ToArray());
    }
    catch (GoogleAdsException ex)
    {
        MessageBox.Show($"API Error: {ex.Message}");
    }
}

Modifier le budget de la campagne et afficher une boîte de message d'alerte

private async void OnUpdateBudgetButtonClick(object sender, EventArgs e)
{
    try
    {
        // Get the CampaignBudgetService.
        CampaignBudgetServiceClient budgetService = client.GetService(
            Services.V25.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 asynchronously.
        MutateCampaignBudgetsResponse response =
            await budgetService.MutateCampaignBudgetsAsync(
                customerId.ToString(),
                new CampaignBudgetOperation[] { budgetOperation });

        MessageBox.Show(response.Results[0].ResourceName);
    }
    catch (GoogleAdsException ex)
    {
        MessageBox.Show($"API Error: {ex.Message}");
    }
}