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

  • 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 uno desde la consola de Google Cloud.
  • Nivel de acceso a la API: El nivel de acceso a la API de tu proyecto de Google Cloud 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. El nivel de acceso a la API de tu proyecto se indica en la página de descripción general de la API de Google Ads del proyecto.
  • Cuenta de administrador de Google Ads: Se utiliza para administrar otras cuentas de Google Ads, que pueden ser una colección de cuentas de cliente de Google Ads o de otras cuentas de administrador de Google Ads.
  • Cuenta de cliente de Google Ads: Es la cuenta de Google Ads que se usa para publicar los anuncios a los que deseas segmentar tus 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. Si copiaste este ID de la IU de Google Ads, asegúrate de quitar los guiones.
  • 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.
  • 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 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.

Configura tu proyecto de Cloud para acceder a la API de Google Ads

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

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

Habilita la API de Google Ads

A continuación, visita la página de descripción general de la API de Google Ads. En la página, se muestra tu nivel de acceso a la API actual. Si tu nivel de acceso a la API actual es Prueba, expande la sección Actualizar el nivel de acceso. Sigue las instrucciones para solicitar el nivel de acceso de Explorador.

Una vez que completes la solicitud, Google la revisará automáticamente y la actualizará a Explorer en la mayoría de los casos. Si no se te otorgó acceso de Explorador, no te preocupes. Esta guía te proporcionará las instrucciones adecuadas para configurar tu cuenta de cliente de Google Ads.

Crea una cuenta de servicio

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 volver a usar las credenciales existentes.

Cómo crear una cuenta de servicio y una clave

  1. En la consola de Google Cloud, ve a Menú > 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. No confirmes credentials.json en el control de versiones (por ejemplo, agrégalo a tu archivo .gitignore).

  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 proyecto de Google Cloud. Consulta tu página de descripción general de la API de Google Ads para conocer tu nivel de acceso a la API.

Niveles de acceso Explorador, Básico y Estándar

Puedes realizar 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 de prueba si es necesario.

Prueba el acceso

Tu proyecto de Google Cloud 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

En las siguientes instrucciones, se crean una cuenta de administrador de prueba de Google Ads y una cuenta de anunciante de prueba de Google Ads subordinada a 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.

    Crea una cuenta de administrador de prueba de Google Ads

  2. Mientras estás en tu cuenta de administrador de prueba 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 correspondientes 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.
    Página Acceso y seguridad de Google Ads que muestra el botón para agregar 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 de correo electrónico no se admite para las cuentas de servicio.
    Cuadro de diálogo para agregar un correo electrónico de la cuenta de servicio y seleccionar un nivel de acceso
  5. Se otorga acceso a la cuenta de servicio.
    Página de acceso y seguridad que muestra la cuenta de servicio con acceso
  6. [Opcional] No puedes otorgar acceso de administrador a una cuenta de servicio durante la configuración inicial. 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 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 quieras realizar las llamadas a la API.

Usa una biblioteca cliente

Descarga e instala la biblioteca cliente que elijas.

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

La interfaz de línea de comandos de Google Cloud

Sigue la guía de instalación de Google Cloud CLI para instalar la CLI de gcloud.

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 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 de Maven Central.

Para administrar las versiones de las dependencias y evitar conflictos, consulta la guía de la lista de materiales (BOM) de la API de Google Ads.

Si no usas la BoM, agrega la biblioteca cliente directamente a tu proyecto con una de las siguientes herramientas de compilación:

Maven: Agrega la siguiente dependencia a tu archivo pom.xml:

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

Gradle: Agrega la siguiente dependencia a tu archivo build.gradle:

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

Crea un archivo ads.properties en tu directorio principal (~/ads.properties en Linux y macOS, o %USERPROFILE%\ads.properties en Windows) con el siguiente contenido:

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

Antes de ejecutar solicitudes a la API, crea una instancia de GoogleAdsClient. De forma predeterminada, fromPropertiesFile() carga las credenciales del archivo ads.properties ubicado en tu directorio principal:

GoogleAdsClient googleAdsClient;
try {
  googleAdsClient = GoogleAdsClient.newBuilder().fromPropertiesFile().build();
} catch (IOException e) {
  System.err.printf("Failed to create GoogleAdsClient: %s%n", e);
  throw new RuntimeException("Initialization failed", e);
}

A continuación, ejecuta un informe de la campaña con GoogleAdsService.SearchStream para transmitir grandes conjuntos de resultados de manera eficiente y recuperar las campañas de tu cuenta:

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

C#

Los paquetes de la biblioteca cliente se publican en el repositorio de NuGet.org. Para comenzar, agrega una referencia de paquete NuGet al paquete Google.Ads.GoogleAds:

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

Para realizar llamadas a la API, crea un objeto GoogleAdsConfig a partir de tus parámetros de configuración (como appsettings.json, variables de entorno o parámetros de configuración personalizados) y pásalo para inicializar una instancia de GoogleAdsClient:

GoogleAdsConfig config = new GoogleAdsConfig()
{
    OAuth2Mode = OAuth2Flow.SERVICE_ACCOUNT,
    OAuth2SecretsJsonPath = "JSON_KEY_FILE_PATH",
    LoginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"
};
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 explican los detalles de la generación de informes.

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

PHP

