Amostras de código e casos de uso

Já concluímos as configurações para você realizar sua primeira chamada de API e revisamos os componentes de configuração necessários para realizar chamadas à API.

Neste guia, observaremos a estrutura de uma amostra de código comum da Google AdWords API.

Em seguida, examinaremos alguns casos de uso comuns que ilustram como as amostras de código podem ser usadas para integrar de modo prático qualquer funcionalidade da API no seu aplicativo.

Anatomia de uma amostra de código da API

As amostras de código fornecidas com bibliotecas cliente abrangem todas as funções da API mais comuns. Elas realizam automaticamente a maioria das tarefas de back-end e facilitam muito o desenvolvimento dos aplicativos da Google AdWords API.

Vamos observar a estrutura comum de uma amostra de código da Google AdWords API. Clique na guia abaixo para selecionar a linguagem desejada:

Java

No seu IDE, abra o arquivo de amostra que usamos no guia anterior: GetCampaigns.java.

No arquivo GetCampaigns.java, você encontrará um código padrão no parâmetro main que:

  • gera credenciais;
  • cria sessões do Google AdWords;
  • instancia serviços do Google AdWords.

Você se familiariza com essas ações à medida que explora as amostras de código na biblioteca cliente.

Há outra linha na amostra GetCampaigns de que você poderá precisar. Lembre-se de que no guia anterior nós definimos o ID do cliente no arquivo ads.properties.

E se você tem muitas contas de cliente na mesma conta de administrador? Nesse caso, você pode remover o ID do cliente do arquivo ads.properties e configurá-lo de maneira programática por meio do objeto da sessão do Google AdWords. Após criar o objeto, chame o parâmetro setClientCustomerID para programá-lo dinamicamente.

/ Construct an AdWordsSession.
    AdWordsSession session = new AdWordsSession.Builder()
        .fromFile()
        .withOAuth2Credential(oAuth2Credential)
        .build();

    session.setClientCustomerID("123-456-7890");

    AdWordsServices adWordsServices = new AdWordsServices();

    runExample(adWordsServices, session);
  }

.NET

No seu IDE, abra o arquivo de amostra que usamos no guia anterior: GetCampaigns.cs.

