Sprawdzone metody

Na tej stronie znajdziesz różne sprawdzone metody tworzenia skryptów Google Ads.

Selektory

Filtrowanie za pomocą selektorów

Jeśli to możliwe, używaj filtrów, aby żądać tylko potrzebnych encji. Zastosowanie odpowiednich filtrów ma te zalety:

• Kod jest prostszy i łatwiejszy do zrozumienia.
• Skrypt będzie wykonywany znacznie szybciej.

Porównaj te fragmenty kodu:

var keywords = AdsApp.keywords()
    .withCondition('Clicks > 10')
    .forDateRange('LAST_MONTH')
    .get();
while (keywords.hasNext()) {
  var keyword = keywords.next();
  // Do work here.
}

var keywords = AdsApp.keywords().get();

while (keywords.hasNext()) {
  var keyword = keywords.next();
  var stats = keyword.getStatsFor(
      'LAST_MONTH');
  if (stats.getClicks() > 10) {
    // Do work here.
  }
}

Drugie podejście nie jest zalecane, ponieważ próbuje pobrać listę wszystkich słów kluczowych na koncie tylko po to, aby zastosować do niej filtr.

Unikaj przechodzenia przez hierarchię kampanii

Jeśli chcesz pobrać jednostki na określonym poziomie, użyj metody kolekcji na tym poziomie zamiast przechodzić przez całą hierarchię kampanii. To nie tylko prostsze, ale też znacznie wydajniejsze rozwiązanie, ponieważ system nie musi niepotrzebnie wczytywać wszystkich kampanii i grup reklam.

Porównaj te fragmenty kodu, które pobierają wszystkie reklamy na Twoim koncie:

var ads = AdsApp.ads();

var campaigns = AdsApp.campaigns().get();
while (campaigns.hasNext()) {
  var adGroups = campaigns.next().
      adGroups().get();
  while (adGroups.hasNext()) {
    var ads = adGroups.next().ads().get();
    // Do your work here.
  }
}

Drugie podejście nie jest zalecane, ponieważ próbuje pobrać całe hierarchie obiektów (kampanie, grupy reklam), gdy wymagane są tylko reklamy.

Używanie konkretnych akcesorów nadrzędnych

Czasami trzeba uzyskać jednostkę nadrzędną pobranego obiektu. W takim przypadku zamiast pobierać całe hierarchie należy użyć udostępnionego akcesora.

Porównaj te fragmenty kodu, które pobierają grupy reklam zawierające reklamy tekstowe z ponad 50 kliknięciami w zeszłym miesiącu:

var ads = AdsApp.ads()
    .withCondition('Clicks > 50')
    .forDateRange('LAST_MONTH')
    .get();

while (ads.hasNext()) {
  var ad = ads.next();
  var adGroup = ad.getAdGroup();
  var campaign = ad.getCampaign();
  // Store (campaign, adGroup) to an array.
}

var campaigns = AdsApp.campaigns().get();
while (campaigns.hasNext()) {
  var adGroups = campaigns.next()
      .adGroups()
      .get();
  while (adGroups.hasNext()) {
    var ads = adGroups.ads()
       .withCondition('Clicks > 50')
       .forDateRange('LAST_MONTH')
       .get();
    if (ads.totalNumEntities() > 0) {
      // Store (campaign, adGroup) to an array.
    }
  }
}

Drugie podejście nie jest zalecane, ponieważ pobiera całą hierarchię kampanii i grup reklam na Twoim koncie, podczas gdy potrzebujesz tylko podzbioru kampanii i grup reklam powiązanych z Twoim zestawem reklam. Pierwsze podejście ogranicza się do pobierania tylko odpowiedniej kolekcji reklam i używa odpowiedniej metody, aby uzyskać dostęp do obiektów nadrzędnych.

Używanie konkretnych filtrów rodziców

Aby uzyskać dostęp do elementów w konkretnej kampanii lub grupie reklam, użyj w selektorze określonego filtra zamiast pobierać dane, a potem przechodzić przez hierarchię.

Porównaj poniższe fragmenty kodu, które pobierają listę reklam tekstowych w określonej kampanii i grupie reklam, które w zeszłym miesiącu uzyskały ponad 50 kliknięć.

