Estrutura do código

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, analisaremos a estrutura de uma amostra de código comum da Google AdWords API.

Depois, veremos 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 mais comuns da API. Elas realizam automaticamente a maioria das tarefas de back-end e facilitam muito o desenvolvimento dos aplicativos da Google AdWords API.

Vejamos 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ê verá um código padrão no parâmetro main que:

  • gera credenciais;
  • cria sessões do Google AdWords;
  • gera instâncias de serviços do Google AdWords.

Você conhecerá melhor essas ações à medida que explorar as amostras de código na biblioteca cliente.

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

E se você tiver 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. Depois de 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);

C#

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

Você verá 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 C#. As classes AdsUser geralmente englobam uma única conta de anúncios, neste caso, uma conta do Google AdWords.

Com a classe AdsWordsUser, é possível criar 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.

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

E se você tiver 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, definimos o ID do cliente no googleads.yaml. Por padrão, o método LoadFromStorage é configurado 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ê tiver 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 GetCampaigns.php.

Primeiro, o exemplo gera um token OAuth:

// Generate a refreshable OAuth2 credential for authentication.
$oAuth2Credential = (new OAuth2TokenBuilder())
    ->fromFile()
    ->build();

Então, ele usa o token para criar uma sessão da API na qual a função runExample() é executada:

// Construct an API session configured from a properties file and the OAuth2
// credentials above.
$session = (new AdWordsSessionBuilder())
    ->fromFile()
    ->withOAuth2Credential($oAuth2Credential)
    ->build();
self::runExample(new AdWordsServices(), $session);

runExample() é a função principal nesse exemplo. Ele recupera IDs e nomes de campanhas usando um seletor do CampaignService.

Perl

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

Na amostra, você verá 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 => "v201710"});

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

E se você tiver muitas contas de cliente na mesma conta de administrador? Nesse caso, você pode remover o ID do cliente do 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 => "v201710"});
$client->set_client_id("123-456-7890");

Ruby

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

Na amostra, você verá 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, definimos o ID do cliente no arquivo de configurações adwords_api.yml.

E se você tiver 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. Depois de 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, veremos alguns casos de uso que demonstram como as amostras de código podem ser usadas em praticamente qualquer função da API.

Os dois principais repositórios de funcionalidade da API são relatórios 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ê verá o mesmo código padrão no parâmetro main que observamos antes:

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

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

// 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 serem recuperados para o relatório.

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

C#

Acesse seu IDE e abra o arquivo DownloadCriteriaReport.cs.

Você verá o mesmo código padrão da 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());
  }
}

No entanto, o código interessante nessa amostra é aquele em que criamos uma hierarquia de objetos definindo o relatório desejado:

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 serem recuperados 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_with_selector.py.

Você verá 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)

No entanto, 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_with_selector.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 serem recuperados para o relatório na seção "Seletor", por exemplo, "CampaignId", "AdGroupId" etc.

PHP

Acesse seu IDE e abra o arquivo DownloadCriteriaReportWithSelector.php.

O exemplo tem o código padrão para autenticar e criar uma sessão do Google AdWords. Ele está na função principal runExample(), em que um seletor é criado e o relatório é definido:

// Create selector.
$selector = new Selector();
$selector->setFields(['CampaignId', 'AdGroupId', 'Id', 'Criteria',
    'CriteriaType', 'Impressions', 'Clicks', 'Cost']);

// Create report definition.
$reportDefinition = new ReportDefinition();
$reportDefinition->setSelector($selector);
$reportDefinition->setReportName(
    'Criteria performance report #' . uniqid());
$reportDefinition->setDateRangeType(
    ReportDefinitionDateRangeType::LAST_7_DAYS);
$reportDefinition->setReportType(
    ReportDefinitionReportType::CRITERIA_PERFORMANCE_REPORT);
$reportDefinition->setDownloadFormat(DownloadFormat::CSV);

O exemplo especifica um CRITERIA_PERFORMANCE_REPORT para o tipo de relatório, bem como os campos a serem recuperados para o relatório.

Então, a definição do relatório é passada para uma ferramenta de download de relatórios:

// Download report.
$reportDownloader = new ReportDownloader($session);
$reportDownloadResult =
    $reportDownloader->downloadReport($reportDefinition);
$reportDownloadResult->saveToFile($filePath);
printf("Report with name '%s' was downloaded to '%s'.\n",
    $reportDefinition->getReportName(), $filePath);

Execute o arquivo DownloadCriteriaReportWithSelector.php, e o console imprimirá o local do arquivo recebido por download.

