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 de 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 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 chamadas de API. O nível de acesso à API do seu projeto está listado na página de visão geral da API Google Ads do projeto.
- Conta de administrador do Google Ads: Uma conta de administrador do Google Ads é usada para gerenciar outras contas do Google Ads, que podem ser uma coleção 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: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 hifens.
- 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 para 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. Ela é usada para autenticar seu aplicativo na API Google Ads. Você precisa de um projeto na nuvem do Google Cloud para receber uma conta de serviço.
- Chave da conta de serviço:um arquivo de credencial de app JSON que contém a chave privada da sua conta de serviço. Ela é usada para gerar credenciais do OAuth 2.0 para autenticar uma conta de serviço ao fazer uma chamada de API da 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 de 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 de API OAuth 2.0. Você pode encontrar seus projetos do Google Cloud ou criar um acessando 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 à API atual. 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 fazer uma análise automática da sua inscrição e fazer upgrade para o Explorer na maioria dos casos. Se você não recebeu 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 chave pública/privada é gerado e transferido por download para sua máquina como um novo arquivo. Salve o arquivo JSON transferido por download como
credentials.jsonno seu diretório de trabalho. Esse é a única cópia da chave. Não confirmecredentials.jsonno controle de versão. Por exemplo, adicione-o ao arquivo.gitignore. - Clique em Fechar.
Configurar sua conta de cliente do Google Ads
Comece identificando a conta do Google Ads em que você está fazendo chamadas de API. O tipo de conta em que você pode fazer chamadas de API depende do nível de acesso à API do seu projeto do Google Cloud. Consulte a página de visão geral da API Google Ads para descobrir seu nível de acesso à API.
Níveis de acesso Explorer, Básico e Padrão
Você pode fazer chamadas para sua conta de produção do Google Ads. No entanto, é possível criar uma conta de teste do Google Ads seguindo as instruções na guia Testar acesso , se necessário.
Testar o acesso
Seu projeto do Google Cloud não pode ser usado para fazer chamadas de API para uma conta de produção do Google Ads. Você só pode 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 a conta de anunciante de teste do Google Ads.
Clique no botão azul para criar uma conta de administrador de teste do Google Ads. Se solicitado, faça login com uma Conta do Google que não esteja vinculada à sua conta de administrador de produção do Google Ads. Se você não tiver uma, use o Criar conta botão nessa página para criar uma nova 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.
- Opcionalmente, crie algumas campanhas na conta de cliente de teste do Google Ads na página do Google Ads.
Para fazer uma chamada de API para um cliente do Google Ads, conceda acesso e permissões adequadas à sua conta de serviço na conta de cliente do Google Ads. Para fazer isso, você precisa de acesso de administrador à conta de cliente.
Como conceder acesso à conta de serviço à sua conta do Google Ads
- Comece fazendo login na sua conta do Google Ads como administrador.
- Acesse Admin > 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
Adicionar conta botão. O nível de acesso por 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
conta 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 suspensa ao lado do nível de acesso da conta de serviço na coluna Nível de acesso.
- Selecione Admin na lista suspensa.
Fazer o download de ferramentas e bibliotecas de cliente
Você pode fazer o download de uma biblioteca de cliente ou de um cliente HTTP, dependendo de como você quer fazer 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.
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 para o restante deste guia foram verificadas para funcionar com a versão a seguir 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, na sigla em inglês) 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>48.0.0</version>
</dependency>
Gradle: adicione a seguinte dependência ao arquivo build.gradle:
implementation 'com.google.api-ads:google-ads:48.0.0'
Crie um arquivo ads.properties no seu diretório principal (~/ads.properties
no Linux e 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 seu 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.5.0Para fazer chamadas de API, crie um objeto GoogleAdsConfig nas configurações (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
GoogleAdsService.SearchStream
método para recuperar as campanhas na sua conta. Este guia não aborda
os detalhes da geração de relatórios.
public void Run(GoogleAdsClient client, long customerId)
{
// Get the GoogleAdsService.
GoogleAdsServiceClient googleAdsService = client.GetService(
Services.V26.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 do Composer instalados. Em seguida, mude para o diretório raiz do seu 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.2.0Faça uma cópia do
google_ads_php.ini
arquivo do repositório do GitHub, salve-o no seu diretório principal ou no seu
diretório 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\V26\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, execute um relatório de campanha usando o
GoogleAdsService.SearchStream
método 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==34.0.0Para autenticar suas chamadas de API, configure um arquivo google-ads.yaml:
- Faça o download de uma cópia do arquivo de exemplo
google-ads.yamldo repositório do GitHub. - Salve o arquivo no seu diretório principal (
~/google-ads.yaml) ou em um caminho personalizado. Abra
google-ads.yamle atualize-o para incluir suas credenciais:login_customer_id: INSERT_LOGIN_CUSTOMER_ID_HERE json_key_file_path: JSON_KEY_FILE_PATHConfigure a geração de registros antes de inicializar o cliente para que a biblioteca capture 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
GoogleAdsClient.load_from_storage método e transmitindo o caminho para o
google-ads.yaml arquivo:
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 principal (~/google-ads.yaml) por padrão.
Em seguida, execute um relatório de campanha usando o
GoogleAdsService.SearchStream
método 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 Bundler para instalar a biblioteca:
Adicione a gem ao
Gemfiledo seu aplicativo:gem 'google-ads-googleads', '~> 46.0.0'Instale a gem executando:
bundle install
Para configurar suas credenciais:
- Copie o arquivo de exemplo
google_ads_config.rbdo repositório do GitHub. - Salve o arquivo no diretório raiz do projeto ou no seu diretório principal (
~). Abra
google_ads_config.rbe substitua os valores do marcador pelas 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 o arquivo de configuração (google_ads_config.rb):
client = Google::Ads::GoogleAds::GoogleAdsClient.new(
'path/to/google_ads_config.rb'
)
Em seguida, execute um relatório de campanha usando o
GoogleAdsService.SearchStream
método 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 do Perl é distribuída no
CPAN e requer o Perl
5.28 ou mais recente e o cpan ou cpanm gerenciador de pacotes.
Clone o repositório
google-ads-perlno diretório de sua preferência:git clone https://github.com/googleads/google-ads-perl.gitMude para o diretório
google-ads-perle execute os comandos a seguir 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 principal (~/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 arquivo configuradogoogleads.properties(como~/googleads.properties):
my $api_client = Google::Ads::GoogleAds::Client->new({
properties_file => "/path/to/googleads.properties"
});
Em seguida, execute um relatório de campanha usando o
GoogleAdsService.SearchStream
método 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::V26::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 gcloud CLI.
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 contendo 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
GoogleAdsService.SearchStream
método para recuperar campanhas na sua conta:
curl -i -X POST \
https://googleads.googleapis.com/v26/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 Resolver erros de API para orientações sobre como solucionar problemas.