Zmień

Skrypty Google Ads obsługują ogólne operacje mutate dostępne w interfejsie Google Ads API. Większość operacji, które można wykonać za pomocą GoogleAdsService.mutate, można też wykonać w skryptach Google Ads, w tym tworzenie kampanii i zarządzanie nimi.

Ta funkcja umożliwia dostęp do tak dużej części interfejsu Google Ads API, że aby z niej korzystać, musisz mieć podstawową wiedzę o konwencjach interfejsu Google Ads API. Możesz pominąć wiele aspektów, takich jak tokeny dewelopera i autoryzacja, ponieważ są one obsługiwane przez skrypty Google Ads, ale musisz utworzyć prawidłowe żądanie mutate.

Zanim przejdziesz dalej, zapoznaj się z tymi podstawowymi materiałami na temat interfejsu REST interfejsu Google Ads API:

Podstawowy przykład

Aby zademonstrować tę funkcję, rozważ ten podstawowy przykład, który tworzy budżet kampanii:

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

Wywołanie funkcji AdsApp.mutate przyjmuje obiekt JSON, który reprezentuje pojedynczą operację MutateOperation. W tym obiekcie określasz, jaki rodzaj operacji wykonujesz – w tym przypadku jest to campaignBudgetOperation. Następnie określasz create, remove lub oba te elementy: update i updateMask. Konkretne pola w obrębie create i update zależą od konkretnego typu zasobu, na którym działasz.

Tworzenie operacji

Istnieje kilka strategii, których możesz użyć do utworzenia prawidłowej operacji. W przypadku budżetu kampanii możesz wyszukać dokumentację referencyjną REST dotyczącą budżetu kampanii, aby zobaczyć listę wszystkich prawidłowych pól, a następnie wypełnić odpowiednie pola lub napisać niestandardowy kod JavaScript w skrypcie, aby utworzyć odpowiedni obiekt.

Możesz też spróbować utworzyć operację dynamicznie za pomocą funkcji „Wypróbuj” w przypadku budżetu kampanii, która umożliwia dynamiczne tworzenie treści żądania przez 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 operacji określ create, przekazując reprezentację obiektu zasobu, który chcesz utworzyć.

Przykład operacji create znajdziesz we fragmencie kodu podanym wcześniej.

Usuń

W operacji określ remove, przekazują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ć za pomocą żądania Adsapp.search.

Aktualizuj

W operacji określ update, przekazując obiekt z określoną nazwą zasobu, aby system mógł określić, który obiekt chcesz zaktualizować. Dodatkowo wypełnij wszystkie pola, których wartości chcesz zaktualizować, i określ updateMask, który wskazuje dokładnie, które pola planujesz zmienić w tym żądaniu. Nie uwzględniaj 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 zwracana wartość to MutateResult. Możesz użyć zwróconej nazwy zasobu, aby wysłać zapytanie o bieżący stan zasobu po operacji mutate i sprawdzić, czy operacja się powiodła, czy też wystąpiły jakieś błędy.

Oto przykład przedstawiający podstawowy proces 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ż operacje mutate w ramach jednego żądania za pomocą metody AdsApp.mutateAll. Możesz tworzyć encje, które są od siebie zależne, np. całą hierarchię kampanii w jednym żądaniu. Opcjonalnie możesz ustawić, aby cały zestaw operacji był niepodzielny. Jeśli któraś z nich się nie powiedzie, żadna z nich nie zostanie wykonana.

Wartość zwracana to tablica obiektów MutateResult , po jednym dla każdej operacji, którą podajesz, i w tej samej kolejności co operacje początkowe.

Ta funkcja działa tak samo jak funkcja interfejsu Google Ads API, więc aby uzyskać pełne wyjaśnienie tymczasowych identyfikatorów i innych kwestii, zapoznaj się z przewodnikiem po sprawdzonych metodach interfejsu Google Ads API. Pamiętaj, że w przewodniku nazwy pól są zapisywane w formacie snake_case, a w dokumentacji skryptów Google Ads – w formacie lowerCamelCase. Oba te formaty są akceptowane w skryptach Google Ads, więc możesz kopiować kod bezpośrednio z tego przewodnika.

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

  • apiVersion: możesz określić niestandardową wersję interfejsu API, np. V25, jeśli chcesz użyć innej wersji niż domyślna wersja skryptów. Możesz użyć dowolnej publicznie dostępnej wersji.
  • partialFailure: to pole domyślnie ma wartość true. Jeśli ma wartość true, wykonywane są prawidłowe operacje, a operacje, które się nie powiodły, zwracają błędy. Jeśli ma wartość false, a któraś z operacji się nie powiedzie, żadna z nich nie zostanie wykonana, co sprawi, że ten zestaw operacji będzie niepodzielny.

Oto przykład z kilkoma operacjami, który tworzy budżet kampanii, kampanię i grupę reklam w ramach niepodzielnego żądania.

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});