Perl

Acesse seu IDE e abra o arquivo download_criteria_report_with_selector.pl.

Você verá 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 => "v201710"});

No entanto, o código interessante nessa amostra é aquele em que criamos um seletor definindo o relatório desejado:

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_with_selector.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 serem recuperados 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_with_selector.rb.

Você verá 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_with_selector(file_name)
  # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
  # when called without parameters.
  adwords = AdwordsApi::Api.new

No entanto, o código interessante nessa amostra é aquele em que criamos uma hierarquia de objetos definindo o relatório desejado:

# 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',
}

Depois, o passamos para o método report_utils.download_report_as_file:

# 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_with_selector.rb. A localização do arquivo recebido por download será impressa no console.

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 serem recuperados 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. É uma linguagem semelhante ao SQL. Com ela, você pode criar relatórios de forma menos detalhada do que usando objetos.

Java

Compare o código de amostra que acabamos de executar com o arquivo DownloadCriteriaReportWithAWQL.java: eles recuperam 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";

C#

Compare o código de amostra que acabamos de executar com o arquivo DownloadCriteriaReportWithAWQL.cs: eles recuperam 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: eles recuperam 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 exemplo de download de relatório pelo seletor com o arquivo DownloadCriteriaReportWithAwql.php. Ambos definem os mesmos tipos de relatório e campos e recuperam o mesmo relatório, mas a abordagem da AWQL é mais concisa:

// Create report query to get the data for last 7 days.
$reportQuery = 'SELECT CampaignId, AdGroupId, Id, Criteria, CriteriaType, '
    . 'Impressions, Clicks, Cost FROM CRITERIA_PERFORMANCE_REPORT '
    . 'WHERE Status IN [ENABLED, PAUSED] DURING LAST_7_DAYS';

Perl

Compare o código de amostra que acabamos de executar com o arquivo download_criteria_report_with_awql.pl: eles recuperam 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: eles recuperam 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 você conhece os princípios básicos da geração de relatórios, 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. Isso resultará em um melhor uso 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 antes. 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ê encontra esse código? Você pode gerá-lo de maneira programática, por meio do método get() da interface AdGroupService. Como um atalho, você pode pegar o código 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 do AdGroupService porque atualizará um grupo de anúncios. Para atualizar outras entidades, você deve 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 dele como o código do grupo de anúncios a ser atualizado.

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

Depois, define o status como PAUSED.

adGroup.setStatus(AdGroupStatus.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 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. Depois de executá-lo, faça login na conta de teste na interface da Web do Google AdWords e verifique se o status mudou.

C#

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ê encontra esse código? Você pode gerá-lo e maneira programática, por meio do método get() da interface AdGroupService. Como um atalho, você pode pegar o código 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 do AdGroupService porque atualizará um grupo de anúncios. Para atualizar outras entidades, você deve 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.v201710.AdGroupService);
}

Em seguida, ele cria um novo objeto AdGroup e define o código dele como o código do grupo de anúncios a ser atualizado.

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

Ele também define o status como PAUSED.

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 fim, 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. Depois de executá-lo, faça login na conta de teste na interface da Web do Google AdWords e verifique se o status mudou.

Python

No seu IDE, abra a amostra update_ad_group.py.

Vemos novamente o código padrão em que 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ê encontra esse código? Você pode gerá-lo e maneira programática, por meio do método get() da interface AdGroupService. Como um atalho, você pode pegar o código 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 do AdGroupService porque atualizará um grupo de anúncios. Para atualizar outras entidades, você deve 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='v201710')

Em seguida, ele define o código como o código do grupo de anúncios a ser atualizado e muda o status para PAUSED.

# 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 PAUSED.

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

Por fim, 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. Depois de executá-lo, faça login na conta de teste na interface da Web do Google AdWords e verifique se o status mudou.

PHP

No seu IDE, abra PauseAd.php.

O anúncio específico é identificado por meio do grupo de anúncios e de códigos de anúncio:

const AD_GROUP_ID = 'INSERT_AD_GROUP_ID_HERE';
const AD_ID = 'INSERT_AD_ID_HERE';

O código do grupo de anúncios pode ser recuperado por meio do método get() do AdGroupService ou do URL da interface da Web do Google AdWords ao visualizar o grupo de anúncios.

