Bibliotecas cliente

Las bibliotecas cliente de la API de Google Ads proporcionan vistas de alto nivel y componentes básicos de la funcionalidad de la API de Google Ads, lo que facilita el desarrollo rápido de aplicaciones. Si es la primera vez que usas la API, comienza con una biblioteca cliente.

Biblioteca cliente	Fuente	Distribución	Ejemplos de código
Java	google-ads-java	Maven, tar.gz, zip	Ver en GitHub
.NET	google-ads-dotnet	NuGet, tar.gz, zip	Ver en GitHub
PHP	google-ads-php	Composer, tar.gz, zip	Ver en GitHub
Python	google-ads-python	PyPI, tar.gz, zip	Ver en GitHub
Ruby	google-ads-ruby	RubyGems, tar.gz, zip	Ver en GitHub
Perl	google-ads-perl	CPAN, tar.gz, zip	Ver en GitHub

Bibliotecas de la comunidad

Conocemos varias bibliotecas que mantiene la comunidad de código abierto. Mantenemos esta lista para ayudar a los desarrolladores interesados a encontrarlos. No probamos, contribuimos ni mantenemos estas bibliotecas. Úsalas bajo tu propio riesgo. Si tienes alguna pregunta, dirígela a los propietarios de los proyectos de código abierto.

Si conoces alguna biblioteca que no incluimos, haz clic en Enviar comentarios en la parte superior de la página y avísanos.

• Node.js: google-ads-api en npm
• Go: google-ads-pb en GitHub

Versiones de API compatibles

En la tabla, se muestran las bibliotecas cliente que funcionan con cada versión de la API.

La versión mínima de la biblioteca cliente que se indica es suficiente para la versión principal de la API de Google Ads (como la versión v25). Para ver la versión de la biblioteca cliente requerida para las versiones secundarias, consulta el registro de cambios vinculado.

Java

Registro de cambios

API de Google Ads	Biblioteca cliente para Java
v25	Min: 44.0.0 Max: -
v24	Min: 43.0.0 Max: -
v23	Min: 42.0.0 Max: -
v22	Min: 41.0.0 Max: -

C#

Registro de cambios

API de Google Ads	Biblioteca cliente para .NET
v25	Min: 26.1.0 Max: -
v24	Min: 25.3.0 Max: -
v23	Min: 25.1.0 Max: -
v22	Min: 24.1.0 Max: -

PHP

Registro de cambios

API de Google Ads	Biblioteca cliente para PHP
v25	Min: 33.6.0 Max: -
v24	Min: 33.3.0 Max: -
v23	Min: 32.2.0 Max: -
v22	Min: 31.0.0 Max: -

Python

Registro de cambios

API de Google Ads	Biblioteca cliente para Python
v25	Min: 31.2.0 Max: -
v24	Min: 30.1.0 Max: -
v23	Min: 29.2.0 Max: -
v22	Min: 28.1.0 Max: 32.0.0

Ruby

Registro de cambios

API de Google Ads	Biblioteca cliente para Ruby
v25	Min: 43.0.0 Max: -
v24	Min: 40.0.0 Max: -
v23	Min: 38.0.0 Max: -
v22	Min: 36.0.0 Max: -

Perl

Registro de cambios

API de Google Ads	Biblioteca cliente para Perl
v25	Min: 33.0.0 Max: -
v24	Min: 32.0.0 Max: -
v23	Min: 31.0.0 Max: -
v22	Min: 29.0.0 Max: -

Configuración

Cada biblioteca cliente de la API de Google Ads proporciona diferentes parámetros de configuración y métodos de carga que puedes usar para personalizar su comportamiento.

Estas son las variables de entorno estándar que puedes usar para configurar las bibliotecas cliente:

• Biblioteca cliente
  • GOOGLE_ADS_CONFIGURATION_FILE_PATH: Ruta de acceso al archivo de configuración (se lee automáticamente cuando se carga desde un archivo de configuración sin un argumento de ruta de acceso explícito en Java [fromPropertiesFile()], Perl [Client->new()], PHP [fromFile()], Python [load_from_storage() y también verificado por load_from_env()] y Ruby [GoogleAdsClient.new]; en .NET, carga esta variable de forma explícita con config.TryLoadFromEnvironmentFilePath o carga archivos de configuración con LoadFromSettingsJson, LoadFromConfigurationSection o LoadFromConfigurationRoot).
