Inicio rápido

Esta guía de inicio rápido te ayuda a realizar tu primera llamada a la API de Google Ads.

Conceptos clave

  • Token de desarrollador: Un token de desarrollador es una cadena alfanumérica de 22 caracteres que identifica tu aplicación en los servidores de la API de Google Ads. Es necesario para realizar llamadas a la API.
  • Nivel de acceso a la API: El nivel de acceso a la API de tu token de desarrollador controla la cantidad de llamadas a la API que puedes realizar por día y los entornos a los que puedes realizar llamadas a la API.
  • Cuenta de administrador de Google Ads: Se utiliza para administrar otras cuentas de Google Ads. Una cuenta de administrador de Google Ads se puede utilizar para administrar cuentas de cliente de Google Ads o bien otras cuentas de administrador de Google Ads. Necesitas una cuenta de administrador de Google Ads para obtener un token de desarrollador.
  • Cuenta de cliente de Google Ads: Es la cuenta de Google Ads con la que realizas llamadas a la API.
  • ID de cliente del cliente: Es el número de 10 dígitos que identifica una cuenta de cliente de Google Ads.
  • OAuth 2.0: OAuth 2.0 es un protocolo estándar de la industria para la autorización que usan todas las APIs de Google. Necesitas una cuenta de servicio y una clave para generar credenciales de OAuth 2.0 y realizar llamadas a la API.
  • Proyecto de Google Cloud: Un proyecto de Google Cloud constituye la base para crear, habilitar y usar todos los servicios de Google, incluida la administración de las APIs y las credenciales de la API de OAuth 2.0. Puedes crear una desde la consola de Google Cloud.
  • Cuenta de servicio: Es un tipo especial de Cuenta de Google que pertenece a tu aplicación, en lugar de a un usuario individual. Se usa para autenticar tu aplicación en la API de Google Ads. Necesitas un proyecto de Google Cloud para obtener una cuenta de servicio.
  • Clave de la cuenta de servicio: Es un archivo de credenciales de la app en formato JSON que contiene la clave privada de tu cuenta de servicio. Se usa para generar credenciales de OAuth 2.0 para autenticar una cuenta de servicio cuando se realiza una llamada a la API de la API de Google Ads. Necesitas una cuenta de servicio para obtener una clave de cuenta de servicio.

Requisitos previos

Para realizar una llamada a la API de Google Ads, debes completar los siguientes pasos.

Obtén tu token de desarrollador

Si te registraste para obtener un token de desarrollador en el pasado, puedes encontrarlo en el Centro de APIs mientras accedes a tu cuenta de administrador de Google Ads.

Accede al Centro de APIs

Si no tienes un token de desarrollador, puedes registrarte para obtener uno en el Centro de APIs.

Cómo registrarse para obtener un token de desarrollador

  1. Navega al Centro de APIs en tu navegador web. Accede a tu cuenta de administrador de Google Ads si se te solicita. Crea una cuenta de administrador de Google Ads si no tienes una.
  2. Completa el formulario de acceso a la API y acepta los Términos y Condiciones.
    • Asegúrate de que tu información sea correcta y de que la URL del sitio web de tu empresa funcione. Si el sitio web no está activo, es posible que Google no pueda procesar tu solicitud y la rechace.
    • Asegúrate de que el correo electrónico de contacto de la API que proporciones dirija a una bandeja de entrada que se supervise con regularidad. Es posible que el equipo de cumplimiento de la API de Google se comunique con esta dirección de correo electrónico durante el proceso de revisión para solicitar aclaraciones. Si no se pueden comunicar contigo, es posible que Google no continúe con tu solicitud.
    • Puedes editar tu correo electrónico de contacto de la API en el Centro de APIs. Mantén esta información actualizada, incluso después del proceso de solicitud, para que Google pueda enviarte anuncios de servicio importantes.

Después de completar el proceso de solicitud, el token de desarrollador aparecerá en tu Centro de API con el estado Aprobación pendiente. Tu token de desarrollador ahora tiene el nivel de acceso Test Account Access.

Configura tu proyecto de la Consola de APIs de Google

El proyecto de la Consola de APIs de Google se usa para administrar las APIs de Google y las credenciales de la API de OAuth 2.0. Para encontrar tus proyectos existentes de la Consola de APIs de Google o crear uno, visita la Consola de APIs de Google.

Abrir la consola de APIs de Google

Para comenzar, habilita la API de Google Ads en tu proyecto:

Habilita la API de Google Ads

