Zmień

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

Ta funkcja umożliwia dostęp do tak dużej części interfejsu Google Ads API, dlatego musisz znać podstawowe konwencje dotyczące interfejsu Google Ads API, aby z niej korzystać. 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.

Oto kilka podstawowych materiałów o interfejsie REST interfejsu Google Ads API, które warto znać, zanim przejdziesz do dalszej części tego przewodnika:

• Projektowanie interfejsu REST
• Nazwy zasobów
• Mapowania danych w formacie JSON
• Mutate

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 obrębie tego obiektu możesz określić rodzaj wykonywanej operacji – w tym przypadku jest to campaignBudgetOperation. Następnie określ create, remove lub oba atrybuty update i updateMask. Konkretne pola w obrębie create i update zależą od typu zasobu, z którego korzystasz.

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 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ślonym zasobem, aby system mógł określić, który obiekt chcesz zaktualizować. Dodatkowo wypełnij pola, których wartości chcesz zaktualizować, i określ parametr updateMask, który wskazuje, 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

Bez względu na typ operacji zwracaną wartością jest MutateResult. Za pomocą zwróconej nazwy zasobu możesz sprawdzić bieżący stan zasobu po zmianie i sprawdzić, czy operacja zakończyła się pomyślnie lub jakie błędy wystąpiły.

Oto przykład podstawowego procesu sprawdzania wyniku i drukowania informacji w logach:

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 – 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 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. V18. Możesz korzystać z dowolnej wersji dostępnej publicznie.
• partialFailure: to pole ma domyślnie wartość true. Jeśli opcja true ma wartość true, wykonywane są prawidłowe operacje, a nieudane zwracają błędy. Jeśli zasada ma wartość false, to jeśli jakaś operacja się nie powiedzie, nie są wykonywane żadne operacje, co w efekcie powoduje, że zbiór operacji jest niepodzielny.

Oto przykład z kilkoma operacjami, które w jednym żądaniu atomowym 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});