• OAuth2
  • Modo de aplicación
    • GOOGLE_ADS_CLIENT_ID: Configura este valor en tu ID de cliente de OAuth2.
    • GOOGLE_ADS_CLIENT_SECRET: Configura este valor en el secreto de tu cliente de OAuth 2.
    • GOOGLE_ADS_REFRESH_TOKEN: Establece este valor en un token de actualización de OAuth2 generado previamente si deseas reutilizar tokens de OAuth2. Este parámetro de configuración es opcional.
  • Modo de cuenta de servicio
    • GOOGLE_ADS_JSON_KEY_FILE_PATH: Establece este valor en la ruta de acceso a tu archivo de clave JSON de OAuth2 (en .NET, también establece GOOGLE_ADS_OAUTH2_MODE en SERVICE_ACCOUNT, ya que OAuth2Mode se establece de forma predeterminada en APPLICATION; en versiones de PHP anteriores a v32.1.0 o cuando se usan alcances personalizados, también establece [OAUTH2] scopes en google_ads_php.ini o llama a withScopes(), ya que fromEnvironmentVariables() no lee los alcances de OAuth2 desde una variable de entorno).
    • GOOGLE_ADS_IMPERSONATED_EMAIL: Establece este valor en la dirección de correo electrónico de la cuenta que suplantas cuando usas la delegación a nivel del dominio de Google Workspace. Este parámetro de configuración es opcional
  • Modo de credenciales predeterminadas de la aplicación
    • GOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS: Establece este valor en true para autenticarte con las credenciales predeterminadas de la aplicación (ADC). Se admite en Java v41.1.0 y versiones posteriores, Python v28.3.0 y versiones posteriores, y Ruby v36.1.0 y versiones posteriores (en .NET v24.1.0 y versiones posteriores, LoadFromEnvironmentVariables() lee la variable USE_APPLICATION_DEFAULT_CREDENTIALS sin prefijo; también puedes establecer UseApplicationDefaultCredentials = true en GoogleAdsConfig; en PHP, OAuth2TokenBuilder recurre automáticamente a las ADC cuando no se establecen credenciales explícitas de OAuth2; Perl no admite las ADC).
• API de Google Ads
  • GOOGLE_ADS_DEVELOPER_TOKEN: Opcional en las versiones más recientes (Java v46.0.0 y versiones posteriores, .NET v27.3.0 y versiones posteriores, PHP v35.0.0 y versiones posteriores, Python v32.0.0 y versiones posteriores, Ruby v45.0.0 y versiones posteriores, y Perl v35.0.0 y versiones posteriores). Los tokens de desarrollador dejaron de estar disponibles el 9 de septiembre de 2026, y los servidores de la API ignoran el encabezado developer-token independientemente de la versión de la biblioteca cliente (hasta que una versión principal futura de la API de Google Ads lo rechace). Las versiones anteriores de la biblioteca cliente aún requieren un valor no vacío para la validación local del cliente. Consulta la guía de configuración de cada biblioteca para obtener detalles específicos de la versión.
  • GOOGLE_ADS_LOGIN_CUSTOMER_ID: Es el ID del cliente autorizado para usar en la solicitud, sin guiones (-).
  • GOOGLE_ADS_LINKED_CUSTOMER_ID: Este encabezado solo es obligatorio para los métodos que actualizan los recursos de una entidad cuando se otorgan permisos a través de las cuentas vinculadas en la IU de Google Ads (recurso AccountLink en la API de Google Ads). Establece este valor en el ID de cliente del proveedor de datos que actualiza los recursos del ID de cliente especificado. Debe configurarse sin guiones (-). Para obtener más información sobre las cuentas vinculadas, visita el Centro de ayuda.

Nota: Para obtener más detalles sobre cómo usarlas y conocer las variables de entorno adicionales específicas de cada biblioteca cliente, consulta las guías de configuración dedicadas a cada biblioteca cliente: Java, .NET, PHP, Python, Ruby y Perl.

Las variables de entorno se suelen definir en un archivo de configuración de bash, como un archivo .bashrc o .bash_profile ubicado en el directorio $HOME. También se pueden definir con la línea de comandos.

Nota: En estas instrucciones, se supone que usas Bash. Si usas otra shell, consulta la documentación para conocer los comandos equivalentes.

Estos son algunos pasos básicos para definir una variable de entorno con un archivo .bashrc a través de una terminal:

# Append the line "export GOOGLE_ADS_CLIENT_ID=1234567890" to
# the bottom of your .bashrc file.
echo "export GOOGLE_ADS_CLIENT_ID=1234567890" >> ~/.bashrc

# Update your bash environment to use the most recently updated
# version of your .bashrc file.
source ~/.bashrc

También puedes establecer variables de entorno en tu instancia de terminal directamente desde la línea de comandos:

export GOOGLE_ADS_CLIENT_ID=1234567890

Otra alternativa es establecer variables de entorno cuando se llama al comando que las usa:

GOOGLE_ADS_CLIENT_ID=1234567890 php /path/to/script/that/uses/envvar.php

Recupera entidades

Por lo general, GoogleAdsService.SearchStream se usa para recuperar entidades, y los resultados se devuelven como un flujo de filas. Como alternativa, puedes usar GoogleAdsService.Search para recuperar entidades a través de una conexión a Internet poco confiable. GoogleAdsService.Search devuelve resultados como tamaños de página fijos de 10,000 filas por página.

Las bibliotecas cliente implementan la paginación automáticamente cuando iteras los resultados para que puedas descargarlos y procesarlos todos de forma secuencial.

Java

