Per iniziare

Questa guida fornisce una breve panoramica su come iniziare a utilizzare la libreria .NET dell'API Google Ads.

Installazione

I file binari della libreria client vengono distribuiti utilizzando NuGet. Aggiungi un riferimento NuGet al Google.Ads.GoogleAds package nel tuo progetto per utilizzare la libreria client.

Configura l'autorizzazione

Per autorizzare le chiamate API, devi specificare l'ID cliente, il segreto client, il token di aggiornamento e il token sviluppatore alla libreria.

Se devi generare le credenziali

Se hai già le credenziali

  • Copia il nodo GoogleAdsApi e la sezione GoogleAdsApi sotto il nodo configSections dal file App.config su GitHub nel file App.config / Web.config. Se hai utilizzato NuGet per installare il pacchetto, questi nodi verranno inseriti automaticamente nel file App.config / Web.config.
  • Includi il token sviluppatore, l'ID client, il client secret e il token di aggiornamento in App.config / Web.config della tua app.

Il file App.config incluso in GitHub è ben documentato, ma puoi anche consultare la guida alla configurazione per saperne di più e utilizzare metodi alternativi per configurare la libreria client, come le variabili d'ambiente.

Esegui una chiamata API

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

// Create a Google Ads client.
GoogleAdsClient client = new GoogleAdsClient();

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

// Make more calls to service class.

Crea un'istanza GoogleAdsClient

La classe più importante della libreria .NET dell'API Google Ads è la classeGoogleAdsClient. Ti consente di creare una classe di servizio preconfigurata che può essere utilizzata per effettuare chiamate API. GoogleAdsClient fornisce un costruttore predefinito che crea un oggetto utente utilizzando le impostazioni specificate in App.config / Web.config della tua app. Per le opzioni di configurazione, consulta la guida alla configurazione.

// Create a new GoogleAdsClient with the App.config settings.
GoogleAdsClient user = new GoogleAdsClient();

Creare un servizio

GoogleAdsClient fornisce un metodo GetService che può essere utilizzato per creare un servizio Google Ads.

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

Forniamo una classe Services che enumera tutte le versioni e tutti i servizi API supportati. 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 V18 dell'API Google Ads, devi chiamare il metodo GoogleAdsClient.GetService con Services.V18.CampaignService come argomento, come mostrato nell'esempio precedente.

Thread safety

Non è sicuro condividere un'istanza GoogleAdsClient tra più thread, poiché le modifiche alla configurazione apportate a un'istanza in un thread potrebbero influire sui servizi creati in altri thread. Operazioni come l'ottenimento di nuove istanze di servizio da un'istanza GoogleAdsClient ed effettuare chiamate a più servizi in parallelo sono sicure per i thread.

Un'applicazione multithread avrà il seguente aspetto:

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

Evitare blocchi nelle applicazioni .NET Framework

I metodi sincroni possono causare il blocco di alcune applicazioni .NET Framework. Un esempio comune è l'esecuzione di chiamate API da un metodo di gestore eventi di un'applicazione WinForm.

Esistono due modi per risolvere il problema:

  1. Utilizza la libreria Grpc precedente.

    Puoi impostare la proprietà UseGrpcCore di GoogleAdsConfig in modo da utilizzare la libreria Grpc.Core precedente anziché la libreria Grpc.Net.Client predefinita. Questo metodo non è stato testato ampiamente sulle applicazioni .NET Framework, quindi potrebbe non risolvere il problema. Ecco uno snippet di esempio:

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

  2. Utilizza metodi asincroni.

    Puoi utilizzare metodi asincroni per evitare blocchi. Ecco alcuni esempi:

    SearchStream

    Viene eseguita una chiamata a SearchStream() e i risultati vengono compilati in una visualizzazione elenco.

    private async void button1_Click(object sender, EventArgs e)
{
// Get the GoogleAdsService.
GoogleAdsServiceClient googleAdsService = client.GetService(
    Services.V18.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 della campagna

    Viene creata una chiamata CampaignBudget e il nome della risorsa del nuovo budget viene visualizzato utilizzando un avviso MessageBox.

    private async void button2_Click(object sender, EventArgs e)
{
// Get the BudgetService.
CampaignBudgetServiceClient budgetService = client.GetService(
    Services.V18.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);
}

Gestione degli errori

Non tutte le chiamate API andranno a buon fine. Il server può generare errori se le chiamate API non vanno a buon fine per qualche motivo. È importante acquisire gli errori dell'API e gestirli adeguatamente.

Un'istanza GoogleAdsException viene lanciata quando si verifica un errore dell'API. Contiene dettagli che ti aiutano a capire cosa è andato storto:

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