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:
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
- En la consola de Google Cloud, ve a Menú > IAM y administración > Cuentas de servicio.
- Selecciona tu cuenta de servicio.
- Haz clic en Claves > Agregar clave > Crear clave nueva.
- 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.jsonen tu directorio de trabajo. Este archivo es la única copia de esta clave. No confirmescredentials.jsonen el control de versiones (por ejemplo, agrégalo a tu archivo.gitignore). - Haz clic en Cerrar.
Configura tu cuenta de cliente de Google Ads
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.
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.
- 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.
- 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
- Para comenzar, accede a tu cuenta de Google Ads como administrador.
- Navega a Administrador > Acceso y seguridad.
- Haz clic en el botón
en la pestaña Usuarios.
- 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.
- Se otorga acceso a la cuenta de servicio.
- [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.
- Haz clic en la flecha desplegable junto al nivel de acceso de la cuenta de servicio en la columna Nivel de acceso.
- 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.30Realiza 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.0Para 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.0Haz 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.0Para autenticar tus llamadas a la API, configura un archivo google-ads.yaml:
- Descarga una copia del archivo de muestra
google-ads.yamldesde el repositorio de GitHub. - Guarda el archivo en tu directorio principal (
~/google-ads.yaml) o en una ruta de acceso personalizada. Abre
google-ads.yamly actualízalo para incluir tus credenciales:login_customer_id: INSERT_LOGIN_CUSTOMER_ID_HERE json_key_file_path: JSON_KEY_FILE_PATHConfigura 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
INFOen 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:
Agrega la gem al
Gemfilede tu aplicación:gem 'google-ads-googleads', '~> 45.1.0'Para instalar la gema, ejecuta el siguiente comando:
bundle install
Para configurar tus credenciales, haz lo siguiente:
- Copia el archivo de muestra
google_ads_config.rbdel repositorio de GitHub. - Guarda el archivo en el directorio raíz de tu proyecto o en tu directorio principal (
~). Abre
google_ads_config.rby 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' endCrea una instancia de
GoogleAdsClientpasando 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.
Clona el repositorio
google-ads-perlen el directorio que elijas:git clone https://github.com/googleads/google-ads-perl.gitCambia al directorio
google-ads-perly 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:
Copia el archivo de configuración de muestra
googleads.propertiesdel repositorio de GitHub en tu directorio principal (~/googleads.properties):cp googleads.properties ~/googleads.propertiesEdita
~/googleads.propertiespara incluir tus credenciales:jsonKeyFilePath=JSON_KEY_FILE_PATH loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERECrea una instancia de
Clientpasando la ruta de acceso a tu archivogoogleads.propertiesconfigurado (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_PATHA 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.