var ads = AdsApp.ads()
    .withCondition('CampaignName = "Campaign 1"')
    .withCondition('AdGroupName = "AdGroup 1"')
    .withCondition('Clicks > 50')
    .forDateRange('LAST_MONTH')
    .get();

while (ads.hasNext()) {
  var ad = ads.next();
  var adGroup = ad.getAdGroup();
  var campaign = ad.getCampaign();
  // Store (campaign, adGroup, ad) to
  // an array.
}

var campaigns = AdsApp.campaigns()
    .withCondition('Name = "Campaign 1"')
    .get();

while (campaigns.hasNext()) {
  var adGroups = campaigns.next()
      .adGroups()
      .withCondition('Name = "AdGroup 1"')
      .get();
  while (adGroups.hasNext()) {
    var ads = adGroups.ads()
       .withCondition('Clicks > 50')
       .forDateRange('LAST_MONTH')
       .get();
    while (ads.hasNext()) {
      var ad = ads.next();
      // Store (campaign, adGroup, ad) to
      // an array.
    }
  }
}

Drugie podejście nie jest zalecane, ponieważ iteruje hierarchię kampanii i grup reklam na koncie, podczas gdy potrzebujesz tylko wybranego zestawu reklam oraz ich kampanii i grup reklam nadrzędnych. Pierwsze podejście ogranicza iterację do listy reklam przez zastosowanie w selektorze określonego filtra encji nadrzędnych.

W miarę możliwości używaj identyfikatorów do filtrowania.

Podczas filtrowania encji najlepiej jest filtrować je według identyfikatorów, a nie innych pól.

Zapoznaj się z tymi fragmentami kodu, które wybierają kampanię.

var campaign = AdsApp.campaigns()
    .withIds([12345])
    .get()
    .next();

var campaign = AdsApp.campaigns()
    .withCondition('Name="foo"')
    .get()
    .next();

Drugie podejście jest mniej optymalne, ponieważ filtrujemy według pola, które nie jest identyfikatorem.

W miarę możliwości filtruj według identyfikatorów rodzicielskich.

Podczas wybierania jednostki, jeśli to możliwe, filtruj według identyfikatorów nadrzędnych. Dzięki temu zapytania będą szybsze, ponieważ ograniczy to listę podmiotów pobieranych przez serwery podczas filtrowania wyników.

Rozważmy ten fragment kodu, który pobiera grupę reklam według jej identyfikatora. Załóżmy, że identyfikator kampanii nadrzędnej jest znany.

var adGroup = AdsApp.adGroups()
    .withIds([12345])
    .withCondition('CampaignId="54678"')
    .get()
    .next();

var adGroup = AdsApp.adGroups()
    .withIds([12345])
    .get()
    .next();

Chociaż oba fragmenty kodu dają identyczne wyniki, dodatkowe filtrowanie w fragmencie kodu 1 za pomocą identyfikatora nadrzędnego (CampaignId="54678") sprawia, że kod jest bardziej wydajny, ponieważ ogranicza listę elementów, po których serwer musi iterować podczas filtrowania wyników.

Używanie etykiet, gdy jest zbyt wiele warunków filtrowania

Jeśli masz zbyt wiele warunków filtrowania, warto utworzyć etykietę dla przetwarzanych elementów i użyć jej do filtrowania elementów.

Rozważ ten fragment kodu, który pobiera listę kampanii według ich nazwy.

var label = AdsApp.labels()
    .withCondition('Name = "My Label"')
    .get()
    .next();
var campaigns = label.campaigns.get();
while (campaigns.hasNext()) {
  var campaign = campaigns.next();
  // Do more work
}

var campaignNames = ['foo', 'bar', 'baz'];

for (var i = 0; i < campaignNames.length; i++) {
  campaignNames[i] = '"' + campaignNames[i] + '"';
}

var campaigns = AdsApp.campaigns
    .withCondition('CampaignName in [' + campaignNames.join(',') + ']')
    .get();

while (campaigns.hasNext()) {
  var campaign = campaigns.next();
  // Do more work.
}

Oba fragmenty kodu zapewniają podobny poziom wydajności, ale drugie podejście generuje bardziej złożony kod, gdy liczba warunków w selektorze wzrasta. Łatwiej jest też zastosować etykietę do nowego elementu niż edytować skrypt, aby uwzględnić nowy element.