A continuación, necesitas una cuenta de servicio y una clave de cuenta de servicio para realizar llamadas a la API. Si ya usas otra API de Google y creaste una cuenta de servicio y una clave de OAuth 2.0, puedes omitir este paso y reutilizar las credenciales existentes.

Cómo crear una cuenta de servicio y una clave

  1. En el menú de la consola de Google Cloud, ve a > IAM y administración > Cuentas de servicio.

    Ir a Cuentas de servicio

  2. Selecciona tu cuenta de servicio.
  3. Haz clic en Claves > Agregar clave > Crear clave nueva.
  4. Selecciona JSON y, luego, haz clic en Crear.

    Se generará y descargará el nuevo par de claves pública/privada en tu equipo como un archivo nuevo. Guarda el archivo JSON descargado como credentials.json en tu directorio de trabajo. Este archivo es la única copia de esta clave.

  5. Haz clic en Cerrar.

Comienza por identificar la cuenta de Google Ads con la que realizas llamadas a la API. El tipo de cuenta a la que puedes hacer llamadas a la API depende del nivel de acceso a la API de tu token de desarrollador. Consulta tu Centro de APIs para conocer tu nivel de acceso a la API.

Acceso básico y estándar

Puedes hacer llamadas a tu cuenta de producción de Google Ads. Sin embargo, puedes crear una cuenta de prueba de Google Ads siguiendo las instrucciones de la pestaña Acceso a la cuenta de prueba si es necesario.

Acceso a la cuenta de prueba

Tu token de desarrollador no se puede usar para realizar llamadas a la API a una cuenta de producción de Google Ads. Solo puedes realizar llamadas a la API en cuentas de prueba de Google Ads.

Cómo crear una cuenta de prueba de Google Ads

Las siguientes instrucciones crean una cuenta de administrador de prueba de Google Ads y una cuenta de anunciante de prueba de Google Ads debajo de ella.

  1. Haz clic en el botón azul para crear una cuenta de administrador de prueba de Google Ads. Si se te solicita, accede con una Cuenta de Google que no esté vinculada a tu cuenta de administrador de producción de Google Ads. Si no tienes una, usa el botón Crear cuenta de esa página para crear una Cuenta de Google nueva.

    Cómo crear una cuenta de administrador de prueba de Google Ads

  2. Mientras estás en tu cuenta de administrador de pruebas de Google Ads, crea una cuenta de cliente de prueba de Google Ads: Haz clic en Cuentas > > Crear cuenta nueva y completa el formulario. Las cuentas de Google Ads que crees desde tu cuenta de administrador de prueba de Google Ads serán automáticamente cuentas de prueba de Google Ads.
  3. De manera opcional, crea algunas campañas en la cuenta de cliente de prueba de Google Ads desde la página de Google Ads.

Para hacer una llamada a la API a un cliente de Google Ads, debes otorgar acceso y los permisos adecuados a tu cuenta de servicio para la cuenta de cliente de Google Ads. Para ello, debes tener acceso de administrador a la cuenta del cliente.

Cómo otorgar acceso a la cuenta de servicio a tu cuenta de Google Ads

  1. Para comenzar, accede a tu cuenta de Google Ads como administrador.
  2. Navega a Administrador > Acceso y seguridad.
  3. Haz clic en el botón en la pestaña Usuarios.
  4. Escribe la dirección de correo electrónico de la cuenta de servicio en la casilla de entrada Correo electrónico. Selecciona el nivel de acceso a la cuenta adecuado y haz clic en el botón Agregar cuenta. Ten en cuenta que el nivel de acceso al correo electrónico no es compatible con las cuentas de servicio.
  5. Se otorga acceso a la cuenta de servicio.
  6. [Opcional] De forma predeterminada, no puedes otorgar acceso de administrador a una cuenta de servicio. Si tus llamadas a la API requieren acceso de administrador, puedes actualizar el acceso de la siguiente manera.
    1. Haz clic en la flecha desplegable que se encuentra junto al nivel de acceso de la cuenta de servicio en la columna Nivel de acceso.
    2. Selecciona Administrador en la lista desplegable.

Descarga herramientas y bibliotecas cliente

Puedes descargar una biblioteca cliente o un cliente HTTP según cómo desees realizar las llamadas a la API.

Usa una biblioteca cliente

Descarga e instala la biblioteca cliente que elijas.

Usar el cliente HTTP (REST)

curl

Descarga e instala curl, la herramienta de línea de comandos para transferir datos a través de una URL.

Google Cloud CLI

Sigue las instrucciones para instalar gcloud CLI.

Se verificó que las instrucciones del resto de esta guía funcionan con la siguiente versión de la herramienta de gcloud y es posible que no funcionen con versiones anteriores debido a diferencias en el comportamiento de la aplicación o en las opciones de la línea de comandos.