private void runExample(GoogleAdsClient googleAdsClient, long customerId) {
  try (GoogleAdsServiceClient googleAdsServiceClient =
      googleAdsClient.getLatestVersion().createGoogleAdsServiceClient()) {
    String query = "SELECT campaign.id, campaign.name FROM campaign ORDER BY campaign.id";
    // Constructs the SearchGoogleAdsStreamRequest.
    SearchGoogleAdsStreamRequest request =
        SearchGoogleAdsStreamRequest.newBuilder()
            .setCustomerId(Long.toString(customerId))
            .setQuery(query)
            .build();

    // Creates and issues a search Google Ads stream request that will retrieve all campaigns.
    ServerStream<SearchGoogleAdsStreamResponse> stream =
        googleAdsServiceClient.searchStreamCallable().call(request);

    // Iterates through and prints all of the results in the stream response.
    for (SearchGoogleAdsStreamResponse response : stream) {
      for (GoogleAdsRow googleAdsRow : response.getResultsList()) {
        System.out.printf(
            "Campaign with ID %d and name '%s' was found.%n",
            googleAdsRow.getCampaign().getId(), googleAdsRow.getCampaign().getName());
      }
    }
  }
}
GetCampaigns.java
      

C#

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;
    }
}
GetCampaigns.cs
      

PHP

public static function runExample(GoogleAdsClient $googleAdsClient, int $customerId)
{
    $googleAdsServiceClient = $googleAdsClient->getGoogleAdsServiceClient();
    // Creates a query that retrieves all campaigns.
    $query = 'SELECT campaign.id, campaign.name FROM campaign ORDER BY campaign.id';
    // Issues a search stream request.
    /** @var GoogleAdsServerStreamDecorator $stream */
    $stream = $googleAdsServiceClient->searchStream(
        SearchGoogleAdsStreamRequest::build($customerId, $query)
    );

    // Iterates over all rows in all messages and prints the requested field values for
    // the campaign in each row.
    foreach ($stream->iterateAllElements() as $googleAdsRow) {
        /** @var GoogleAdsRow $googleAdsRow */
        printf(
            "Campaign with ID %d and name '%s' was found.%s",
            $googleAdsRow->getCampaign()->getId(),
            $googleAdsRow->getCampaign()->getName(),
            PHP_EOL
        );
    }
}
GetCampaigns.php
      

Python

def main(client: GoogleAdsClient, customer_id: str) -> None:
    ga_service: GoogleAdsServiceClient = client.get_service("GoogleAdsService")

    query: str = """
        SELECT
          campaign.id,
          campaign.name
        FROM campaign
        ORDER BY campaign.id"""

    # Issues a search request using streaming.
    stream: Iterator[SearchGoogleAdsStreamResponse] = ga_service.search_stream(
        customer_id=customer_id, query=query
    )

    for batch in stream:
        rows: List[GoogleAdsRow] = batch.results
        for row in rows:
            print(
                f"Campaign with ID {row.campaign.id} and name "
                f'"{row.campaign.name}" was found.'
            )
get_campaigns.py
      

Ruby

def get_campaigns(customer_id)
  # GoogleAdsClient will read a config file from
  # ENV['HOME']/google_ads_config.rb when called without parameters
  client = Google::Ads::GoogleAds::GoogleAdsClient.new

  responses = client.service.google_ads.search_stream(
    customer_id: customer_id,
    query: 'SELECT campaign.id, campaign.name FROM campaign ORDER BY campaign.id',
  )

  responses.each do |response|
    response.results.each do |row|
      puts "Campaign with ID #{row.campaign.id} and name '#{row.campaign.name}' was found."
    end
  end
end
get_campaigns.rb
      

Perl

sub get_campaigns {
  my ($api_client, $customer_id) = @_;

  # Create a search Google Ads stream request that will retrieve all campaigns.
  my $search_stream_request =
    Google::Ads::GoogleAds::V25::Services::GoogleAdsService::SearchGoogleAdsStreamRequest
    ->new({
      customerId => $customer_id,
      query      =>
        "SELECT campaign.id, campaign.name FROM campaign ORDER BY campaign.id"
    });

  # Get the GoogleAdsService.
  my $google_ads_service = $api_client->GoogleAdsService();

  my $search_stream_handler =
    Google::Ads::GoogleAds::Utils::SearchStreamHandler->new({
      service => $google_ads_service,
      request => $search_stream_request
    });

  # Issue a search request and process the stream response to print the requested
  # field values for the campaign in each row.
  $search_stream_handler->process_contents(
    sub {
      my $google_ads_row = shift;
      printf "Campaign with ID %d and name '%s' was found.\n",
        $google_ads_row->{campaign}{id}, $google_ads_row->{campaign}{name};
    });

  return 1;
}
get_campaigns.pl
      

curl

Nota: Si bien aquí no se proporciona una muestra de código de REST directa para este paso, puedes lograrlo con una solicitud de REST manual.

Consulta la documentación de la interfaz de REST de la API de Google Ads y las páginas de referencia específicas del método. Deberás construir la carga útil JSON según las definiciones de .proto.

Recursos clave:

• Uso de REST
• Estructura de la interfaz de REST
• Asignaciones de campos JSON
• Consulta la referencia de la API de REST para el servicio y el método específicos.

Ejemplos de código

Consulta nuestros ejemplos de código de algunas funciones comunes en la API de Google Ads.