Zmień

Skrypty Google Ads obsługują mutacje ogólne dostępne w interfejsie Google Ads API. Większość operacji, które można wykonywać w narzędziu GoogleAdsService.mutate, można też wykonywać w skryptach Google Ads, m.in. tworzyć kampanie i nimi zarządzać.

Ponieważ ta funkcja umożliwia dostęp do tak dużej części interfejsu Google Ads API, należy znać podstawowe konwencje tego interfejsu. Możesz pominąć wiele aspektów, np. tokeny programisty i autoryzacja, ponieważ są one obsługiwane przez skrypty Google Ads, ale musisz przesłać prawidłowe żądanie zmiany.

Oto podstawowe materiały o interfejsie API REST Google Ads, z którymi musisz zapoznać się przed przejściem do dalszej części tego przewodnika:

Podstawowy przykład

Aby zademonstrować tę funkcję, spójrzmy na podstawowy przykład, jak utworzyć budżet kampanii:

const budgetResult = AdsApp.mutate({
    campaignBudgetOperation: {
      create: {
        amountMicros: 10000000,
        explicitlyShared: false
      }
    }
  });

Wywołanie AdsApp.mutate przyjmuje obiekt JSON reprezentujący pojedynczy MutateOperation. Określasz w nim rodzaj operacji, którą wykonujesz – w tym przypadku campaignBudgetOperation. Następnie możesz określić create, remove lub obie te wartości (update i updateMask). Konkretne pola w create i update zależą od typu zasobu, na którym pracujesz.

Tworzenie operacji

Istnieje kilka strategii, których możesz użyć do utworzenia prawidłowej operacji. Powracając do przykładu budżetu kampanii, możesz wyszukać w dokumentacji referencyjnej REST budżet kampanii listę wszystkich prawidłowych pól, a następnie wypełnić odpowiednie pola lub wpisać w skrypcie niestandardowy kod JavaScript, aby utworzyć odpowiedni obiekt.

Możesz też spróbować dynamicznie utworzyć operację, korzystając z funkcji „Wypróbuj” przy budżecie kampanii, która umożliwia dynamiczne tworzenie treści żądania poprzez wybieranie pól, które chcesz dodać. Następnie możesz wyodrębnić zawartość operacji z wygenerowanego wyniku i dodać ją do wywołania mutate po określeniu typu operacji.

Typy operacji

Utwórz

W swojej operacji określ create, przekazując ponownie obiekt do reprezentacji zasobu, który chcesz utworzyć.

Powyżej znajdziesz przykład operacji create.

Usuń

W operacji podaj remove, podając nazwę zasobu zasobu, który chcesz usunąć, na przykład:

AdsApp.mutate({
    adGroupOperation: {
        remove: "customers/[CUSTOMER_ID]/adGroups/[AD_GROUP_ID]"
    }
});

Jeśli nie znasz nazwy zasobu encji, możesz ją pobrać przy użyciu żądania Adsapp.search.

Aktualizuj

Określ update w operacji, przekazując obiekt o określonej nazwie zasobu, aby system mógł określić, który obiekt chcesz zaktualizować. Wypełnij też pola, w których chcesz zaktualizować wartości, i określ pole updateMask, które wskaże dokładnie, które pola chcesz zmienić w tym żądaniu. Nie umieszczaj nazwy zasobu w masce aktualizacji.

Przykład operacji update:

const campaignResult = AdsApp.mutate({
    campaignOperation: {
        update: {
            resourceName: "customers/[CUSTOMER_ID]/campaigns/[CAMPAIGN_ID]",
            status: "PAUSED",
            name: "[Paused] My campaign"
        },
        updateMask: "name,status"
    }
});

Obsługa wyników

Niezależnie od typu operacji zwracaną wartością jest MutateResult. Zwróconej nazwy zasobu możesz użyć, aby przesłać zapytanie o bieżący stan zasobu po zmianie i sprawdzić, czy operacja zakończyła się powodzeniem, a także jakie błędy wystąpiły.

Oto przykład podstawowego procesu sprawdzania wyniku i drukowania niektórych informacji w dziennikach:

const result = AdsApp.mutate( ... );
if (result.isSuccessful()) {
    console.log(`Resource ${result.getResourceName()} successfully mutated.`);
} else {
    console.log("Errors encountered:");
    for (const error of result.getErrorMessages()) {
        console.log(error);
    }
}

Wiele operacji

Skrypty Google Ads obsługują też mutację wielu operacji w pojedynczym żądaniu za pomocą metody AdsApp.mutateAll. W jednym żądaniu możesz tworzyć zależne od siebie elementy, np. pełną hierarchię kampanii. Opcjonalnie możesz ustawić cały zestaw działań jako niepodzielny, więc jeśli któraś z nich się nie powiedzie, nie będzie ona wykonywana.

Zwracana wartość to tablica obiektów MutateResult, po jednym na każdą podaną operację, w tej samej kolejności co operacje początkowe.

Ta funkcja działa tak samo jak interfejs Google Ads API, więc zapoznaj się ze sprawdzonymi metodami korzystania z interfejsu Google Ads API, aby poznać pełne informacje o identyfikatorach tymczasowych i innych kwestiach. Pamiętaj, że w przewodniku nazwy pól są przedstawiane za pomocą parametru snake_case, a w dokumentacji skryptów Google Ads – lowerCamelCase. Oba te przypadki są akceptowane w skryptach Google Ads, więc możesz skopiować kod bezpośrednio z tego przewodnika.

Aby wykonać wiele operacji w jednym żądaniu, zbierz wszystkie operacje w tablicy, a następnie wywołaj AdsApp.mutateAll. Wywołanie mutateAll przyjmuje tablicę operacji jako pierwszy argument i opcjonalny drugi argument opcji, w tym:

  • apiVersion: jeśli chcesz użyć innej wersji niż domyślna, możesz określić niestandardową wersję interfejsu API, np. V16. W takiej sytuacji możesz użyć dowolnej publicznie dostępnej wersji.
  • partialFailure: to pole przyjmuje domyślnie wartość true. Jeśli ma wartość true, wykonywane są prawidłowe operacje, a nieudane – zwracają błędy. Jeśli zasada ma wartość false, w przypadku niepowodzenia jakiejkolwiek operacji nie są wykonywane żadne operacje, co w efekcie sprawi, że zbiór operacji będzie nieistotny.

Oto przykład z wieloma operacjami, który tworzy budżet kampanii, kampanię i grupę reklam w niepodzielnym żądaniu.

const operations = [];
const customerId = 'INSERT_CUSTOMER_ID_HERE';
const budgetId = `customers/${customerId}/campaignBudgets/-1`;
const campaignId = `customers/${customerId}/campaigns/-2`;
operations.push({
    campaignBudgetOperation: {
      create: {
        resourceName: budgetId,
        amountMicros: 10000000,
        explicitlyShared: false
      }
    }
  });
operations.push({
    campaignOperation: {
      create: {
        resourceName: campaignId,
        name: 'New Campaign ' + new Date(),
        advertisingChannelType: 'SEARCH',
        manualCpc: {},
        campaignBudget: budgetId,
        advertisingChannelType: 'DISPLAY',
        networkSettings: {
          targetContentNetwork: true
        }
      }
    }
  });
operations.push({
    adGroupOperation: {
      create: {
        campaign: campaignId,
        name: 'New AdGroup ' + new Date(),
        optimizedTargetingEnabled: true
      }
    }
  });
const results = AdsApp.mutateAll(
    operations, {partialFailure: false});