Agora vejamos runExample(), etapa por etapa:

  1. Busque uma referência a um objeto AdGroupService, já que estamos atualizando um grupo de anúncios.
    $adGroupAdService =
        $adWordsServices->get($session, AdGroupAdService::class);
    
  2. Crie um objeto de anúncio.
    $ad = new Ad();
    $ad->setId($adId);
    
  3. Crie um objeto de anúncio de um grupo de anúncio e defina o código e o anúncio dele.
    $adGroupAd = new AdGroupAd();
    $adGroupAd->setAdGroupId($adGroupId);
    $adGroupAd->setAd($ad);
    
  4. Defina o status do grupo de anúncios como PAUSED.
    $adGroupAd->setStatus(AdGroupAdStatus::PAUSED);
    
  5. Configure uma operação e envie-a para AdGroupAdService por meio do método mutate().
    // Create ad group ad operation and add it to the list.
    $operation = new AdGroupAdOperation();
    $operation->setOperand($adGroupAd);
    $operation->setOperator(Operator::SET);
    $operations[] = $operation;
    
    // Pause the ad on the server.
    $result = $adGroupAdService->mutate($operations);
    

Substitua os marcadores pelos códigos correspondentes da conta cliente de teste e execute o código. Após a conclusão, faça login na conta de teste na interface da Web do Google AdWords e verifique se o status mudou.

Perl

No seu IDE, abra a amostra update_ad_group.pl.

Na parte inferior, encontramos novamente o código padrão que vimos antes. 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ê quer pausar.

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

Onde você encontra esse código? Você pode gerá-lo e maneira programática, por meio do método get() da interface AdGroupService. Como um atalho, você pode pegar o código 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 adGroupID especificado. Para atualizar outras entidades, você deve usar o serviço correspondente delas. Uma lista completa dos serviços está disponível no guia Objetos, métodos e serviços. Em seguida, ele define o status como PAUSED.

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

Em seguida, ele 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::v201710::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. Depois de executá-lo, faça login na conta de teste na interface da Web do Google AdWords e verifique se o status mudou.

Ruby

Abra a amostra update_ad_group.rb.

Encontramos novamente o código padrão que vimos antes. 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ê encontra esse código? Você pode gerá-lo e maneira programática, por meio do método get() da interface AdGroupService. Como um atalho, você pode pegar o código 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 porque atualizará um grupo de anúncios. Para atualizar outras entidades, você deve 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 dele como o código do grupo de anúncios a ser atualizado. Além disso, ele 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. Depois de executá-lo, faça login na conta de teste na interface da Web do Google AdWords e verifique se o status mudou.

Como rever o padrão

O processo e o 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 a seguir:

  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.

Como é uma atualização, usamos o operador SET. Em adições ou remoções usamos os operadores ADD ou REMOVE.

Se estiver confuso, observe outras amostras de código para perceber melhor o padrão.

Agora que conhece o padrão, você pode fazer várias outras alterações com facilidade, por exemplo, modificar o lance para um grupo de anúncios.

Modificar lances para um grupo de anúncios

Outro caso de uso conhecido é modificar um lance de maneira programática. Um exemplo comum é aumentar o lance para um anúncio de guarda-chuvas quando estiver chovendo. 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. Nesse caso, em vez de definir AdGroupStatus, seria necessário definir . 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 eles seguem o mesmo padrão mencionado acima. Nesse caso, assim que a hierarquia do objeto é criada, 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.

C#

No seu IDE, observe AddCampaigns.cs.

São vários códigos, mas eles seguem o mesmo padrão mencionado acima. Nesse caso, assim que a hierarquia do objeto é criada, 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 eles seguem o mesmo padrão mencionado acima. Nesse caso, assim que a hierarquia do objeto é criada, 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, abra AddCampaigns.php.

Como normalmente, a maior parte da lógica está em runExample(). Criamos um orçamento, uma campanha e uma estratégia de lances e definimos configurações opcionais, como segmentação da rede e limite de frequência. Por fim, finalizamos a campanha com um operador ADD e enviamos a operação para o parâmetro CampaignService por meio do mutate().

Perl

No seu IDE, observe add_campaigns.pl.

São vários códigos, mas eles seguem o mesmo padrão mencionado acima. Nesse caso, assim que a hierarquia do objeto é criada, 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 eles seguem o mesmo padrão mencionado acima. Nesse caso, assim que a hierarquia do objeto é criada, 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 você conhece os princípios básicos, consulte Objetos, métodos e serviços e guias relacionados para saber mais sobre a arquitetura, os serviços e os recursos da API.

Depois, você estará pronto para começar a criar seu próprio aplicativo, aproveitando por completo a maior eficácia da automação e da visibilidade que os relatórios personalizados da Google AdWords API oferecem.

Enviar comentários sobre…

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