:~$ gcloud version
Google Cloud SDK 492.0.0
alpha 2024.09.06
beta 2024.09.06
bq 2.1.8
bundled-python3-unix 3.11.9
core 2024.09.06
enterprise-certificate-proxy 0.3.2
gcloud-crc32c 1.0.0
gsutil 5.30

Realiza una llamada a la API

Selecciona el cliente que prefieras para obtener instrucciones sobre cómo realizar una llamada a la API:

Java

Los artefactos de la biblioteca cliente se publican en el repositorio central de Maven. Agrega la biblioteca cliente como una dependencia a tu proyecto de la siguiente manera:

La dependencia de Maven es la siguiente:

<dependency>
  <groupId>com.google.api-ads</groupId>
  <artifactId>google-ads</artifactId>
  <version>40.0.0</version>
</dependency>

La dependencia de Gradle es la siguiente:

implementation 'com.google.api-ads:google-ads:40.0.0'

api.googleads.serviceAccountSecretsPath=JSON_KEY_FILE_PATH
api.googleads.developerToken=INSERT_DEVELOPER_TOKEN_HERE
api.googleads.loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE

Crea un objeto GoogleAdsClient de la siguiente manera:

GoogleAdsClient googleAdsClient = null;
try {
  googleAdsClient = GoogleAdsClient.newBuilder().fromPropertiesFile().build();
} catch (FileNotFoundException fnfe) {
  System.err.printf(
      "Failed to load GoogleAdsClient configuration from file. Exception: %s%n",
      fnfe);
  System.exit(1);
} catch (IOException ioe) {
  System.err.printf("Failed to create GoogleAdsClient. Exception: %s%n", ioe);
  System.exit(1);
}

A continuación, ejecuta un informe de la campaña con el método GoogleAdsService.SearchStream para recuperar las campañas de tu cuenta. En esta guía, no se abordan los detalles de la generación de informes.

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#

Los paquetes de la biblioteca cliente se publican en el repositorio de Nuget.org. Comienza por agregar una referencia de NuGet al paquete Google.Ads.GoogleAds.

dotnet add package Google.Ads.GoogleAds --version 18.1.0

Crea un objeto GoogleAdsConfig con la configuración pertinente y úsalo para crear un objeto GoogleAdsClient.

GoogleAdsConfig config = new GoogleAdsConfig()
{
    DeveloperToken = "******",
    OAuth2Mode = OAuth2Flow.SERVICE_ACCOUNT,
    OAuth2SecretsJsonPath = "PATH_TO_CREDENTIALS_JSON",
    LoginCustomerId = ******
};
GoogleAdsClient client = new GoogleAdsClient(config);

A continuación, ejecuta un informe de la campaña con el método GoogleAdsService.SearchStream para recuperar las campañas de tu cuenta. En esta guía, no se abordan los detalles de la generación de informes.

