Uso básico

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

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

Inicializa el cliente y los servicios

Para interactuar con la API de Google Ads, primero configura y crea una instancia de GoogleAdsClient y, luego, úsala para crear los clientes de servicio de la API específicos que necesites.

Crear una instancia de GoogleAdsClient

La clase más importante de la biblioteca de la API de Google Ads para .NET es la clase GoogleAdsClient. Te permite crear un cliente de servicio preconfigurado que se puede usar para realizar llamadas a la API. Para configurar un objeto GoogleAdsClient, crea un objeto GoogleAdsConfig y establece las propiedades requeridas. Consulta la guía de configuración para obtener más información.

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

Crear un servicio

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

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

La biblioteca proporciona una clase Services que enumera todas las versiones de API compatibles (en las que las versiones secundarias, como v25.1, usan su enumeración de versión principal, Services.V25) y los servicios. El método GetService acepta estos objetos de enumeración como argumento cuando se crea el servicio. Por ejemplo, para crear una instancia de CampaignServiceClient para la versión V25 de la API de Google Ads, llama al método GoogleAdsClient.GetService con Services.V25.CampaignService como argumento, como se muestra en el ejemplo anterior.

Manejo de errores

No todas las llamadas a la API se realizan correctamente. El servidor puede mostrar errores si tus llamadas a la API fallan por algún motivo. Es importante capturar los errores de la API y controlarlos de forma adecuada.

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

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

Seguridad del subproceso

Modificar el estado de configuración de una instancia de GoogleAdsClient compartida en varios subprocesos no es seguro para subprocesos, ya que los cambios de configuración que realices en una instancia en un subproceso pueden afectar los servicios que crees en otros subprocesos. Sin embargo, las operaciones de solo lectura, como obtener nuevas instancias de servicio a partir de una instancia de GoogleAdsClient que no cambia y realizar llamadas a varios servicios en paralelo, son seguras para subprocesos.

Para aislar los cambios de configuración por subproceso, crea una instancia de un objeto GoogleAdsClient independiente por tarea o subproceso de trabajador:

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

Mantén la capacidad de respuesta de tu aplicación

Las llamadas a métodos de la API de Google Ads pueden tardar en completarse, según el tamaño de las solicitudes. Para que tu aplicación siga respondiendo, sigue estos pasos:

Usa la biblioteca Grpc.Core para frameworks de IU heredados

Si desarrollas una aplicación que tiene como objetivo .NET Framework y usa una tecnología de IU heredada, como ASP.NET Web Forms o WinForms, puedes habilitar la biblioteca de transporte Grpc.Core heredada de la siguiente manera:

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

Usar métodos asíncronos

Puedes usar métodos asíncronos para que tu aplicación siga respondiendo. Aquí tienes algunos ejemplos.

Recupera la lista de campañas y propaga 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}");
    }
}

Actualiza el presupuesto de una campaña y muestra un mensaje de alerta

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