Ogranicz liczbę warunków w klauzuli IN

Podczas uruchamiania skryptów często generuje się raport dla listy podmiotów. Deweloperzy zwykle robią to, tworząc bardzo długie zapytanie GAQL, które filtruje identyfikatory encji za pomocą klauzuli IN. To podejście sprawdza się, gdy liczba jednostek jest ograniczona. Jednak wraz ze wzrostem długości zapytania wydajność skryptu spada z 2 powodów:

• Dłuższe zapytanie wymaga więcej czasu na przeanalizowanie.
• Każdy identyfikator dodany do klauzuli IN jest dodatkowym warunkiem do oceny, co wydłuża czas przetwarzania.

W takich przypadkach lepiej jest zastosować etykietę do encji, a następnie filtrować według LabelId.

// The label applied to the entity is "Report Entities"
var label = AdsApp.labels()
    .withCondition('LabelName contains "Report Entities"')
    .get()
    .next();

var report = AdsApp.report('SELECT AdGroupId, Id, Clicks, ' +
    'Impressions, Cost FROM KEYWORDS_PERFORMANCE_REPORT ' +
    'WHERE LabelId = "' + label.getId() + '"');

var report = AdsApp.report('SELECT AdGroupId, Id, Clicks, ' +
    'Impressions, Cost FROM KEYWORDS_PERFORMANCE_REPORT WHERE ' +
    'AdGroupId IN (123, 456) and Id in (123,345, 456…)');

Informacje o koncie

Zmiany zbiorcze

Gdy wprowadzasz zmiany w elemencie Google Ads, skrypty Google Ads nie wykonują ich od razu. Zamiast tego próbuje połączyć wiele zmian w partie, aby móc wysłać jedno żądanie, które wprowadza wiele zmian. Dzięki temu skrypty działają szybciej i mniej obciążają serwery Google Ads. Istnieją jednak pewne wzorce kodu, które wymuszają na skryptach Google Ads częste czyszczenie partii operacji, co powoduje, że skrypt działa wolno.

Spójrz na ten skrypt, który aktualizuje stawki listy słów kluczowych.

var keywords = AdsApp.keywords()
    .withCondition('Clicks > 50')
    .withCondition('CampaignName = "Campaign 1"')
    .withCondition('AdGroupName = "AdGroup 1"')
    .forDateRange('LAST_MONTH')
    .get();

var list = [];
while (keywords.hasNext()) {
  var keyword = keywords.next();
  keyword.bidding().setCpc(1.5);
  list.push(keyword);
}

for (var i = 0; i < list.length; i++) {
  var keyword = list[i];
  Logger.log('%s, %s', keyword.getText(),
      keyword.bidding().getCpc());
}

var keywords = AdsApp.keywords()
    .withCondition('Clicks > 50')
    .withCondition('CampaignName = "Campaign 1"')
    .withCondition('AdGroupName = "AdGroup 1"')
    .forDateRange('LAST_MONTH')
    .get();

while (keywords.hasNext()) {
  var keyword = keywords.next();
  keyword.bidding().setCpc(1.5);
  Logger.log('%s, %s', keyword.getText(),
      keyword.bidding().getCpc());
}

Drugie podejście nie jest zalecane, ponieważ wywołanie keyword.bidding().getCpc() wymusza na skryptach Google Ads usunięcie operacji setCpc() i wykonanie tylko jednej operacji naraz. Pierwsze podejście, choć podobne do drugiego, ma dodatkową zaletę w postaci obsługi przetwarzania wsadowego, ponieważ wywołanie getCpc() odbywa się w osobnej pętli od wywołania setCpc().

W miarę możliwości używaj narzędzi do tworzenia.

Skrypty Google Ads obsługują 2 sposoby tworzenia nowych obiektów: kreatory i metody tworzenia. Kreatory są bardziej elastyczne niż metody tworzenia, ponieważ dają dostęp do obiektu utworzonego przez wywołanie interfejsu API.

Rozważmy te fragmenty kodu:

var operation = adGroup.newKeywordBuilder()
    .withText('shoes')
    .build();
var keyword = operation.getResult();

