Skrypty Google Ads obsługują ogólne modyfikacje dostępne w interfejsie Google Ads API. Większość operacji, które można wykonywać za pomocą GoogleAdsService.mutate, można też wykonywać w scenariach Google Ads, m.in. tworzyć kampanie i nimi zarządzać.
Ponieważ ta funkcja umożliwia dostęp do dużej części interfejsu Google Ads API, aby z niej korzystać, musisz mieć podstawową znajomość konwencji interfejsu Google Ads API. Możesz pominąć wiele aspektów, np. tokeny dewelopera i autoryzację, ponieważ są one obsługiwane przez skrypty Google Ads, ale musisz utworzyć prawidłowe żądanie zmiany.
Zanim przejdziesz do dalszej części tego przewodnika, zapoznaj się z podstawowymi materiałami na temat interfejsu Google Ads API REST:
Przykład podstawowy
Aby pokazać działanie tej funkcji, rozważ ten podstawowy przykład, w którym tworzony jest budżet kampanii:
const budgetResult = AdsApp.mutate({
campaignBudgetOperation: {
create: {
amountMicros: 10000000,
explicitlyShared: false
}
}
});
Wywołanie funkcji
AdsApp.mutate
przekazuje obiekt JSON reprezentujący pojedynczy element
MutateOperation. W tym obiekcie określasz, jakiego rodzaju operację wykonujesz – w tym przypadku campaignBudgetOperation. Następnie określ create, remove lub oba atrybuty update i updateMask. Konkretne pola w elementach create i update zależą od typu zasobu, z którym pracujesz.
Tworzenie operacji
Aby utworzyć prawidłową operację, możesz zastosować kilka strategii. W przypadku budżetu kampanii możesz zajrzeć do dokumentacji interfejsu REST na temat budżetu kampanii, aby zobaczyć listę wszystkich prawidłowych pól, a potem wypełnić odpowiednie pola lub napisać niestandardowy kod JavaScript w swoim skrypcie, aby utworzyć odpowiedni obiekt.
Możesz też spróbować utworzyć operację dynamicznie, korzystając z funkcji „Wypróbuj to” w przypadku budżetu kampanii, która umożliwia dynamiczne tworzenie treści żądania przez wybieranie i dodawanie pól.
Następnie możesz wyodrębnić zawartość operacji z wygenerowanego wyniku i dodać ją do wywołania funkcji mutate po określeniu typu operacji.
Typy operacji
Utwórz
W operacji podaj wartość create, przekazując obiekt reprezentujący zasób, który chcesz utworzyć.
Przykład operacji create znajdziesz powyżej.
Usuń
W operacji określ wartość remove, podając nazwa 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 danego elementu, możesz ją pobrać za pomocą żądania Adsapp.search.
Aktualizuj
W operacji podaj update, przekazując obiekt z określoną nazwą zasobu, aby system mógł określić, który obiekt chcesz zaktualizować. Dodatkowo wypełnij pola, których wartości chcesz zmienić, i określ updateMask, aby wskazać dokładnie, które pola chcesz zmienić w tym żądaniu. Nie dodawaj nazwy zasobu do maski 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 zwracana jest wartość MutateResult.
Za pomocą zwróconej nazwy zasobu możesz wysłać zapytanie o obecny stan zasobu po zmianie i sprawdzić, czy operacja zakończyła się pomyślnie lub jakie błędy wystąpiły.
Oto przykład podstawowych czynności sprawdzania wyniku i wyświetlania 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ż mutowanie wielu operacji w jednym żądaniu za pomocą metody AdsApp.mutateAll. Możesz tworzyć elementy, które są od siebie zależne, np. pełną hierarchię kampanii w jednym żądaniu. Opcjonalnie możesz ustawić, aby cały zestaw operacji był atomowy, co oznacza, że jeśli jedna z operacji się nie powiedzie, żadne z nich nie zostaną wykonane.
Zwracana wartość to tablica obiektów MutateResult, po jednym dla każdej podanej operacji i w tej samej kolejności co operacje początkowe.
Ta funkcja działa tak samo jak funkcja Google Ads API, więc pełne informacje o tym, jak korzystać z tymczasowych identyfikatorów i innych kwestii, znajdziesz w przewodniku Zalecane metody postępowania dotyczące interfejsu Google Ads API. Pamiętaj, że w tym przewodniku do reprezentowania nazw pól używa się symbolu snake_case, a w dokumentacji dotyczącej skryptów Google Ads – symbolu lowerCamelCase. Oba te przypadki są akceptowane w scenariach 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 potem wywołaj funkcję AdsApp.mutateAll. Wywołanie funkcji mutateAll przyjmuje tablicę operacji jako pierwszy argument i opcjonalny drugi argument opcji, w tym:
apiVersion: jeśli chcesz użyć wersji innej niż domyślna w skryptach, możesz podać niestandardową wersję interfejsu API, np.V19. Możesz korzystać z dowolnej wersji dostępnej publicznie.partialFailure: to pole ma domyślnie wartośćtrue. Jeśli opcjatruema wartośćtrue, wykonywane są prawidłowe operacje, a nieudane zwracają błędy. Jeśli ustawisz wartośćfalse, w przypadku niepowodzenia dowolnej operacji nie zostaną wykonane żadne operacje, co spowoduje, że ten zestaw operacji będzie atomowy.
Oto przykład, w którym w ramach jednej atomowej prośby wykonywane są liczne operacje, które tworzą budżet kampanii, kampanię i grupę reklam.
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});