Comenzar

Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

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

Instalación

Los objetos binarios de la biblioteca cliente se distribuyen mediante 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 el ID de cliente, el secreto de cliente, el token de actualización y el token de desarrollador en la biblioteca.

Si ya tienes credenciales...

  • Copia el nodo GoogleAdsApi y la sección GoogleAdsApi en el nodo configSections del archivo App.config en GitHub a 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 o Web.config.
  • Incluye el token de desarrollador, el ID de cliente, el secreto de cliente y el token de actualización en el archivo App.config o Web.config de tu app. El archivo App.config incluido en GitHub está bien documentado, pero también puedes consultar la Guía de configuración para obtener más información y usar los ajustes de configuración alternativos.

Si necesitas generar credenciales...

  • Si aún no tienes uno, sigue la guía de token del desarrollador para obtenerlo.
  • Sigue la guía de flujo de aplicación de escritorio de OAuth para generar un ID de cliente, un secreto de cliente y un token de actualización.
  • Copia el nodo GoogleAdsApi y la sección GoogleAdsApi en el nodo configSections del archivo App.config en GitHub a 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 o Web.config.
  • Incluye el token de desarrollador, el ID de cliente, el secreto de cliente y el token de actualización en el archivo App.config o Web.config de tu app. El archivo App.config incluido en GitHub está bien documentado, pero también puedes consultar la Guía de configuración para obtener más información y usar los ajustes de configuración alternativos.

Realiza una llamada a la API

A continuación, se muestra el uso básico de la biblioteca cliente:

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

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

// Make more calls to service class.

Cree una instancia de Google Ads Client

Las clases más importantes de la biblioteca .NET de la API de Google Ads son 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 App.config o Web.config de tu app. Consulta la guía de configuración para ver varias opciones de configuración.

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

Creación de servicio

GoogleAdsClient proporciona un método GetService que se puede usar para crear un servicio de Ads.

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

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

Seguridad del subproceso

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

Una aplicación multiproceso se vería así:

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 bloqueos en las aplicaciones de .NET Framework

Los métodos síncronos pueden hacer que algunas de tus aplicaciones de .NET Framework se congelen. Un ejemplo común es realizar llamadas a la API desde un método de controlador de eventos de una aplicación WinForm. Estos son algunos ejemplos del uso de versiones asíncronas de métodos para evitar bloqueos:

Ejemplo 1: se ejecuta una llamada de SearchStream() y los resultados se propagan en una vista de lista.

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

Ejemplo 2: se crea una llamada CampaignBudget y el nombre del recurso del presupuesto nuevo se muestra con una alerta de MessageBox.

private async void button2_Click(object sender, EventArgs e)
{
    // Get the BudgetService.
    CampaignBudgetServiceClient budgetService = client.GetService(
        Services.V13.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<MutateCampaignBudgetsResponse> t = budgetService.MutateCampaignBudgetsAsync(
        customerId.ToString(), new CampaignBudgetOperation[] { budgetOperation });

    await t;
    MutateCampaignBudgetsResponse response = t.Result;
    MessageBox.Show(response.Results[0].ResourceName);
}

Cancela métodos asíncronos

En la programación asíncrona, puedes usar el parámetro callSettings para pasar un CancellationToken:

CancellationTokenSource cancellationTokenSource = new CancellationTokenSource();
cancellationTokenSource.CancelAfter(3000);
CallSettings callSettings = CallSettings.FromCancellationToken(cancellationTokenSource.Token);

string query = "SELECT campaign.name FROM campaign";
var request = new SearchGoogleAdsStreamRequest()
{
    CustomerId = customerId.ToString(),
    Query = query,
};

GoogleAdsServiceClient googleAdsService = client.GetService(
    Services.V13.GoogleAdsService);

googleAdsService.SearchStream(request,
    delegate (SearchGoogleAdsStreamResponse resp)
    {
        foreach (GoogleAdsRow googleAdsRow in resp.Results)
        {
            // Process the row.
        }
    }, callSettings
);

Manejo de errores

No todas las llamadas a la API serán exitosas. El servidor puede generar errores si las llamadas a la API fallan por algún motivo. Es importante capturar los errores de la API y manejarlos de manera adecuada.

Se produce una instancia GoogleAdsException cuando se produce un error de API. Hay detalles que te ayudarán a descubrir qué salió mal:

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