En esta guía, se ofrece una breve descripción general de cómo comenzar a usar la biblioteca .NET de la API de Google Ads.
Instalación
Los objetos binarios de la biblioteca cliente se distribuyen con NuGet. Agrega una referencia de Nuget al paquete Google.Ads.GoogleAds
de 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 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ónGoogleAdsApi
en el nodoconfigSections
del archivoApp.config
en GitHub en tu archivoApp.config
/Web.config
. Si usaste NuGet para instalar el paquete, estos nodos se insertarán automáticamente en tu archivoApp.config
/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
/Web.config
de tu app. El archivoApp.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 parámetros de configuración alternativos.
Si necesitas generar credenciales...
- Sigue la guía de tokens de desarrollador para obtener tu token de desarrollador si aún no lo tienes.
- Sigue la guía de flujo de la 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ónGoogleAdsApi
en el nodoconfigSections
del archivoApp.config
en GitHub en tu archivoApp.config
/Web.config
. Si usaste NuGet para instalar el paquete, estos nodos se insertarán automáticamente en tu archivoApp.config
/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
/Web.config
de tu app. El archivoApp.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 parámetros 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.V17.CampaignService);
// Make more calls to service class.
Crea una instancia de GoogleAdsClient
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 usando la configuración especificada en App.config
/ Web.config
de tu app. Consulta la Guía de configuración para conocer varias opciones de configuración.
// 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 un servicio de Google Ads.
CampaignServiceClient campaignService = client.GetService(Services.V17.CampaignService);
// Now make calls to CampaignService.
Proporcionamos una clase Services
que enumera todos los servicios y las versiones de la API compatibles. El método GetService
acepta estos objetos de enumeración como argumento cuando se crea el servicio. Por ejemplo, si deseas crear una instancia de CampaignServiceClient
para la versión V17
de la API de Google Ads, debes llamar al método GoogleAdsClient.GetService
con Services.V17.CampaignService
como argumento, como se mostró anteriormente.
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 podrían afectar los servicios que creas en otros subprocesos. Las operaciones como la obtención de instancias de servicio nuevas desde una instancia de GoogleAdsClient
y las llamadas a varios servicios en paralelo, etc., son seguras para los subprocesos.
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 las aplicaciones de .NET Framework se bloqueen. Un ejemplo común consiste en realizar llamadas a la API desde un método de controlador de eventos de una aplicación WinForm.
Existen dos maneras de abordar este problema:
Usa la biblioteca de Grpc heredada.
Puedes configurar la propiedad
UseGrpcCore
deGoogleAdsConfig
para usar la bibliotecaGrpc.Core
heredada en lugar de la bibliotecaGrpc.Net.Client
predeterminada. Este método no se probó ampliamente 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);
Usa métodos asíncronos.
Puedes usar métodos asíncronos para evitar bloqueos. Estos son algunos ejemplos:
SearchStream
Se realiza una llamada a
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.V17.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 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.V17.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); }
Cancela métodos asíncronos
Para 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.V17.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 tendrán éxito. 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 forma adecuada.
Se arroja 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.V17.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}");
}