adGroup.createKeyword('shoes');
var keyword = adGroup.keywords()
    .withCondition('KeywordText="shoes"')
    .get()
    .next();

Drugie podejście nie jest zalecane ze względu na dodatkową operację wyboru wymaganą do pobrania słowa kluczowego. Dodatkowo wycofane zostały metody tworzenia.

Pamiętaj jednak, że konstruktory, jeśli są używane nieprawidłowo, mogą uniemożliwiać skryptom Google Ads wykonywanie operacji w pakietach.

Rozważ te fragmenty kodu, które tworzą listę słów kluczowych i wyświetlają identyfikatory nowo utworzonych słów kluczowych:

var keywords = ['foo', 'bar', 'baz'];

var list = [];
for (var i = 0; i < keywords.length; i++) {
  var operation = adGroup.newKeywordBuilder()
      .withText(keywords[i])
      .build();
  list.push(operation);
}

for (var i = 0; i < list.length; i++) {
  var operation = list[i];
  var result = operation.getResult();
  Logger.log('%s %s', result.getId(),
      result.getText());
}

var keywords = ['foo', 'bar', 'baz'];

for (var i = 0; i < keywords.length; i++) {
  var operation = adGroup.newKeywordBuilder()
      .withText(keywords[i])
      .build();
  var result = operation.getResult();
  Logger.log('%s %s', result.getId(),
      result.getText());
}

Drugie podejście nie jest zalecane, ponieważ wywołuje metodę operation.getResult() w tej samej pętli, która tworzy operację, co zmusza skrypty Google Ads do wykonywania operacji pojedynczo. Pierwsze podejście, choć podobne, umożliwia grupowanie, ponieważ wywołujemy metodę operation.getResult() w innej pętli niż ta, w której została utworzona.

W przypadku dużych aktualizacji rozważ użycie przesyłania zbiorczego

Częstym zadaniem deweloperów jest uruchamianie raportów i aktualizowanie właściwości obiektów (np. stawek za słowa kluczowe) na podstawie bieżących wartości skuteczności. Jeśli musisz zaktualizować dużą liczbę elementów, przesyłanie zbiorcze zwykle zapewnia lepszą wydajność. Przeanalizujmy na przykład te skrypty, które zwiększają maksymalny CPC słów kluczowych, których TopImpressionPercentage > 0.4 w ostatnim miesiącu:

var report = AdsApp.report(
  'SELECT AdGroupId, Id, CpcBid FROM KEYWORDS_PERFORMANCE_REPORT ' +
  'WHERE TopImpressionPercentage > 0.4 DURING LAST_MONTH');

var upload = AdsApp.bulkUploads().newCsvUpload([
  report.getColumnHeader('AdGroupId').getBulkUploadColumnName(),
  report.getColumnHeader('Id').getBulkUploadColumnName(),
  report.getColumnHeader('CpcBid').getBulkUploadColumnName()]);
upload.forCampaignManagement();

var reportRows = report.rows();
while (reportRows.hasNext()) {
  var row = reportRows.next();
  row['CpcBid'] = row['CpcBid'] + 0.02;
  upload.append(row.formatForUpload());
}

upload.apply();

var reportRows = AdsApp.report('SELECT AdGroupId, Id, CpcBid FROM ' +
    'KEYWORDS_PERFORMANCE_REPORT WHERE TopImpressionPercentage > 0.4 ' +
    ' DURING LAST_MONTH')
    .rows();

var map = {
};

while (reportRows.hasNext()) {
  var row = reportRows.next();
  var adGroupId = row['AdGroupId'];
  var id = row['Id'];

  if (map[adGroupId] == null) {
    map[adGroupId] = [];
  }
  map[adGroupId].push([adGroupId, id]);
}

for (var key in map) {
  var keywords = AdsApp.keywords()
      .withCondition('AdGroupId="' + key + '"')
      .withIds(map[key])
      .get();

  while (keywords.hasNext()) {
    var keyword = keywords.next();
    keyword.bidding().setCpc(keyword.bidding().getCpc() + 0.02);
  }
}

Drugie podejście zapewnia całkiem dobrą wydajność, ale w tym przypadku preferowane jest pierwsze, ponieważ

