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 wysyłać prośby tylko o potrzebne Ci elementy. Stosowanie odpowiednich filtrów przynosi te korzyści:

• 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.

Unikanie 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. Oprócz tego, że będzie to prostsze, będzie też działać znacznie lepiej: system nie będzie musiał niepotrzebnie odczytywać 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), podczas gdy wymagane są tylko reklamy.

Używanie konkretnych metod dostępu rodzica

Czasami musisz uzyskać jednostkę nadrzędną pobranego obiektu. W takim przypadku zamiast pobierać całe hierarchie, użyj udostępnionej metody dostępu.

Porównaj te fragmenty kodu, które pobierają grupy reklam zawierające reklamy tekstowe z ponad 50 kliknięciami w ostatnim 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 koncie, a potrzebny jest tylko podzbiór kampanii i grup reklam powiązanych z zestawem reklam. Pierwsze podejście ogranicza się do pobierania tylko odpowiedniej kolekcji reklam i używa odpowiedniej metody dostępu do jej obiektów nadrzędnych.

Używanie konkretnych filtrów nadrzędnych

Aby uzyskać dostęp do elementów w określonej kampanii lub grupie reklam, użyj w selektorze konkretnego 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 ostatnim 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, a potrzebny jest tylko wybrany zestaw reklam oraz ich kampanie i grupy reklam nadrzędne. Pierwsze podejście ogranicza iterację do listy reklam, stosując w selektorze określony filtr dla jednostek nadrzędnych.

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

Podczas filtrowania encji lepiej jest filtrować je według identyfikatorów niż według 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 innego niż identyfikator.

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

Podczas wybierania encji filtruj według identyfikatorów nadrzędnych, jeśli to możliwe. Dzięki temu zapytania będą szybsze, ponieważ podczas filtrowania wyników serwery będą pobierać tylko ograniczoną listę elementó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") zwiększa wydajność kodu, ograniczając listę jednostek, po których serwer musi iterować podczas filtrowania wyników.

Używaj 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 tych elementów.

Oto fragment kodu, który pobiera listę kampanii według ich nazw.

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 skuteczności, ale drugie podejście zwykle generuje bardziej złożony kod, ponieważ liczba warunków w selektorze rośnie. Łatwiej jest też zastosować etykietę do nowego elementu niż edytować skrypt, aby go uwzględnić.

Ogranicz liczbę warunków w klauzuli IN

Podczas uruchamiania skryptów często zdarza się, że trzeba wygenerować raport dla listy podmiotów. Deweloperzy zwykle osiągają to, tworząc bardzo długie zapytanie AWQL, 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 skuteczność skryptu spada z 2 powodów:

• Dłuższe zapytanie wymaga dłuższego czasu analizowania.
• Każdy identyfikator dodany do klauzuli IN to dodatkowy warunek do oceny, a więc wydłuża czas przetwarzania.

W takich przypadkach lepiej jest zastosować etykietę do elementów, 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 wprowadzisz zmiany w elemencie Google Ads, skrypty Google Ads nie wykonają ich od razu. Zamiast tego próbuje łączyć wiele zmian w pakiety, aby wysyłać jedno żądanie, które wprowadza wiele zmian. Dzięki temu skrypty działają szybciej i zmniejsza się obciążenie serwerów Google Ads. Istnieją jednak pewne wzorce kodu, które wymuszają częste opróżnianie przez skrypty Google Ads partii operacji, co powoduje powolne działanie skryptu.

Rozważmy ten skrypt, który aktualizuje stawki na liście 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 opróżnienie setCpc() i wykonywanie 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 tej, w której wywoływane jest setCpc().

W miarę możliwości używaj monterów

Skrypty Google Ads obsługują 2 sposoby tworzenia nowych obiektów: konstruktory i metody tworzenia. Konstruktory są bardziej elastyczne niż metody tworzenia, ponieważ zapewniają dostęp do obiektu utworzonego na podstawie wywołania interfejsu API.

