Utilizzo di base

L'utilizzo di base della libreria client .NET è il seguente:

// 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.V26.CampaignService);

// Make calls to the service client.

Inizializzare il client e i servizi

Per interagire con l'API Google Ads, devi prima configurare e creare un'istanza di GoogleAdsClient, quindi utilizzarla per creare i client di servizi API specifici di cui hai bisogno.

Creare un'istanza di GoogleAdsClient

La classe più importante della libreria .NET dell'API Google Ads è la classe GoogleAdsClient. Ti consente di creare un client di servizi preconfigurato che può essere utilizzato per effettuare chiamate API. Per configurare un oggetto GoogleAdsClient, crea un oggetto GoogleAdsConfig e imposta le proprietà richieste. Per saperne di più, consulta la guida alla configurazione.

// 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";

Creare un servizio

GoogleAdsClient fornisce un metodo GetService che può essere utilizzato per creare un client di servizi API.

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

La libreria fornisce una classe Services che enumera tutte le versioni API supportate (dove le release secondarie come v25.1 utilizzano l'enum della versione principale, Services.V25) e i servizi. Il metodo GetService accetta questi oggetti di enumerazione come argomento durante la creazione del servizio. Ad esempio, per creare un' istanza di CampaignServiceClient per la versione V26 dell' API Google Ads, chiama il metodo GoogleAdsClient.GetService con Services.V26.CampaignService come argomento, come mostrato nell'esempio precedente.

Gestione degli errori

Non tutte le chiamate API vanno a buon fine. Il server può restituire errori se le chiamate API non vanno a buon fine per qualche motivo. È importante acquisire gli errori API e gestirli in modo appropriato.

Quando si verifica un errore API, viene generata un'istanza di GoogleAdsException. Contiene dettagli che ti aiutano a capire cosa è andato storto:

public void Run(GoogleAdsClient client, long customerId)
{
    // Get the GoogleAdsService.
    GoogleAdsServiceClient googleAdsService = client.GetService(
        Services.V26.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 modifica dello stato di configurazione di un'istanza GoogleAdsClient condivisa su più thread non è thread-safe, perché le modifiche alla configurazione apportate a un'istanza in un thread possono influire sui servizi creati su altri thread. Tuttavia, le operazioni di sola lettura, come l'ottenimento di nuove istanze di servizi da un'istanza GoogleAdsClient invariabile e l'esecuzione di chiamate a più servizi in parallelo, sono thread-safe.

Per isolare le modifiche alla configurazione per thread, crea un'istanza separata di GoogleAdsClient per ogni attività o thread di lavoro:

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

Mantenere la reattività dell'applicazione

Le chiamate ai metodi dell'API Google Ads possono richiedere un po' di tempo per essere completate, a seconda delle dimensioni delle richieste. Per mantenere la reattività dell'applicazione, segui questi passaggi:

Utilizzare la libreria Grpc.Core per i framework UI legacy

Se stai sviluppando un'applicazione destinata a .NET Framework e utilizzi una tecnologia UI legacy come ASP.NET Web Forms o WinForms, puoi attivare la libreria di trasporto Grpc.Core legacy nel seguente modo:

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

Utilizzare metodi asincroni

Puoi utilizzare metodi asincroni per mantenere la reattività dell'applicazione. Ecco alcuni esempi.

Recuperare l'elenco delle campagne e popolare un ListView

private async void OnRetrieveCampaignsButtonClick(object sender, EventArgs e)
{
    try
    {
        // Get the GoogleAdsService.
        GoogleAdsServiceClient googleAdsService = client.GetService(
            Services.V26.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}");
    }
}

Aggiornare il budget della campagna e visualizzare un avviso di messaggio

private async void OnUpdateBudgetButtonClick(object sender, EventArgs e)
{
    try
    {
        // Get the CampaignBudgetService.
        CampaignBudgetServiceClient budgetService = client.GetService(
            Services.V26.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}");
    }
}