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

// Make calls to the service client.

Inizializza il client e i servizi

Per interagire con l'API Google Ads, configura e crea un'istanza di un GoogleAdsClient, quindi utilizzalo per creare i client di servizio API specifici di cui hai bisogno.

Crea un'istanza GoogleAdsClient

La classe più importante nella libreria .NET dell'API Google Ads è la classe GoogleAdsClient. Consente di creare un client di servizio 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";

Crea un servizio

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

CampaignServiceClient campaignService = client.GetService(
    Services.V25.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'enumerazione 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 V25 dell'API Google Ads, chiama il metodo GoogleAdsClient.GetService con Services.V25.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.

Viene generata un'istanza GoogleAdsException quando si verifica un errore API. 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.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;
    }
}

Sicurezza dei thread

La modifica dello stato di configurazione di un'istanza GoogleAdsClient condivisa in più thread non è thread-safe, perché le modifiche alla configurazione apportate a un'istanza in un thread possono influire sui servizi creati in altri thread. Tuttavia, le operazioni di sola lettura come l'ottenimento di nuove istanze di servizio 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 di un GoogleAdsClient separato per ogni attività o thread del worker:

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 precedenti

Se stai sviluppando un'applicazione che ha come target .NET Framework e utilizza una tecnologia UI legacy come ASP.NET Web Forms o WinForms, puoi abilitare la libreria di trasporto legacy Grpc.Core 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 un paio di esempi.

Recupera l'elenco delle campagne e compila 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}");
    }
}

Aggiornare il budget della campagna e visualizzare una casella di messaggio di avviso

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