Los paquetes de la biblioteca cliente se publican en el repositorio de Packagist. Asegúrate de tener instalada una versión de PHP y Composer compatibles. Luego, cambia al directorio raíz de tu proyecto y ejecuta el siguiente comando para instalar la biblioteca y sus dependencias en el directorio vendor/ de tu proyecto:

composer require googleads/google-ads-php:35.1.0

Haz una copia del archivo google_ads_php.ini del repositorio de GitHub, guárdala en el directorio principal o en el directorio raíz de tu proyecto y modifícala para incluir tus credenciales:

[GOOGLE_ADS]
loginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"

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

Crea una instancia de GoogleAdsClient con tu archivo de configuración google_ads_php.ini:

use Google\Ads\GoogleAds\Lib\OAuth2TokenBuilder;
use Google\Ads\GoogleAds\Lib\V25\GoogleAdsClientBuilder;

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

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

Python

La biblioteca cliente de la API de Google Ads para Python se distribuye en PyPI. Asegúrate de tener instalada una versión compatible de Python y, luego, instala la biblioteca con pip:

python -m pip install google-ads==33.0.0

Para autenticar tus llamadas a la API, configura un archivo google-ads.yaml:

  1. Descarga una copia del archivo de muestra google-ads.yaml desde el repositorio de GitHub.
  2. Guarda el archivo en tu directorio principal (~/google-ads.yaml) o en una ruta de acceso personalizada.
  3. Abre google-ads.yaml y actualízalo para incluir tus credenciales:

    login_customer_id: INSERT_LOGIN_CUSTOMER_ID_HERE
    json_key_file_path: JSON_KEY_FILE_PATH
    

    Configura el registro antes de inicializar el cliente para que la biblioteca capture cualquier advertencia de inicialización o configuración. En el siguiente ejemplo, se configura el registrador de la biblioteca para que genere registros de INFO en la salida estándar (stdout):

import logging
import sys

logger = logging.getLogger("google.ads.googleads.client")
logger.setLevel(logging.INFO)
logger.addHandler(logging.StreamHandler(sys.stdout))

Crea una instancia de GoogleAdsClient llamando al método GoogleAdsClient.load_from_storage y pasando la ruta de acceso a tu archivo google-ads.yaml:

from google.ads.googleads.client import GoogleAdsClient

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

Si omites el argumento de ruta de acceso, load_from_storage() buscará el archivo de configuración en tu directorio principal (~/google-ads.yaml) de forma predeterminada.

A continuación, ejecuta un informe de la campaña con el método GoogleAdsService.SearchStream para recuperar las campañas de tu cuenta:

    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.'
            )

Ruby

Las gemas de Ruby para la biblioteca cliente se publican en RubyGems. Asegúrate de tener instalada una versión compatible de Ruby y usa Bundler para instalar la biblioteca:

  1. Agrega la gem al Gemfile de tu aplicación:

    gem 'google-ads-googleads', '~> 45.1.0'
    
  2. Para instalar la gema, ejecuta el siguiente comando:

    bundle install

Para configurar tus credenciales, haz lo siguiente:

  1. Copia el archivo de muestra google_ads_config.rb del repositorio de GitHub.
  2. Guarda el archivo en el directorio raíz de tu proyecto o en tu directorio principal (~).
  3. Abre google_ads_config.rb y reemplaza los valores de marcador de posición por tus credenciales de la API de Google Ads:

    Google::Ads::GoogleAds::Config.new do |c|
      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 tu archivo de configuración (google_ads_config.rb):

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:

    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

Perl

La biblioteca cliente de Perl se distribuye en CPAN y requiere Perl 5.28 o una versión posterior, y el administrador de paquetes cpan o cpanm.

  1. Clona el repositorio google-ads-perl en el directorio que elijas:

    git clone https://github.com/googleads/google-ads-perl.git
  2. Cambia al directorio google-ads-perl y ejecuta los siguientes comandos para instalar las dependencias requeridas y compilar la biblioteca:

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

Para configurar tus credenciales, haz lo siguiente:

  1. Copia el archivo de configuración de muestra googleads.properties del repositorio de GitHub en tu directorio principal (~/googleads.properties):

    cp googleads.properties ~/googleads.properties
  2. Edita ~/googleads.properties para incluir tus credenciales:

    jsonKeyFilePath=JSON_KEY_FILE_PATH
    loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE
    

    Crea una instancia de Client pasando la ruta de acceso a tu archivo googleads.properties configurado (como ~/googleads.properties):

my $api_client = Google::Ads::GoogleAds::Client->new({
  properties_file => "/path/to/googleads.properties"
});

A continuación, ejecuta un informe de la campaña con el método GoogleAdsService.SearchStream para recuperar las campañas de tu cuenta:

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

Cuando se ejecuta, la secuencia de comandos transmite las filas coincidentes y, luego, imprime el ID y el nombre de cada campaña de tu cuenta.

curl

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

gcloud auth login --cred-file=JSON_KEY_FILE_PATH

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'

Crea un archivo llamado query.json que contenga tu solicitud del lenguaje de consulta de Google Ads (GAQL):

{
  "query": "SELECT campaign.id, campaign.name, campaign.network_settings.target_content_network FROM campaign ORDER BY campaign.id"
}

Ejecuta un informe de la campaña con el método GoogleAdsService.SearchStream para recuperar las campañas de tu cuenta:

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

Si encuentras errores cuando realices tu primera llamada, consulta Cómo controlar errores de la API para obtener orientación sobre la solución de problemas.