Este guia de início rápido ajuda você a fazer sua primeira chamada de API para a API Google Ads.
Principais conceitos
- Projeto do Google Cloud:um projeto do Google Cloud forma a base para criar, ativar e usar todos os serviços do Google, incluindo o gerenciamento de APIs e credenciais da API OAuth 2.0. É possível criar um no console do Google Cloud.
- Nível de acesso à API:o nível de acesso à API do seu projeto na nuvem do Google Cloud controla o número de chamadas de API que você pode fazer por dia e os ambientes em que é possível fazer essas chamadas. O nível de acesso à API do seu projeto está listado na página de visão geral da API Google Ads.
- Conta de administrador do Google Ads:usada para gerenciar outras contas do Google Ads, que podem ser um conjunto de contas de cliente do Google Ads ou outras contas de administrador do Google Ads.
- Conta de cliente do Google Ads:a conta do Google Ads usada para veicular anúncios que você quer segmentar com chamadas de API.
- ID de cliente do cliente:o número de 10 dígitos que identifica uma conta de cliente do Google Ads. Se você copiou esse ID da interface do Google Ads, remova os hífens.
- OAuth 2.0:o OAuth 2.0 é um protocolo padrão do setor para autorização, usado por todas as APIs do Google. Você precisa de uma conta de serviço e uma chave para gerar credenciais do OAuth 2.0 e fazer chamadas de API.
- Conta de serviço:um tipo especial de Conta do Google que pertence ao seu aplicativo, e não a um usuário individual. Ele é usado para autenticar seu aplicativo na API Google Ads. Você precisa de um projeto na nuvem do Google Cloud para conseguir uma conta de serviço.
- Chave da conta de serviço:um arquivo JSON de credenciais do app que contém a chave privada da sua conta de serviço. Ele é usado para gerar credenciais do OAuth 2.0 e autenticar uma conta de serviço ao fazer uma chamada de API Google Ads. Você precisa de uma conta de serviço para receber uma chave de conta de serviço.
Pré-requisitos
Para fazer uma chamada da API Google Ads, siga estas etapas.
Configurar seu projeto na nuvem para acesso à API Google Ads
O projeto do Google Cloud é usado para gerenciar APIs do Google e credenciais da API OAuth 2.0. Para encontrar seus projetos do Google Cloud ou criar um, acesse o console do Google Cloud.
Comece ativando a API Google Ads no seu projeto:
Em seguida, acesse a página de visão geral da API Google Ads. A página mostra seu nível de acesso atual à API. Se o nível de acesso à API atual for Teste, expanda a seção Fazer upgrade do nível de acesso. Siga as instruções para solicitar o nível de acesso Explorer.
Depois que você concluir a inscrição, o Google vai analisar e fazer upgrade automático para o Explorer na maioria dos casos. Se você não tiver acesso ao Explorer, não se preocupe. Este guia vai fornecer as instruções adequadas ao configurar sua conta de cliente do Google Ads.
Criar uma conta de serviço
Você precisa de uma conta de serviço e uma chave de conta de serviço para fazer chamadas de API. Se você já estiver usando outra API do Google e tiver criado uma conta de serviço e uma chave do OAuth 2.0, pule esta etapa e reutilize as credenciais atuais.
Como criar uma conta de serviço e uma chave
- No console do Google Cloud, acesse Menu > IAM e administrador > Contas de serviço.
- Selecione a conta de serviço.
- Clique em Chaves > Adicionar chave > Criar nova chave.
- Selecione JSON e clique em Criar.
Seu novo par de chaves pública/privada é gerado e transferido por download para sua máquina como um novo arquivo. Salve o arquivo JSON baixado como
credentials.jsonno seu diretório de trabalho. Este arquivo é a única cópia dessa chave. Não faça commit decredentials.jsonno controle de versões. Por exemplo, adicione ao arquivo.gitignore. - Clique em Fechar.
Configurar sua conta de cliente do Google Ads
Comece identificando a conta do Google Ads que você está usando para fazer chamadas de API. O tipo de conta para que você pode fazer chamadas de API depende do nível de acesso à API do seu projeto na nuvem do Google Cloud. Confira sua página de visão geral da API Google Ads para saber seu nível de acesso à API.
Níveis de acesso Explorer, Basic e Standard
Você pode fazer chamadas para sua conta de produção do Google Ads. No entanto, você pode criar uma conta de teste do Google Ads seguindo as instruções na guia Acesso de teste, se necessário.
Testar o acesso
Seu projeto do Google Cloud não pode ser usado para fazer chamadas de API em uma conta de produção do Google Ads. Só é possível fazer chamadas de API em contas de teste do Google Ads.
Como criar uma conta de teste do Google Ads
As instruções a seguir criam uma conta de administrador de teste do Google Ads e uma conta de anunciante de teste do Google Ads abaixo dela.
Clique no botão azul para criar uma conta de administrador de teste do Google Ads. Se necessário, faça login com uma Conta do Google que não esteja vinculada à sua conta de gerente de produção do Google Ads. Se você não tiver uma, use o botão Criar conta nessa página para criar uma Conta do Google.
- Na sua conta de administrador de teste do Google Ads, crie uma conta de cliente de teste do Google Ads: clique em Contas > > Criar nova conta e preencha o formulário. Todas as contas do Google Ads criadas na sua conta de administrador de teste do Google Ads são automaticamente contas de teste do Google Ads.
- Se quiser, crie algumas campanhas na conta de cliente de teste do Google Ads na página do Google Ads.
Para fazer uma chamada de API a um cliente do Google Ads, conceda acesso e as permissões adequadas à sua conta de serviço na conta de cliente do Google Ads. Para fazer isso, você precisa ter acesso de administrador à conta do cliente.
Como conceder acesso da conta de serviço à sua conta do Google Ads
- Primeiro, faça login na sua conta do Google Ads como administrador.
- Acesse Administrador > Acesso e segurança.
- Clique no botão
na guia Usuários.
- Digite o endereço de e-mail da conta de serviço na caixa de entrada E-mail.
Selecione o nível de acesso à conta adequado e clique no botão
Adicionar conta. O nível de acesso "E-mail" não é compatível com contas de serviço.
- A conta de serviço recebe acesso.
- [Opcional] Não é possível conceder acesso de administrador a uma conta de serviço durante a configuração inicial. Se as chamadas de API exigirem acesso de administrador, faça upgrade do acesso da seguinte maneira.
- Clique na seta do menu suspenso ao lado do nível de acesso da conta de serviço na coluna Nível de acesso.
- Selecione Administrador na lista suspensa.
Baixar ferramentas e bibliotecas de cliente
Você pode baixar uma biblioteca de cliente ou um cliente HTTP, dependendo de como quer fazer as chamadas de API.
Usar uma biblioteca de cliente
Faça o download e instale uma biblioteca de cliente de sua escolha.
Usar o cliente HTTP (REST)
curl
Faça o download e instale o curl, a ferramenta de linha de comando para transferir dados por um URL.
A interface de linha de comando do Google Cloud
Siga o guia de instalação da CLI do Google Cloud para instalar a CLI gcloud.
As instruções do restante deste guia foram verificadas para funcionar com a seguinte versão da ferramenta gcloud e podem não funcionar com versões anteriores devido a diferenças no comportamento do aplicativo ou nas opções de linha de comando.
:~$ 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.30Fazer uma chamada de API
Selecione o cliente de sua preferência para instruções sobre como fazer uma chamada de API:
Java
Os artefatos da biblioteca de cliente são publicados no repositório Maven Central.
Para gerenciar versões de dependência e evitar conflitos, consulte o guia da lista de materiais (BOM) da API Google Ads.
Se você não estiver usando a BOM, adicione a biblioteca de cliente diretamente ao seu projeto usando uma das seguintes ferramentas de build:
Maven: adicione a seguinte dependência ao arquivo pom.xml:
<dependency>
<groupId>com.google.api-ads</groupId>
<artifactId>google-ads</artifactId>
<version>46.1.0</version>
</dependency>
Gradle: adicione a seguinte dependência ao arquivo build.gradle:
implementation 'com.google.api-ads:google-ads:46.1.0'
Crie um arquivo ads.properties no seu diretório principal (~/ads.properties
no Linux e no macOS ou %USERPROFILE%\ads.properties no Windows) com o
seguinte conteúdo:
api.googleads.serviceAccountSecretsPath=JSON_KEY_FILE_PATH
api.googleads.loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE
Antes de executar solicitações de API, crie uma instância GoogleAdsClient. Por
padrão, fromPropertiesFile() carrega credenciais do arquivo ads.properties
localizado no diretório 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);
}
Em seguida, execute um relatório de campanha usando GoogleAdsService.SearchStream para transmitir grandes conjuntos de resultados de maneira eficiente e recuperar as campanhas na sua conta:
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#
Os pacotes da biblioteca de cliente são publicados no
repositório NuGet.org.
Comece adicionando uma referência de pacote NuGet ao pacote Google.Ads.GoogleAds:
dotnet add package Google.Ads.GoogleAds --version 27.4.0Para fazer chamadas de API, crie um objeto GoogleAdsConfig com base nas configurações de configuração (como appsettings.json, variáveis de ambiente ou configurações personalizadas) e transmita-o para inicializar uma instância 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);
Em seguida, execute um relatório de campanha usando o método
GoogleAdsService.SearchStream
para recuperar as campanhas na sua conta. Este guia não aborda os detalhes dos relatórios.
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
Os pacotes da biblioteca de cliente são publicados no
repositório Packagist.
Verifique se você tem uma versão compatível do PHP e o Composer instalado. Em seguida, mude
para o diretório raiz do projeto e execute o comando a seguir para
instalar a biblioteca e as dependências dela no diretório vendor/
do projeto:
composer require googleads/google-ads-php:35.1.0Faça uma cópia do arquivo
google_ads_php.ini
do repositório do GitHub, salve-o no diretório inicial ou na raiz do
projeto e modifique-o para incluir suas credenciais:
[GOOGLE_ADS]
loginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"
[OAUTH2]
jsonKeyFilePath = "JSON_KEY_FILE_PATH"
scopes = "https://www.googleapis.com/auth/adwords"
Crie uma instância GoogleAdsClient usando o arquivo de configuração 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();
Em seguida, gere um relatório de campanha usando o método
GoogleAdsService.SearchStream
para recuperar as campanhas na sua conta:
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
A biblioteca de cliente da API Google Ads para Python é distribuída no PyPI. Verifique se você tem uma versão compatível do Python instalada e instale a biblioteca usando
pip:
python -m pip install google-ads==33.0.0Para autenticar suas chamadas de API, configure um arquivo google-ads.yaml:
- Baixe uma cópia do arquivo de amostra
google-ads.yamlno repositório do GitHub. - Salve o arquivo no diretório principal (
~/google-ads.yaml) ou em um caminho personalizado. Abra
google-ads.yamle atualize para incluir suas credenciais:login_customer_id: INSERT_LOGIN_CUSTOMER_ID_HERE json_key_file_path: JSON_KEY_FILE_PATHConfigure o registro em log antes de inicializar o cliente para que a biblioteca capture todos os avisos de inicialização ou configuração. O exemplo a seguir configura o logger da biblioteca para gerar registros
INFOna saída padrão (stdout):
import logging
import sys
logger = logging.getLogger("google.ads.googleads.client")
logger.setLevel(logging.INFO)
logger.addHandler(logging.StreamHandler(sys.stdout))
Crie uma instância GoogleAdsClient chamando o método
GoogleAdsClient.load_from_storage e transmitindo o caminho para o arquivo
google-ads.yaml:
from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_storage("path/to/google-ads.yaml")
Se você omitir o argumento de caminho, load_from_storage() vai procurar o
arquivo de configuração no seu diretório inicial (~/google-ads.yaml) por padrão.
Em seguida, gere um relatório de campanha usando o método
GoogleAdsService.SearchStream
para recuperar as campanhas na sua conta:
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
As gems do Ruby para a biblioteca de cliente são publicadas no RubyGems. Verifique se você tem uma versão compatível do Ruby instalada e use o Bundler para instalar a biblioteca:
Adicione a gem ao
Gemfiledo aplicativo:gem 'google-ads-googleads', '~> 45.1.0'Instale a gem executando:
bundle install
Para configurar suas credenciais:
- Copie o arquivo de amostra
google_ads_config.rbdo repositório do GitHub. - Salve o arquivo no diretório raiz do projeto ou no diretório principal
(
~). Abra
google_ads_config.rbe substitua os valores dos marcadores de posição pelas suas credenciais da API Google Ads:Google::Ads::GoogleAds::Config.new do |c| c.login_customer_id = 'INSERT_LOGIN_CUSTOMER_ID_HERE' c.keyfile = 'JSON_KEY_FILE_PATH' endCrie uma instância
GoogleAdsClienttransmitindo o caminho para seu arquivo de configuração (google_ads_config.rb):
client = Google::Ads::GoogleAds::GoogleAdsClient.new(
'path/to/google_ads_config.rb'
)
Em seguida, gere um relatório de campanha usando o método
GoogleAdsService.SearchStream
para recuperar as campanhas na sua conta:
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
A biblioteca de cliente Perl é distribuída no CPAN e requer Perl 5.28 ou mais recente e o gerenciador de pacotes cpan ou cpanm.
Clone o repositório
google-ads-perlno diretório que preferir:git clone https://github.com/googleads/google-ads-perl.gitMude para o diretório
google-ads-perle execute os seguintes comandos para instalar as dependências necessárias e criar a biblioteca:cd google-ads-perl cpan install Module::Build perl Build.PL perl Build installdeps perl Build perl Build install
Para configurar suas credenciais:
Copie o arquivo de configuração de exemplo
googleads.propertiesdo repositório do GitHub para seu diretório inicial (~/googleads.properties):cp googleads.properties ~/googleads.propertiesEdite
~/googleads.propertiespara incluir suas credenciais:jsonKeyFilePath=JSON_KEY_FILE_PATH loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERECrie uma instância
Clienttransmitindo o caminho para o arquivogoogleads.propertiesconfigurado (como~/googleads.properties):
my $api_client = Google::Ads::GoogleAds::Client->new({
properties_file => "/path/to/googleads.properties"
});
Em seguida, gere um relatório de campanha usando o método
GoogleAdsService.SearchStream
para recuperar as campanhas na sua conta:
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;
}
Quando executado, o script transmite as linhas correspondentes e imprime o ID e o nome de cada campanha na sua conta.
curl
Comece definindo a conta de serviço como as credenciais ativas na CLI da gcloud.
gcloud auth login --cred-file=JSON_KEY_FILE_PATHEm seguida, busque um token de acesso do OAuth 2.0 para a API Google Ads.
gcloud auth \
print-access-token \
--scopes='https://www.googleapis.com/auth/adwords'Crie um arquivo chamado query.json com sua solicitação da linguagem de consulta do Google Ads
(GAQL):
{
"query": "SELECT campaign.id, campaign.name, campaign.network_settings.target_content_network FROM campaign ORDER BY campaign.id"
}
Execute um relatório de campanha usando o método
GoogleAdsService.SearchStream
para recuperar as campanhas na sua conta:
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"Se você encontrar erros ao fazer sua primeira chamada, consulte Como lidar com erros da API para orientações sobre solução de problemas.