Você encontrará um código padrão no parâmetro main que faz referência ao AdWordsUser:
public static void Main(string[] args) {
      GetCampaigns codeExample = new GetCampaigns();
      Console.WriteLine(codeExample.Description);
      try {
        codeExample.Run(new AdWordsUser());

As classes AdsUser são as mais importantes na biblioteca .NET. As classes AdsUser geralmente englobam uma única conta de anúncios, neste caso, uma conta do Google AdWords.

A classe AdsWordsUser permite que você crie uma classe de serviços pré-configurada que pode ser usada para realizar chamadas de API com configurações específicas do arquivo app.config no seu aplicativo.

// Create a new AdWordsUser with the App.config settings.
AdWordsUser user = new AdWordsUser();

E se você tem muitas contas de cliente na mesma conta de administrador? Nesse caso, você pode defini-la de maneira programática usando a propriedade "Configuração" do objeto AdsUser para configurar o usuário em questão no tempo de execução:

// Create a default AdWordsUser instance. If any configuration
// is available in App.config, those will be used.
AdWordsUser user = new AdWordsUser();

// Override a specific setting at runtime.
AdWordsAppConfig config = (AdWordsAppConfig) user.Config;
user.Config.clientCustomerId = "123-456-7890";

Outra opção é usar o construtor que aceita uma instância AdWordsAppConfig, por exemplo:

// Create a config object with the values in App.config.
AdWordsAppConfig config = new AdWordsAppConfig();

// Override any specific setting you wish to change.
user.Config.clientCustomerId = "123-456-7890";

AdWordsUser user = new AdWordsUser(config);

Python

No seu IDE, abra o arquivo de amostra que usamos no guia anterior: get_campaigns.py.

Na amostra, os comentários indicam que o método LoadFromStorage está puxando credenciais e propriedades do arquivo googleads.yaml. Lembre-se de que no guia anterior nós definimos o ID do cliente no googleads.yaml. O método LoadFromStorage é configurado por padrão para buscar por um arquivo com esse nome no seu diretório inicial, embora você possa passar um caminho para qualquer arquivo com os conteúdos yaml corretos: Para usar o local padrão, seu diretório inicial:

adwords_client = adwords.AdWordsClient.LoadFromStorage()
Para passar no local do arquivo:
adwords_client = adwords.AdWordsClient.LoadFromStorage('C:\My\Directory\googleads.yaml')

E se você tem muitas contas de cliente na mesma conta de administrador? Nesse caso, você pode definir de maneira programática o ID do cliente no tempo de execução usando o código a seguir:

adwords_client = AdWordsClient.LoadFromStorage()
adwords_client.SetClientCustomerId('123-456-7890')

PHP

No seu IDE, abra o arquivo de amostra que usamos no guia anterior: GetCampaigns.php.

Na amostra GetCampaigns, você encontrará um código que recebe as informações de credenciais do seu arquivo de configurações, o auth.ini.

try {
  // Get AdWordsUser from credentials in "../auth.ini"
  // relative to the AdWordsUser.php file's directory.
  $user = new AdWordsUser();

Há outra linha na amostra GetCampaigns de que você poderá precisar. Lembre-se de que no guia anterior nós definimos o ID do cliente no arquivo auth.ini.

E se você tem muitas contas de cliente na mesma conta de administrador? Nesse caso, você pode remover o ID do cliente do arquivo auth.ini e defini-lo de maneira programática chamando o "SetClientCustomerId()" de um objeto "AdWordUser" com um parâmetro como o ID do cliente que deseja definir como:

// Create an AdWordsUser instance using the default constructor, which will load
// information from the auth.ini file as described above.
$user = new AdWordsUser();
$user->SetClientCustomerId('123-456-7890');

Perl

No seu IDE, abra o arquivo de amostra que usamos no guia anterior: get_campaigns.pl.

Na amostra, você encontrará um código que recebe as informações de credenciais do seu arquivo de configurações, o adwords.properties:

# Get AdWords Client, credentials will be read from ~/adwords.properties.
my $client = Google::Ads::AdWords::Client->new({version => "v201702"});

Lembre-se de que no guia anterior nós definimos o ID do cliente no arquivo adwords.properties.

E se você tem muitas contas de cliente na mesma conta de administrador? Nesse caso, você pode remover o ID do cliente do arquivo adwords.properties e configurá-lo de maneira programática chamando set_client_id:

# Get AdWords Client, credentials will be read from ~/adwords.properties.
my $client = Google::Ads::AdWords::Client->new({version => "v201702"});
$client->set_client_id("123-456-7890");

Ruby

Abra o arquivo de amostra que usamos no guia anterior: get_campaigns.rb.

Na amostra, você encontrará um código padrão no parâmetro main que recebe as informações de credenciais do arquivo de configurações adwords_api.yml.

  # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
  # when called without parameters.
  adwords = AdwordsApi::Api.new

Há outra linha na amostra de que você poderá precisar. Lembre-se de que no guia anterior nós definimos o ID do cliente no arquivo de configurações adwords_api.yml.

E se você tem muitas contas de cliente na mesma conta de administrador? Nesse caso, você pode remover o ID do cliente do arquivo adwords_api.yml e configurá-lo de maneira programática por meio do objeto da sessão do Google AdWords. Após criar o objeto, chame o parâmetro adwords.config.set para programá-lo dinamicamente.

# Set a new CID value
adwords.config.set("authentication.client_customer_id", "123-456-7890")

Como acessar as amostras de código

Você pode procurar todas as amostras de código da Google AdWords API nas nossas páginas de biblioteca cliente e amostras. As amostras abrangem as áreas principais dos recursos da API, incluindo:

  • gerenciamento de contas
  • gerenciamento de campanhas
  • como lidar com erros
  • otimização
  • relatórios
  • segmentação

Agora que você compreende a estrutura de uma amostra de código comum da Google AdWords API, observaremos alguns casos de uso que demonstram como as amostras de código podem ser usadas em praticamente qualquer função de API.

Os dois principais repositórios de funcionalidade da API são relatório e automação. Vamos começar com os relatórios.

Como usar amostras de código para gerar relatórios

Começaremos com uma amostra de código que faz o download de um relatório de desempenho de critérios:

Java

Acesse seu IDE e abra o arquivo DownloadCriteriaReport.java.

Você encontrará o mesmo código padrão no parâmetro main que observamos anteriormente:

public static void main(String[] args) throws Exception {
    // Generate a refreshable OAuth2 credential.
    Credential oAuth2Credential = new OfflineCredentials.Builder()
        .forApi(Api.ADWORDS)
        .fromFile()
        .build()
        .generateCredential();

    // Construct an AdWordsSession.
    AdWordsSession session = new AdWordsSession.Builder()
        .fromFile()
        .withOAuth2Credential(oAuth2Credential)
        .build();

Mas o método RunExample é que tem o código interessante nesta classe. Aqui, criamos uma hierarquia de objetos definindo o relatório que quisermos:

// Create report definition.
    ReportDefinition reportDefinition = new ReportDefinition();
    reportDefinition.setReportName("Criteria performance report #" + System.currentTimeMillis());
    reportDefinition.setDateRangeType(ReportDefinitionDateRangeType.YESTERDAY);
    reportDefinition.setReportType(ReportDefinitionReportType.CRITERIA_PERFORMANCE_REPORT);
    reportDefinition.setDownloadFormat(DownloadFormat.CSV);

Em seguida, passamos o relatório para uma instância do ReportDownloader:

 ReportDownloadResponse response =
          new ReportDownloader(session).downloadReport(reportDefinition);
      response.saveToFile(reportFile);

Continue e execute o arquivo DownloadCriteriaReport.java.

O console do IDE imprimirá o local do arquivo recebido por download.

Você verá que o código de amostra especifica um tipo de relatório, neste caso, um relatório de desempenho de critérios.

reportDefinition.setReportType(ReportDefinitionReportType.CRITERIA_PERFORMANCE_REPORT);

A amostra também especifica alguns campos a recuperar para o relatório.

Selector selector = new Selector();
    selector.getFields().addAll(Lists.newArrayList("CampaignId",
        "AdGroupId",
        "Id",
        "CriteriaType",
        "Criteria",
        "FinalUrls",
        "Impressions",
        "Clicks",
        "Cost"));

.NET

Acesse seu IDE e abra o arquivo DownloadCriteriaReport.cs

Você encontrará o mesmo código padrão que vimos na amostra anterior. Ele lida com a autenticação extraindo valores do arquivo app.config:

public static void Main(string[] args) {
      GetCampaigns codeExample = new GetCampaigns();
      Console.WriteLine(codeExample.Description);
      try {
        codeExample.Run(new AdWordsUser());

Mas o código interessante nessa amostra é aquele em que criamos uma hierarquia de objetos definindo o relatório que quisermos:

public void Run(AdWordsUser user, string fileName) {
      ReportDefinition definition = new ReportDefinition() {
        reportName = "Last 7 days CRITERIA_PERFORMANCE_REPORT",
        reportType = ReportDefinitionReportType.CRITERIA_PERFORMANCE_REPORT,
        downloadFormat = DownloadFormat.GZIPPED_CSV,
        dateRangeType = ReportDefinitionDateRangeType.LAST_7_DAYS,

Continue e execute o arquivo DownloadCriteriaReport.cs.

O console imprimirá o local do arquivo recebido por download.

Você verá que o código de amostra especifica um tipo de relatório, neste caso, um relatório de desempenho de critérios.

reportType = ReportDefinitionReportType.CRITERIA_PERFORMANCE_REPORT,

A amostra também especifica alguns campos a recuperar para o relatório.

selector = new Selector() {
          fields = new string[] {"CampaignId", "AdGroupId", "Id", "CriteriaType", "Criteria",
              "FinalUrls", "Clicks", "Impressions", "Cost"},
          predicates = new Predicate[] {
            Predicate.In("Status", new string[] {"ENABLED", "PAUSED"})

Python

Acesse seu IDE e abra o arquivo download_criteria_report.py.

Você encontrará o mesmo código padrão que vimos na amostra anterior. Ele lida com a autenticação extraindo valores do arquivo de configuração googleads.yaml:

adwords_client = adwords.AdWordsClient.LoadFromStorage()
  main(adwords_client)

Mas o código interessante nessa amostra é a hierarquia de objetos que define o relatório que nós queremos:

 # Create report definition.
  report = {
      'reportName': 'Last 7 days CRITERIA_PERFORMANCE_REPORT',
      'dateRangeType': 'LAST_7_DAYS',
      'reportType': 'CRITERIA_PERFORMANCE_REPORT',
      'downloadFormat': 'CSV',
      'selector': {
          'fields': ['CampaignId', 'AdGroupId', 'Id', 'CriteriaType',
                     'Criteria', 'FinalUrls', 'Impressions', 'Clicks', 'Cost']

Em seguida, passamos o relatório para uma instância do ReportDownloader:

 report_downloader.DownloadReport(
      report, sys.stdout, skip_report_header=False, skip_column_header=False,
      skip_report_summary=False)

Continue e execute o arquivo download_criteria_report.py.

Seu console imprimirá o local do arquivo recebido por download.

Você verá que o código de amostra especifica um tipo de relatório, neste caso, um relatório de desempenho de critérios.

A amostra também especifica alguns campos a recuperar para o relatório na seção "Seletor", por exemplo, "CampaignId". "AdGroupId" etc.

PHP

Acesse seu IDE e abra o arquivo DownloadCriteriaReport.php.

Você encontrará o mesmo código padrão que vimos na amostra anterior. Ele lida com a autenticação extraindo valores do arquivo de configuração auth.ini:

  // Get AdWordsUser from credentials in "../auth.ini"
  // relative to the AdWordsUser.php file's directory.
  $user = new AdWordsUser();

Mas o código interessante nessa amostra é aquele em que criamos um seletor definindo o relatório que quisermos:

  // Create report definition.
  $reportDefinition = new ReportDefinition();
  $reportDefinition->selector = $selector;
  $reportDefinition->reportName = 'Criteria performance report #' . uniqid();
  $reportDefinition->dateRangeType = 'LAST_7_DAYS';
  $reportDefinition->reportType = 'CRITERIA_PERFORMANCE_REPORT';
  $reportDefinition->downloadFormat = 'CSV';

Em seguida, passamos o relatório a um gerenciador de downloads:

  // Download report.
  ReportUtils::DownloadReport($reportDefinition, $filePath, $user, $options);
  printf("Report with name '%s' was downloaded to '%s'.\n",
      $reportDefinition->reportName, $filePath);

Continue e execute o arquivo DownloadCriteriaReport.php.

O console imprimirá o local do arquivo recebido por download.

Você verá que o código de amostra especifica um tipo de relatório, neste caso, um relatório de desempenho de critérios.

$reportDefinition->reportType = 'CRITERIA_PERFORMANCE_REPORT';

A amostra também especifica alguns campos a recuperar para o relatório.

$selector->fields = array('CampaignId', 'AdGroupId', 'Id', 'Criteria',
      'CriteriaType', 'Impressions', 'Clicks', 'Cost');

Perl

Acesse seu IDE e abra o arquivo download_criteria_report.pl.

Você encontrará o mesmo código padrão que vimos na amostra anterior. Ele lida com a autenticação extraindo valores do arquivo de configuração adwords.properties:

# Get AdWords Client, credentials will be read from ~/adwords.properties.
my $client = Google::Ads::AdWords::Client->new({version => "v201702"});

Mas o código interessante nessa amostra é aquele em que criamos um seletor e uma definição de relatório definindo o relatório que quisermos:

my $report_definition = Google::Ads::AdWords::Reports::ReportDefinition->new({
      reportName     => "Last 7 days CRITERIA_PERFORMANCE_REPORT #" . $today,
      dateRangeType  => "LAST_7_DAYS",
      reportType     => "CRITERIA_PERFORMANCE_REPORT",
      downloadFormat => "CSV",
      selector       => $selector
  });

Em seguida, passamos o relatório para uma instância do ReportDownloader:

 # Download the report using the appropriate method on ReportDownloadHandler.
  my $result;
  if ($output_file) {
    $result = $report_handler->save($output_file);
  } else {
    $result = $report_handler->get_as_string();
  }

Continue e execute o arquivo download_criteria_report.pl.

O console imprimirá o local do arquivo recebido por download.

Você verá que o código de amostra especifica um tipo de relatório, neste caso, um relatório de desempenho de critérios.

reportType     => "CRITERIA_PERFORMANCE_REPORT",

A amostra também especifica alguns campos a recuperar para o relatório.

# Create selector.
  my $selector = Google::Ads::AdWords::Reports::Selector->new({
      fields => [
        "CampaignId", "AdGroupId", "Id",          "CriteriaType",
        "Criteria",   "FinalUrls", "Impressions", "Clicks",
        "Cost"
      ]});

Ruby

Abra o arquivo download_criteria_report.rb.

Você encontrará o mesmo código padrão que vimos na amostra anterior. Ele lida com a autenticação extraindo valores do arquivo de configuração adwords_api.yml:

def download_criteria_report(file_name)
  # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
  # when called without parameters.
  adwords = AdwordsApi::Api.new

Mas o código interessante nessa amostra é aquele em que criamos uma hierarquia de objetos definindo o relatório que quisermos:

  # Define report definition. You can also pass your own XML text as a string.
  report_definition = {
    :selector => {
      :fields => ['CampaignId', 'AdGroupId', 'Id', 'Criteria', 'CriteriaType',
          'FinalUrls', 'Impressions', 'Clicks', 'Cost'],
    },
...

    :report_name => 'Last 7 days CRITERIA_PERFORMANCE_REPORT',
    :report_type => 'CRITERIA_PERFORMANCE_REPORT',
    :download_format => 'CSV',
    :date_range_type => 'LAST_7_DAYS',

Em seguida, passe o relatório para a instância do download_report:

 # Download report, using "download_report_as_file" utility method.
 # To retrieve the report as return value, use "download_report" method.
  report_utils.download_report_as_file(report_definition, file_name)
  puts "Report was downloaded to '%s'." % file_name
end

Continue e execute o arquivo download_criteria_report.rb.

O console imprimirá o local do arquivo recebido por download.

Você verá que o código de amostra especifica um tipo de relatório, neste caso, um relatório de desempenho de critérios.

:report_type => 'CRITERIA_PERFORMANCE_REPORT',

A amostra também especifica alguns campos a recuperar para o relatório.

:fields => ['CampaignId', 'AdGroupId', 'Id', 'Criteria', 'CriteriaType',
          'FinalUrls', 'Impressions', 'Clicks', 'Cost'],

Consulte a página Tipos de relatório para ver uma lista completa com os tipos de relatório e os campos contidos neles.

Você pode usar essa amostra de código junto com as informações da página Tipos de relatório para definir, criar e fazer o download de qualquer tipo de relatório necessário.

Linguagem de consulta do Google AdWords (AWQL, na sigla em inglês)

Além de definir relatórios com uma hierarquia de objetos, você também pode usar a AWQL. Esta é uma linguagem semelhante ao SQL, com ela você pode criar relatórios de forma menos detalhada em comparação com objetos.

Java

Compare o código de amostra que acabamos de executar com o arquivo DownloadCriteriaReportWithAWQL.java: ele recupera o mesmo relatório, mas a AWQL é mais concisa. Os tipos de relatório e os campos são os mesmos nas duas abordagens.

String query = "SELECT CampaignId, AdGroupId, Id, Criteria, CriteriaType, "
        + "Impressions, Clicks, Cost FROM CRITERIA_PERFORMANCE_REPORT "
        + "WHERE Status IN [ENABLED, PAUSED] "
        + "DURING YESTERDAY";

.NET

Compare o código de amostra que acabamos de executar com o arquivo DownloadCriteriaReportWithAWQL.cs: ele recupera o mesmo relatório, mas a AWQL é mais concisa. Os tipos de relatório e os campos são os mesmos nas duas abordagens.

string query = "SELECT CampaignId, AdGroupId, Id, Criteria, CriteriaType, Impressions, " +
          "Clicks, Cost FROM CRITERIA_PERFORMANCE_REPORT WHERE Status IN [ENABLED, PAUSED] " +
          "DURING LAST_7_DAYS";

Python

Compare o código de amostra que acabamos de executar com o arquivo download_criteria_report_with_awql.py: ele recupera o mesmo relatório, mas a AWQL é mais concisa. Os tipos de relatório e os campos são os mesmos nas duas abordagens.

report_query = ('SELECT CampaignId, AdGroupId, Id, Criteria, CriteriaType, '
                  'FinalUrls, Impressions, Clicks, Cost '
                  'FROM CRITERIA_PERFORMANCE_REPORT '
                  'WHERE Status IN [ENABLED, PAUSED] '
                  'DURING LAST_7_DAYS')

PHP

Compare o código de amostra que acabamos de executar com o arquivo DownloadCriteriaReportWithAwql.php: ele recupera o mesmo relatório, mas a AWQL é mais concisa. Os tipos de relatório e os campos são os mesmos nas duas abordagens.

$reportQuery = 'SELECT CampaignId, AdGroupId, Id, Criteria, CriteriaType, '
      . 'Impressions, Clicks, Cost FROM CRITERIA_PERFORMANCE_REPORT '
      . 'WHERE Status IN [ENABLED, PAUSED] DURING ' . $dateRange;

Nesse caso, o período é definido no código, logo antes da AWQL:

  // Prepare a date range for the last week. Instead you can use 'LAST_7_DAYS'.
  $dateRange = sprintf('%d,%d',
      date('Ymd', strtotime('-7 day')), date('Ymd', strtotime('-1 day')));

Perl

Compare o código de amostra que acabamos de executar com o arquivo download_criteria_report_with_awql.pl: ele recupera o mesmo relatório, mas a AWQL é mais concisa. Os tipos de relatório e os campos são os mesmos nas duas abordagens.

my $report_query =
    "SELECT CampaignId, AdGroupId, Id, Criteria, CriteriaType, " .
    "Impressions, Clicks, Cost FROM CRITERIA_PERFORMANCE_REPORT " .
    ""WHERE Status IN [ENABLED, PAUSED] " . "DURING $last_4_days, $yesterday";";

Nesse caso, o período do relatório é definido no código, logo antes da AWQL:

  # Create report query.
  my (undef, undef, undef, $mday, $mon, $year) = localtime(time - 60 * 60 * 24);
  my $yesterday = sprintf("%d%02d%02d", ($year + 1900), ($mon + 1), $mday);
  (undef, undef, undef, $mday, $mon, $year) =
    localtime(time - 60 * 60 * 24 * 4);
  my $last_4_days = sprintf("%d%02d%02d", ($year + 1900), ($mon + 1), $mday);

Ruby

Compare o código de amostra que acabamos de executar com o arquivo download_criteria_report_with_awql.rb: ele recupera o mesmo relatório, mas a AWQL é mais concisa. Os tipos de relatório e os campos são os mesmos nas duas abordagens.

report_query = 'SELECT CampaignId, AdGroupId, Id, Criteria, CriteriaType, ' +
      'Impressions, Clicks, Cost FROM CRITERIA_PERFORMANCE_REPORT ' +
      'WHERE Status IN [ENABLED, PAUSED] ' +
      'DURING %s' % date_range

Nesse caso, o período é definido no código, logo antes da AWQL:

  # Prepare a date range for the last week. Instead you can use 'LAST_7_DAYS'.
  date_range = '%s,%s' % [
      DateTime.parse((Date.today - 7).to_s).strftime('%Y%m%d'),
      DateTime.parse((Date.today - 1).to_s).strftime('%Y%m%d')
  ]

Agora que compreende os princípios básicos da geração de relatórios, você tem as ferramentas necessárias para começar a criar sua própria plataforma de relatórios personalizada.

Como usar amostras de código para automação

Examinaremos aqui a forma como você pode usar as amostras de código para fazer atualizações nas suas contas do Google AdWords e outros casos de uso comuns. Veremos, também, como essas amostras funcionam como base para quase todos os tipos de automação.

Pausar e retomar grupos de anúncios

Um dos casos de uso mais comuns da API é pausar e retomar grupos de anúncios. Por exemplo, você pode pausar um anúncio quando o inventário de um item estiver esgotado, o que resulta no uso aprimorado do seu orçamento de publicidade.

Esse caso de uso destaca o poder da integração dos seus próprios sistemas, como o acompanhamento de inventário, usando a Google AdWords API.

Usaremos amostras de código para pausar e retomar um grupo de anúncios:

Java

Inicie seu IDE e abra a amostra UpdateAdGroup.java.

Encontraremos novamente o código padrão no parâmetro main que observamos anteriormente. Desta vez main tem uma string de marcador perto da parte inferior do código do grupo de anúncios.

public static void main(String[] args) throws Exception {
    // Generate a refreshable OAuth2 credential.
    Credential oAuth2Credential = new OfflineCredentials.Builder()
        .forApi(Api.ADWORDS)
        .fromFile()
        .build()
        .generateCredential();

    // Construct an AdWordsSession.
    AdWordsSession session = new AdWordsSession.Builder()
        .fromFile()
        .withOAuth2Credential(oAuth2Credential)
        .build();

    Long adGroupId = Long.parseLong("INSERT_AD_GROUP_ID_HERE");

Onde você conseguiria esse código? Você pode consegui-lo de maneira programática, por meio do método GET da interface AdGroupService. Um atalho para receber o código consiste em retirá-lo do URL da interface da Web do Google AdWords ao visualizar o grupo de anúncios.

Novamente, o método runExample tem o código interessante. Vejamos o que ele faz, etapa por etapa:

Primeiro, ele recebe uma referência para a interface AdGroupService, pois atualizará um grupo de anúncios. Para atualizar outras entidades, você precisaria usar o serviço correspondente delas. Uma lista completa dos serviços está disponível no guia Objetos, métodos e serviços.

// Get the AdGroupService.
    AdGroupServiceInterface adGroupService =
        adWordsServices.get(session, AdGroupServiceInterface.class);

Em seguida, ele cria um novo objeto de grupo de anúncios e define o código desse novo objeto como o código do grupo de anúncios que deseja atualizar.

// Create ad group with updated status.
    AdGroup adGroup = new AdGroup();
    adGroup.setId(adGroupId);

Depois, define o status como PAUSADO.

adGroup.setStatus(AdGroupStatus.PAUSED);

Em seguida, ele cria um parâmetro AdGroupOperation usando o objeto de grupo de anúncios recém-criado como o operando e SET como o operador.

// Create operations.
    AdGroupOperation operation = new AdGroupOperation();
    operation.setOperand(adGroup);
    operation.setOperator(Operator.SET);

Por último, ele chama o método mutate da interface AdGroupService, passando o objeto de operação do grupo de anúncios.

// Update ad group.
    AdGroupReturnValue result = adGroupService.mutate(operations);

Substitua o marcador por um código do grupo de anúncios da sua conta de cliente de teste e tente executar o código. Após executá-lo, faça login na conta de teste na interface da Web do Google AdWords e confirme se o status foi alterado.

.NET

No seu IDE, abra a amostra UpdateAdGroup.cs.

Encontraremos novamente o código padrão no parâmetro main que observamos na seção anterior. Desta vez main tem uma string de marcador perto da parte inferior do código do grupo de anúncios.

public static void Main(string[] args) {
      UpdateAdGroup codeExample = new UpdateAdGroup();
      Console.WriteLine(codeExample.Description);
      try {
        long adGroupId = long.Parse("INSERT_ADGROUP_ID_HERE");
        codeExample.Run(new AdWordsUser(), adGroupId);

Onde você conseguiria esse código? Você pode consegui-lo de maneira programática, por meio do método GET da interface AdGroupService. Um atalho para receber o código consiste em retirá-lo do URL da interface da Web do Google AdWords ao visualizar o grupo de anúncios.

Novamente, o método runExample tem o código interessante. Vejamos o que ele faz, etapa por etapa:

Primeiro, ele recebe uma referência para a interface AdGroupService, pois atualizará um grupo de anúncios. Para atualizar outras entidades, você precisaria usar o serviço correspondente delas. Uma lista completa dos serviços está disponível no guia Objetos, métodos e serviços.

public void Run(AdWordsUser user, long adGroupId) {
      // Get the AdGroupService.
      AdGroupService adGroupService =
          (AdGroupService) user.GetService(AdWordsService.v201702.AdGroupService);

Em seguida, ele cria um novo objeto de AdGroup e define o código desse novo objeto como o código do grupo de anúncios que deseja atualizar.

// Create the ad group.
      AdGroup adGroup = new AdGroup();
      adGroup.status = AdGroupStatus.PAUSED;
      adGroup.id = adGroupId;

Ele também define o status para PAUSADO.

adGroup.status = AdGroupStatus.PAUSED;

Em seguida, ele cria um parâmetro AdGroupOperation usando o objeto adGroup recém-criado como o operando e SET como o operador.

// Create the operation.
      AdGroupOperation operation = new AdGroupOperation();
      operation.@operator = Operator.SET;
      operation.operand = adGroup;

Por último, ele chama o método mutate da interface AdGroupService, passando o objeto AdGroupOperation.

// Update the ad group.
        AdGroupReturnValue retVal = adGroupService.mutate(new AdGroupOperation[] {operation});

Substitua o marcador por um código do grupo de anúncios da sua conta de cliente de teste e tente executar o código. Após executá-lo, faça login na conta de teste na interface da Web do Google AdWords e confirme se o status foi alterado.

Python

No seu IDE, abra a amostra update_ad_group.py.

Vemos novamente o código padrão onde o método LoadFromStorage está puxando credenciais e propriedades do arquivo de configuração googleads.yaml. Desta vez, uma string de marcador é adicionada para o código do grupo de anúncios.

AD_GROUP_ID = 'INSERT_AD_GROUP_ID_HERE'

Onde você conseguiria esse código? Você pode consegui-lo de maneira programática, por meio do método GET da interface AdGroupService. Um atalho para receber o código consiste em retirá-lo do URL da interface da Web do Google AdWords ao visualizar o grupo de anúncios.

O código interessante vem depois. Vejamos o que ele faz, etapa por etapa:

Primeiro, ele recebe uma referência para a interface AdGroupService, pois atualizará um grupo de anúncios. Para atualizar outras entidades, você precisaria usar o serviço correspondente delas. Uma lista completa dos serviços está disponível no guia Objetos, métodos e serviços.

def main(client, ad_group_id):
  # Initialize appropriate service.
  ad_group_service = client.GetService('AdGroupService', version='v201702')

Em seguida, ele define o código como o código do grupo de anúncios que deseja atualizar e muda o status para PAUSADO.

# Construct operations and update an ad group.
  operations = [{
      'operator': 'SET',
      'operand': {
          'id': ad_group_id,
          'status': 'PAUSED'

Em seguida, ele cria uma operação de grupo de anúncios usando o objeto de grupo de anúncios recém-criado como o operando e SET como o operador e muda o status para PAUSADO.

# Construct operations and update an ad group.
  operations = [{
      'operator': 'SET',
      'operand': {
          'id': ad_group_id,
          'status': 'PAUSED'

Por último, ele chama o método mutate da interface de serviço do grupo de anúncios, passando o objeto de operação do grupo de anúncios.

ad_groups = ad_group_service.mutate(operations)

Substitua o marcador por um código do grupo de anúncios da sua conta de cliente de teste e tente executar o código. Após executá-lo, faça login na conta de teste na interface da Web do Google AdWords e confirme se o status foi alterado.

PHP

No seu IDE, abra a amostra PauseAd.php.

Vemos novamente o código padrão para extrairmos as informações de autenticação do arquivo de configurações auth.ini.

Desta vez, há uma string de marcador para o código do grupo de anúncios e o anúncio.

// Enter parameters required by the code example.
$adGroupId = 'INSERT_AD_GROUP_ID_HERE';
$adId = 'INSERT_AD_ID_HERE';

Onde você conseguiria esse código? Você pode consegui-lo de maneira programática, por meio do método GET da interface AdGroupService. Um atalho para receber o código consiste em retirá-lo do URL da interface da Web do Google AdWords ao visualizar o grupo de anúncios.

O código interessante nesta amostra surge quando ela é executada. Vejamos o que ele faz, etapa por etapa:

Primeiro, ele recebe uma referência para a interface AdGroupService, pois atualizará um grupo de anúncios. Para atualizar outras entidades, você precisaria usar o serviço correspondente delas. Uma lista completa dos serviços está disponível no guia Objetos, métodos e serviços.

  // Get the service, which loads the required classes.
  $adGroupAdService = $user->GetService('AdGroupAdService', ADWORDS_VERSION);

Em seguida, ele cria o anúncio usando um código existente.

  // Create ad using an existing ID. Use the base class Ad instead of TextAd to
  // avoid having to set ad-specific fields.
  $ad = new Ad();
  $ad->id = $adId;

Em seguida, ele cria um novo objeto de grupo de anúncios e define o código do novo objeto para o código do grupo de anúncios que deseja atualizar.

  // Create ad group ad.
  $adGroupAd = new AdGroupAd();
  $adGroupAd->adGroupId = $adGroupId;
  $adGroupAd->ad = $ad;

Depois, define o status como PAUSADO.

  // Update the status.
  $adGroupAd->status = 'PAUSED';

Em seguida, ele cria um AdGroupOperation usando o objeto do grupo de anúncios recém-criado como o operando, e SET como o operador.

  // Create operation.
  $operation = new AdGroupAdOperation();
  $operation->operand = $adGroupAd;
  $operation->operator = 'SET';
  $operations = array($operation);

Por último, ele chama o método mutate da interface "AdGroupService", passando o objeto de operação do grupo de anúncios.

  // Make the mutate request.
  $result = $adGroupAdService->mutate($operations);

Substitua o marcador por um código do grupo de anúncios da sua conta de cliente de teste e tente executar o código. Após executá-lo, faça login na conta de teste na interface da Web do Google AdWords e confirme se o status foi alterado.

Perl

No seu IDE, abra a amostra update_ad_group.pl.

Encontramos novamente na parte inferior o código padrão que vimos anteriormente. Ele puxa as credenciais do arquivo de configurações adwords.properties.

Nesta amostra, uma string de marcador é adicionada para o código do grupo de anúncios e para o anúncio que você deseja pausar.

# Replace with valid values of your account.
my $ad_group_id = "INSERT_AD_GROUP_ID_HERE";

Onde você conseguiria esse código? Você pode consegui-lo de maneira programática, por meio do método GET da interface AdGroupService. Um atalho para receber o código consiste em retirá-lo do URL da interface da Web do Google AdWords ao visualizar o grupo de anúncios.

O código interessante nesta amostra surge quando ela é executada. Vejamos o que ele faz, etapa por etapa:

Primeiro, ele cria um grupo de anúncios com o status atualizado usando o especificado adGroupID . Para atualizar outras entidades que você usaria seu serviço correspondente. Uma lista completa dos serviços está disponível no guia Objetos, métodos e serviços. Em seguida, ele define o status como PAUSADO.

 # Create ad group with updated status.
  my $ad_group = Google::Ads::AdWords::v201702::AdGroup->new({
      id     => $ad_group_id,
      status => "PAUSED"
  });

Em seguida, cria uma operação de grupo de anúncios usando o objeto do grupo de anúncios recém-criado como o operando, e SET como o operador.

# Create operation.
  my $operation = Google::Ads::AdWords::v201702::AdGroupOperation->new({
      operand  => $ad_group,
      operator => "SET"
  });

Por último, ele chama o método mutate da interface AdGroupService, passando o objeto de operação do grupo de anúncios.

# Update ad group.
  my $result = $client->AdGroupService()->mutate({operations => [$operation]});

Substitua o marcador por um código do grupo de anúncios da sua conta de cliente de teste e tente executar o código. Após executá-lo, faça login na conta de teste na interface da Web do Google AdWords e confirme se o status foi alterado.

Ruby

Abra a amostra update_ad_group.rb.

Encontramos outra vez o código padrão que vimos anteriormente. Ele usa as credenciais do arquivo de configurações adwords_api.yml. Desta vez, percebemos que há uma string de marcador para o código do grupo de anúncios.

    # ID of an ad group to update.
    ad_group_id = 'INSERT_AD_GROUP_ID_HERE'.to_i

Onde você conseguiria esse código? Você pode consegui-lo de maneira programática, por meio do método GET da interface AdGroupService. Um atalho para receber o código consiste em retirá-lo do URL da interface da Web do Google AdWords ao visualizar o grupo de anúncios.

Mais uma vez, o código interessante nesta amostra surge quando ela é executada. Vejamos o que ele faz, etapa por etapa:

Primeiro, ele recebe uma referência para a interface de serviço do AdGroup, pois atualizará um grupo de anúncios. Para atualizar outras entidades, você precisaria usar o serviço correspondente delas. Uma lista completa dos serviços está disponível no guia Objetos, métodos e serviços.

ad_group_srv = adwords.service(:AdGroupService, API_VERSION)

Em seguida, ele cria um novo objeto de grupo de anúncios e define o código do novo objeto para o código do grupo de anúncios que deseja atualizar, e define seu status como PAUSED , usando SET como o operador.

# Prepare for updating ad group.
  operation = {
    :operator => 'SET',
    :operand => {
      :status => 'PAUSED',
      :id => ad_group_id
    }
  }

Por último, ele chama o método mutate da interface AdGroupService, passando o objeto de operação do grupo de anúncios.

# Update ad group.
  response = ad_group_srv.mutate([operation])

Substitua o marcador por um código do grupo de anúncios da sua conta de cliente de teste e tente executar o código. Após executá-lo, faça login na conta de teste na interface da Web do Google AdWords e confirme se o status foi alterado.

Como rever o padrão

Os mesmos processo e padrão que usamos para pausar e retomar o grupo de anúncios acima são usados para a maioria das atualizações por meio da API, por isso convém revisar as etapas:

  1. Crie um novo objeto.
  2. Defina o código dele como código da entidade que você deseja modificar.
  3. Defina o novo valor da propriedade no novo objeto.
  4. Crie um objeto de operação com parâmetro "SET" como o operador e esse novo objeto da entidade como o operando.
  5. Passe o objeto de operação no método "MUTATE" do serviço apropriado.

Esta era uma atualização, por isso usamos o operador "SET". Adições ou remoções usam os operadores "ADD" ou "REMOVE".

Se parecer confuso, observe outras amostras de código e veja rapidamente o padrão.

Agora que sabe o padrão, você pode facilmente fazer muitas outras alterações, por exemplo, modificar o lance para um grupo de anúncios.

Modificar lances para um grupo de anúncios

Outro caso de uso comum é modificar um lance de forma programática. O exemplo comum é aumentar o lance para um anúncio de guarda-chuvas em épocas chuvosas. Seu aplicativo pode utilizar um serviço de previsão de tempo da Web e, em seguida, uma Google AdWords API para aumentar o lance para esse grupo de anúncios.

Você pode modificar a mesma amostra "UpdateAdGroup" que observamos acima para fazer essa atualização: em vez de definir AdGroupStatus, você precisaria definir a estratégia de lance. Consulte o Guia de lances para ver mais informações.

Criar novas campanhas

Outro caso de uso:

Java

No seu IDE, observe AddCampaigns.java.

São vários códigos, mas seguem o mesmo padrão mencionado acima. Nesse caso, assim que a hierarquia do objeto é criada, nós usamos o operador ADD para adicionar um novo orçamento por meio do parâmetro BudgetService e novas campanhas por meio do parâmetro CampaignService.

Não é necessário definir os códigos aqui, já que essas entidades são novas e ainda não têm códigos.

.NET

No seu IDE, observe AddCampaigns.cs.

São vários códigos, mas seguem o mesmo padrão mencionado acima. Nesse caso, assim que a hierarquia do objeto é criada, nós usamos o operador ADD para adicionar um novo orçamento por meio do parâmetro BudgetService e novas campanhas por meio do parâmetro CampaignService.

Não é necessário definir os códigos aqui, já que essas entidades são novas e ainda não têm códigos.

Python

No seu IDE, observe add_campaigns.py.

São vários códigos, mas seguem o mesmo padrão mencionado acima. Nesse caso, assim que a hierarquia do objeto é criada, nós usamos o operador ADD para adicionar um novo orçamento por meio do parâmetro BudgetService e novas campanhas por meio do parâmetro CampaignService.

Não é necessário definir os códigos aqui, já que essas entidades são novas e ainda não têm códigos.

PHP

No seu IDE, observe AddCampaigns.php.

São vários códigos, mas seguem o mesmo padrão mencionado acima. Nesse caso, assim que a hierarquia do objeto é criada, nós usamos o operador ADD para adicionar um novo orçamento por meio do parâmetro BudgetService e novas campanhas por meio do parâmetro CampaignService.

Não é necessário definir os códigos aqui, já que essas entidades são novas e ainda não têm códigos.

Perl

No seu IDE, observe add_campaigns.pl.

São vários códigos, mas seguem o mesmo padrão mencionado acima. Nesse caso, assim que a hierarquia do objeto é criada, nós usamos o operador ADD para adicionar um novo orçamento por meio do parâmetro BudgetService e novas campanhas por meio do parâmetro CampaignService.

Não é necessário definir os códigos aqui, já que essas entidades são novas e ainda não têm códigos.

Ruby

Observe add_campaigns.rb.

São vários códigos, mas seguem o mesmo padrão mencionado acima. Nesse caso, assim que a hierarquia do objeto é criada, nós usamos o operador ADD para adicionar um novo orçamento por meio do parâmetro BudgetService e novas campanhas por meio do parâmetro CampaignService.

Não é necessário definir os códigos aqui, já que essas entidades são novas e ainda não têm códigos.

Próximas etapas

Agora que conhece os princípios básicos, veja Objetos, métodos e serviços e outros guias na seção Arquitetura e conceitos para saber mais sobre a arquitetura da API, os serviços oferecidos pela API e como integrar os recursos da API no seu aplicativo.

Em seguida, você estará pronto para começar a criar seu próprio aplicativo, aproveitando por completo a eficácia aprimorada por meio da automação e uma visibilidade maior por meio dos relatórios personalizados oferecidos pela Google AdWords API.

Enviar comentários sobre…

Precisa de ajuda? Acesse nossa página de suporte.