public void Run(GoogleAdsClient client, long customerId)
{
    // Get the GoogleAdsService.
    GoogleAdsServiceClient googleAdsService = client.GetService(
        Services.V21.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

Los paquetes de la biblioteca cliente se publican en el repositorio de Packagist. Cambia al directorio raíz de tu proyecto y ejecuta el siguiente comando para instalar la biblioteca y todas sus dependencias en el directorio vendor/ del directorio raíz de tu proyecto.

composer require googleads/google-ads-php:31.0.0

Haz una copia del archivo google_ads_php.ini del repositorio de GitHub y modifícalo para incluir tus credenciales.

[GOOGLE_ADS]
developerToken = "INSERT_DEVELOPER_TOKEN_HERE"
loginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"

[OAUTH2]
jsonKeyFilePath = "INSERT_ABSOLUTE_PATH_TO_OAUTH2_JSON_KEY_FILE_HERE"
scopes = "https://www.googleapis.com/auth/adwords"

Crea una instancia del objeto GoogleAdsClient.

$oAuth2Credential = (new OAuth2TokenBuilder())
    ->fromFile('/path/to/google_ads_php.ini')
    ->build();

$googleAdsClient = (new GoogleAdsClientBuilder())
    ->fromFile('/path/to/google_ads_php.ini')
    ->withOAuth2Credential($oAuth2Credential)
    ->build();

A continuación, ejecuta un informe de la campaña con el método GoogleAdsService.SearchStream para recuperar las campañas de tu cuenta. En esta guía, no se abordan los detalles de la generación de informes.

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

La biblioteca cliente se distribuye en PyPI y se puede instalar con el comando pip de la siguiente manera:

python -m pip install google-ads==21.3.0

Haz una copia del archivo google-ads.yaml del repositorio de GitHub y modifícalo para incluir tus credenciales.

developer_token: INSERT_DEVELOPER_TOKEN_HERE
login_customer_id: INSERT_LOGIN_CUSTOMER_ID_HERE
json_key_file_path: JSON_KEY_FILE_PATH_HERE

Crea una instancia de GoogleAdsClient llamando al método GoogleAdsClient.load_from_storage. Pasa la ruta de acceso a tu google-ads.yaml como una cadena al método cuando lo llames:

from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_storage("path/to/google-ads.yaml")

Agrega un controlador al registrador de la biblioteca que le indique dónde imprimir los registros. El siguiente código le indicará al registrador de la biblioteca que imprima en la consola (stdout).

import logging
import sys

logger = logging.getLogger('google.ads.googleads.client')
logger.addHandler(logging.StreamHandler(sys.stdout))

A continuación, ejecuta un informe de la campaña con el método GoogleAdsService.SearchStream para recuperar las campañas de tu cuenta. En esta guía, no se abordan los detalles de la generación de informes.

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

Las gems de Ruby para la biblioteca cliente se publican en el sitio de hosting de gems de Rubygems. La forma recomendada de instalarlo es con Bundler. Agrega una línea a tu Gemfile:

gem 'google-ads-googleads', '~> 35.2.0'

Luego, ejecute lo siguiente:

bundle install

Haz una copia del archivo google_ads_config.rb del repositorio de GitHub y modifícalo para incluir tus credenciales.

Google::Ads::GoogleAds::Config.new do |c|
  c.developer_token = 'INSERT_DEVELOPER_TOKEN_HERE'
  c.login_customer_id = 'INSERT_LOGIN_CUSTOMER_ID_HERE'
  c.keyfile = 'JSON_KEY_FILE_PATH'
end

Crea una instancia de GoogleAdsClient pasando la ruta de acceso a la ubicación en la que guardas este archivo.

client = Google::Ads::GoogleAds::GoogleAdsClient.new('path/to/google_ads_config.rb')

A continuación, ejecuta un informe de la campaña con el método GoogleAdsService.SearchStream para recuperar las campañas de tu cuenta. En esta guía, no se abordan los detalles de la generación de informes.

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

La biblioteca se distribuye en CPAN. Para comenzar, clona el repositorio google-ads-perl en el directorio que elijas.

git clone https://github.com/googleads/google-ads-perl.git

Cambia al directorio google-ads-perl y ejecuta el siguiente comando en el símbolo del sistema para instalar todas las dependencias necesarias para usar la biblioteca.

cd google-ads-perl
cpan install Module::Build
perl Build.PL
perl Build installdeps

Haz una copia del archivo googleads.properties del repositorio de GitHub y modifícalo para incluir tus credenciales.

jsonKeyFilePath=JSON_KEY_FILE_PATH
developerToken=INSERT_DEVELOPER_TOKEN_HERE
loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE

Crea una instancia de Client pasando la ruta de acceso a la ubicación en la que guardas este archivo.

my $properties_file = "/path/to/googleads.properties";

my $api_client = Google::Ads::GoogleAds::Client->new({
  properties_file => $properties_file
});

A continuación, ejecuta un informe de la campaña con el método GoogleAdsService.SearchStream para recuperar las campañas de tu cuenta. En esta guía, no se abordan los detalles de la generación de informes.

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::V21::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

Comienza por configurar la cuenta de servicio como las credenciales activas en la CLI de gcloud.

gcloud auth login --cred-file=PATH_TO_CREDENTIALS_JSON

A continuación, recupera un token de acceso de OAuth 2.0 para la API de Google Ads.

gcloud auth \
  print-access-token \
  --scopes='https://www.googleapis.com/auth/adwords'

A continuación, ejecuta un informe de la campaña con el método GoogleAdsService.SearchStream para recuperar las campañas de tu cuenta. En esta guía, no se abordan los detalles de la generación de informes.

curl -i -X POST https://googleads.googleapis.com/v21/customers/CUSTOMER_ID/googleAds:searchStream \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer ACCESS_TOKEN" \
   -H "developer-token: DEVELOPER_TOKEN" \
   -H "login-customer-id: LOGIN_CUSTOMER_ID" \
   --data-binary "@query.json"

El contenido de query.json es el siguiente:

{
  "query": "SELECT campaign.id, campaign.name, campaign.network_settings.target_content_network FROM campaign ORDER BY campaign.id"
}
Anterior
Introducción
Siguiente
Errores comunes