Przyjrzyj się tym fragmentom 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 metody tworzenia są też wycofywane.

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

Rozważ poniższe 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 operation.getResult()w tej samej pętli, która tworzy operację, co zmusza skrypty Google Ads do wykonywania jednej operacji naraz. Pierwsze podejście, choć podobne, umożliwia przetwarzanie wsadowe, ponieważ wywołujemy operation.getResult() w innej pętli niż ta, w której zostało utworzone.

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

Częstym zadaniem deweloperów jest generowanie 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ść. Przyjrzyjmy się na przykład tym skryptom, które zwiększają maksymalną stawkę 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);
  }
}

Chociaż drugie podejście zapewnia dość dobrą wydajność, w tym przypadku preferowane jest pierwsze, ponieważ

• Skrypty Google Ads mają limit liczby obiektów, które można pobrać lub zaktualizować w jednym uruchomieniu, 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łanych zbiorczo plików według kampanii

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

Rozważ 2 zadania przesyłania zbiorczego uruchomione równolegle. Jedna z nich wstrzymuje reklamy w grupie reklam, a druga dostosowuje stawki za słowa kluczowe. Mimo że operacje nie są ze sobą 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 jednostkę nadrzędną (wspólną grupę reklam lub kampanię), co spowoduje wzajemne blokowanie się zadań przesyłania zbiorczego.

Skrypty Google Ads mogą optymalizować wykonywanie w ramach jednego zadania przesyłania zbiorczego, więc najprostszym rozwiązaniem jest uruchamianie tylko jednego zadania przesyłania zbiorczego na konto w danym momencie. Jeśli zdecydujesz się przeprowadzić więcej niż 1 przesyłanie zbiorcze na konto, zadbaj o to, aby przesłane zbiorczo kampanie (i ich elementy podrzędne) były wzajemnie wykluczające się, co zapewni optymalną skuteczność.

Raportowanie

Korzystanie z raportów do pobierania statystyk

Jeśli chcesz pobrać dużą liczbę jednostek i ich statystyk, często lepiej jest używać raportów niż standardowych metod AdsApp. Korzystanie z 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 preferowane, 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 opracowana z myślą o starej infrastrukturze 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

AWQL jest nadal obsługiwany w zapytaniach do raportów i wywołaniach withCondition, ale jest uruchamiany za pomocą warstwy tłumaczenia, która nie jest w pełni zgodna z prawdziwym AWQL. Aby mieć pełną kontrolę nad zapytaniami, używaj GAQL.

Jeśli masz zapytania AWQL, które chcesz przetłumaczyć, skorzystaj z narzędzia do migracji zapytań.

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ć zestaw wyników i dopasować go do swojego przypadku użycia.

Załóżmy, że chcesz znaleźć grupy reklam ze stawkami wykraczającymi poza określony zakres. Szybsze będzie wykonanie 2 osobnych zapytań – jednego o stawki poniżej dolnego progu, a drugiego o stawki 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

Preferowanie wykonywania równoległego zamiast szeregowego

Podczas pisania skryptów na konta menedżera, jeśli to możliwe, używaj zamiast wykonywania seryjnego funkcji executeInParallel(). executeInParallel() daje skryptowi więcej czasu na przetwarzanie (do godziny) i do 30 minut na przetworzone konto (zamiast 30 minut łącznie w przypadku wykonywania szeregowego). Więcej informacji znajdziesz na stronie z limitami.

Arkusze kalkulacyjne

Używanie operacji zbiorczych 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.

Rozważmy ten fragment kodu, który generuje wzór fraktalny 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();
}

Arkusz Google próbuje zoptymalizować drugi fragment kodu, zapisując wartości w pamięci podręcznej, ale nadal działa wolniej niż pierwszy fragment ze względu na liczbę wywołań interfejsu API.