• Skrypty Google Ads mają limit liczby obiektów, które można pobrać lub zaktualizować w jednym przebiegu, a operacje wyboru i aktualizacji w drugim podejściu wliczają się do tego limitu.

• Przesyłanie zbiorcze ma wyższe limity zarówno pod względem liczby jednostek, które można zaktualizować, jak i ogólnego czasu wykonania.

Grupowanie przesyłania zbiorczego według kampanii

Podczas tworzenia arkuszy przesyłania zbiorczego staraj się grupować operacje według kampanii nadrzędnej. Zwiększa to wydajność i zmniejsza ryzyko wystąpienia konfliktów zmian lub błędów równoczesności.

Rozważmy 2 zadania przesyłania zbiorczego, które są wykonywane równolegle. Jedna wstrzymuje reklamy w grupie reklam, a druga dostosowuje stawki za słowa kluczowe. Nawet jeśli operacje nie są powiązane, mogą dotyczyć elementów w tej samej grupie reklam (lub w 2 różnych grupach reklam w tej samej kampanii). W takiej sytuacji system zablokuje encję nadrzędną (udostępnioną grupę reklam lub kampanię), co spowoduje, że zadania przesyłania zbiorczego będą się wzajemnie blokować.

Skrypty Google Ads mogą optymalizować wykonywanie w ramach pojedynczego zadania przesyłania zbiorczego, więc najprościej jest uruchamiać tylko jedno zadanie przesyłania zbiorczego na konto naraz. Jeśli zdecydujesz się na więcej niż jedno przesyłanie zbiorcze na konto, upewnij się, że przesyłanie zbiorcze działa na wzajemnie wykluczających się listach kampanii (i ich elementach podrzędnych), aby uzyskać optymalną skuteczność.

Raportowanie

Korzystanie z raportów do pobierania statystyk

Jeśli chcesz pobrać dużą liczbę obiektów i ich statystyk, często lepiej jest używać raportów niż standardowych metod AdsApp. Używanie raportów jest preferowane z tych powodów:

• Raporty zapewniają większą wydajność w przypadku dużych zapytań.
• Raporty nie będą podlegać normalnym limitom pobierania.

Porównaj te fragmenty kodu, które pobierają kliknięcia, wyświetlenia, koszt i tekst wszystkich słów kluczowych, które w zeszłym miesiącu uzyskały ponad 50 kliknięć:

  report = AdsApp.search(
      'SELECT ' +
      '   ad_group_criterion.keyword.text, ' +
      '   metrics.clicks, ' +
      '   metrics.cost_micros, ' +
      '   metrics.impressions ' +
      'FROM ' +
      '   keyword_view ' +
      'WHERE ' +
      '   segments.date DURING LAST_MONTH ' +
      '   AND metrics.clicks > 50');
  while (report.hasNext()) {
    var row = report.next();
    Logger.log('Keyword: %s Impressions: %s ' +
        'Clicks: %s Cost: %s',
        row.adGroupCriterion.keyword.text,
        row.metrics.impressions,
        row.metrics.clicks,
        row.metrics.cost);
  }

var keywords = AdsApp.keywords()
    .withCondition('metrics.clicks > 50')
    .forDateRange('LAST_MONTH')
    .get();
while (keywords.hasNext()) {
  var keyword = keywords.next();
  var stats = keyword.getStatsFor('LAST_MONTH');
  Logger.log('Keyword: %s Impressions: %s ' +
      'Clicks: %s Cost: %s',
      keyword.getText(),
      stats.getImpressions(),
      stats.getClicks(),
      stats.getCost());
}

Drugie podejście nie jest zalecane, ponieważ iteruje po słowach kluczowych i pobiera statystyki po jednym elemencie naraz. W tym przypadku raporty działają szybciej, ponieważ pobierają wszystkie dane w ramach jednego wywołania i przesyłają je strumieniowo w miarę potrzeb. Dodatkowo słowa kluczowe pobrane w drugi sposób są wliczane do limitu skryptu dotyczącego liczby elementów pobranych za pomocą wywołania get().

Używanie wyszukiwarki zamiast raportu

Metoda raportowania została utworzona na potrzeby starej infrastruktury i będzie zwracać wyniki w formacie płaskim, nawet jeśli używasz GAQL. Oznacza to, że musi przekształcić wyniki zapytania, aby pasowały do starego stylu, co nie jest obsługiwane w przypadku wszystkich pól i zwiększa obciążenie każdego wywołania.

