Cómo comenzar

En esta guía, se ofrece una breve descripción general sobre cómo comenzar a utilizar la API de Google Ads. biblioteca .NET.

Instalación

Los objetos binarios de la biblioteca cliente se distribuyen con NuGet. Agrega una referencia de NuGet al paquete Google.Ads.GoogleAds en tu proyecto para usar la biblioteca cliente.

Configura la autorización

Para autorizar las llamadas a la API, debes especificar tu ID de cliente, el secreto del cliente, el token de actualización y el token de desarrollador en la biblioteca.

Si necesitas generar credenciales

Si ya tienes credenciales

  • Copia el nodo GoogleAdsApi y la sección GoogleAdsApi debajo del nodo configSections del archivo App.config en GitHub en tu archivo App.config o Web.config. Si usaste NuGet para instalar el paquete, estos nodos se insertarán automáticamente en tu archivo App.config / Web.config.
  • Incluye el token de desarrollador, el ID de cliente, el secreto de cliente y el token de actualización en el App.config / Web.config de tu app.

La App.config incluido en GitHub está bien documentado, pero también puedes consultar el Guía de configuración para obtener más información y usar formas alternativas de configurar la biblioteca cliente como variables de entorno.

Realiza una llamada a la API

El uso básico de la biblioteca cliente es el siguiente:

// 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 una instancia de GoogleAdsClient

La clase más importante de la biblioteca .NET de la API de Google Ads es la clase GoogleAdsClient. Te permite crear una clase de servicio preconfigurada que se puede usar para realizar llamadas a la API. GoogleAdsClient proporciona un constructor predeterminado que crea un objeto de usuario con la configuración especificada en el App.config o Web.config de tu app. Consulta Configuración de Terraform para la configuración opciones de estado.

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

Cómo crear un Service

GoogleAdsClient proporciona un método GetService que se puede usar para crear una Servicio de anuncios.

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

Proporcionamos una clase Services que enumera todas las versiones y los servicios de la API compatibles. El método GetService acepta estos objetos de enumeración como argumento. cuando crees el servicio. Por ejemplo, para crear una instancia de CampaignServiceClient para la versión V18 de la API de Google Ads debes llamar al método GoogleAdsClient.GetService con Services.V18.CampaignService como argumento, como se muestra en el ejemplo anterior.

Seguridad del subproceso

No es seguro compartir una instancia de GoogleAdsClient entre varios subprocesos. ya que los cambios de configuración que realices en una instancia en un subproceso afectará a los servicios que crees en otros subprocesos. Las operaciones como obtener instancias de servicio nuevas de una instancia de GoogleAdsClient y realizar llamadas a varios servicios en paralelo son seguras para el subproceso.

Una aplicación con varios subprocesos se vería de la siguiente manera:

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

Evita las fallas en las aplicaciones de .NET Framework

Los métodos síncronos pueden hacer que algunas de tus aplicaciones de .NET Framework se bloqueen. Un ejemplo común es realizar llamadas a la API desde un método de controlador de eventos de una aplicación de WinForms.

Existen dos maneras de abordar este problema:

  1. Usa la biblioteca heredada de Grpc.

    Puedes configurar la propiedad UseGrpcCore de GoogleAdsConfig para usar el elemento biblioteca Grpc.Core heredada en lugar de la biblioteca predeterminada Grpc.Net.Client. Este método no se probó en profundidad en aplicaciones de .NET Framework, por lo que es posible que no resuelva el problema. Aquí hay un fragmento de muestra:

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

    La página de asistencia de gRPC tiene más detalles sobre las diferencias entre la biblioteca Grpc.Core heredada y la biblioteca Grpc.Net.Client predeterminada.

  2. Usa métodos asíncronos.

    Puedes usar métodos asíncronos para evitar que se bloqueen. Estos son algunos ejemplos:

    SearchStream

    Se realiza una llamada a SearchStream() y se obtienen los resultados. propagado en una vista de lista.

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

    Presupuesto de la campaña

    Se crea una llamada a CampaignBudget y el nombre del recurso del presupuesto nuevo se muestra con una alerta 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);
}

Manejo de errores

No todas las llamadas a la API se realizarán correctamente. El servidor puede generar errores si tu API llama fallar por alguna razón. Es importante capturar los errores de la API y controlarlos de manera adecuada.

Se genera una instancia de GoogleAdsException cuando se produce un error de API. Tiene detalles para ayudarte a descubrir qué salió mal:

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