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.

Inizializza il client e i servizi

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

Crea un'istanza GoogleAdsClient

La classe più importante nella libreria .NET dell'API Google Ads è la classe GoogleAdsClient. Ti 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 del servizio API.

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

La libreria fornisce una classe Services che enumera tutte le versioni dell'API supportate (dove le release secondarie come v26.1 utilizzano l'enum della versione principale, Services.V26) 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 dell'API e gestirli in modo appropriato.

Viene generata un'istanza GoogleAdsException quando si verifica un errore dell'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.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 in altri thread. Tuttavia, le operazioni di sola lettura, come l'ottenimento di nuove istanze di servizio da un'istanza GoogleAdsClient invariata 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 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.
}

Mantieni l'applicazione reattiva

Il completamento delle chiamate ai metodi dell'API Google Ads può richiedere del tempo, a seconda delle dimensioni delle richieste. Per mantenere l'applicazione reattiva, segui questi passaggi:

Utilizza la libreria Grpc.Core per i framework UI legacy

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 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 l'applicazione reattiva. 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.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}");
    }
}

Aggiorna il budget della campagna e visualizza un avviso in una finestra 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}");
    }
}