Zalecamy używanie wyszukiwania, aby korzystać ze wszystkich funkcji raportowania w nowym interfejsie Google Ads API.

Preferowanie GAQL zamiast AWQL

Chociaż AWQL nadal działa w przypadku zapytań dotyczących raportów i wywołań withCondition, nie zalecamy korzystania z tego języka. Aby mieć pełną kontrolę nad zapytaniami, używaj GAQL.

Nie wybieraj więcej wierszy niż potrzebujesz

Szybkość wykonywania raportów (i selektorów) zależy od łącznej liczby wierszy, które raport zwróci, niezależnie od tego, czy będziesz je przeglądać. Oznacza to, że zawsze należy używać konkretnych filtrów, aby jak najbardziej ograniczyć zbiór wyników do przypadku użycia.

Załóżmy na przykład, że chcesz znaleźć grupy reklam ze stawkami spoza określonego zakresu. Szybsze będzie utworzenie 2 osobnych zapytań – jednego dla stawek poniżej dolnego progu i drugiego dla stawek powyżej górnego progu – niż pobranie wszystkich grup reklam i zignorowanie tych, które Cię nie interesują.

var adGroups = []
var report = AdsApp.search(
    'SELECT ad_group.name, ad_group.cpc_bid_micros' +
    ' FROM ad_group WHERE ad_group.cpc_bid_micros < 1000000');

while (report.hasNext()) {
  var row = report.next();
  adGroups.push(row.adGroup);
}
var report = AdsApp.search(
    'SELECT ad_group.name, ad_group.cpc_bid_micros' +
    ' FROM ad_group WHERE ad_group.cpc_bid_micros > 2000000');

while (report.hasNext()) {
  var row = report.next();
  adGroups.push(row.adGroup);
}

var adGroups = []
var report = AdsApp.search(
    'SELECT ad_group.name, ad_group.cpc_bid_micros' +
    ' FROM ad_group');

while (report.hasNext()) {
  var row = report.next();
  var cpcBidMicros = row.adGroup.cpcBidMicros;
  if (cpcBidMicros < 1000000 || cpcBidMicros > 2000000) {
    adGroups.push(row.adGroup);
  }
}

Skrypty konta menedżera Google Ads (MCK)

Preferuj executeInParallel zamiast wykonywania szeregowego

Podczas pisania skryptów dla kont menedżera używaj w miarę możliwości executeInParallel() zamiast wykonywania szeregowego. executeInParallel() daje skryptowi więcej czasu na przetwarzanie (do 1 godziny) i do 30 minut na każde przetwarzane konto (zamiast 30 minut łącznie w przypadku wykonywania szeregowego). Więcej informacji znajdziesz na stronie z limitami.

Arkusze kalkulacyjne

Używanie operacji wsadowych podczas aktualizowania arkuszy kalkulacyjnych

Podczas aktualizowania arkuszy kalkulacyjnych staraj się używać metod operacji zbiorczych (np. getRange()) zamiast metod, które aktualizują po jednej komórce.

Spójrz na ten fragment kodu, który generuje fraktalny wzór w arkuszu kalkulacyjnym.

var colors = new Array(100);
for (var y = 0; y < 100; y++) {
  xcoord = xmin;
  colors[y] = new Array(100);
  for (var x = 0; x < 100; x++) {
    colors[y][x] = getColor_(xcoord, ycoord);
    xcoord += xincrement;
  }
  ycoord -= yincrement;
}
sheet.getRange(1, 1, 100, 100).setBackgroundColors(colors);

var cell = sheet.getRange('a1');
for (var y = 0; y < 100; y++) {
  xcoord = xmin;
  for (var x = 0; x < 100; x++) {
    var c = getColor_(xcoord, ycoord);
    cell.offset(y, x).setBackgroundColor(c);
    xcoord += xincrement;
  }
  ycoord -= yincrement;
  SpreadsheetApp.flush();
}

Chociaż Arkusze Google próbują zoptymalizować drugi fragment kodu przez buforowanie wartości, nadal działa on gorzej niż pierwszy fragment kodu ze względu na liczbę wywołań interfejsu API.