Method: customers.googleAds.mutate

tworzy, aktualizuje i usuwa zasoby; Ta metoda obsługuje transakcje atomowe z wieloma typami zasobów. Możesz na przykład tworzyć kampanie i budżety kampanii w ramach atomu lub przeprowadzać do tysięcy mutacji w ramach atomu.

Ta metoda jest w podstawie obudową serii metod mutacji. Jedynymi funkcjami, które oferuje w porównaniu z wywoływaniem tych metod bezpośrednio, są:

  • Transakcje atomowe
  • Nazwa tymczasowego zasobu (opisana poniżej)
  • Nieco mniejsze opóźnienie podczas wykonywania serii wywołań metody mutate

Uwaga: uwzględniane są tylko zasoby obsługujące transakcje atomowe, więc ta metoda nie może zastąpić wszystkich wywołań poszczególnych usług.

Zalety transakcji atomowych

Atomiczność znacznie ułatwia obsługę błędów. Jeśli wprowadzasz serię zmian, a jedna z nich się nie powiedzie, może to spowodować niespójny stan konta. Dzięki temu albo osiągniesz wybrany stan bezpośrednio, albo żądanie się nie powiedzie i będzie można spróbować ponownie.

Nazwy tymczasowych zasobów

Nazwa tymczasowego zasobu to specjalny typ nazwy zasobu używany do tworzenia zasobu i odwoływania się do niego w tym samym żądaniu. Jeśli np. utworzysz budżet kampanii z wartością parametru resourceName równą customers/123/campaignBudgets/-1, tej nazwy zasobu można użyć ponownie w polu Campaign.budget w tej samej prośbie. W ten sposób oba zasoby są tworzone i połączone w ramach jednej operacji.

Aby utworzyć tymczasową nazwę zasobu, w części nazwy, którą serwer normalnie przydzieli, wpisz liczbę ujemną.

Uwaga:

  • Zasoby muszą zostać utworzone z tymczasową nazwą, zanim będzie można jej użyć ponownie. Na przykład poprzedni przykład kodu CampaignBudget+Campaign nie zadziałałby, gdyby kolejność operacji została odwrócona.
  • Nazwy tymczasowe nie są zapamiętywane w przypadku kolejnych żądań.
  • Nie ma limitu liczby nazw tymczasowych w żądaniu.
  • Każda tymczasowa nazwa musi zawierać unikalną liczbę ujemną, nawet jeśli typy zasobów się różnią.

Czas oczekiwania

Należy grupować operacje zmiany według typu zasobu, ponieważ w przeciwnym razie żądanie może przekroczyć limit czasu i nie zostać zrealizowane. Czas oczekiwania jest w przybliżeniu równy serii wywołań poszczególnych metod mutacji, gdzie każda zmiana typu zasobu jest nowym wywołaniem. Na przykład zmutowanie 10 kampanii, a potem 10 grup reklam to 2 wywołania, a zmutowanie 1 kampanii, 1 grupy reklam, 1 kampanii i 1 grupy reklam to 4 wywołania.

Lista błędów: AdCustomizerError AdError AdGroupAdError AdGroupCriterionError AdGroupError AssetError AuthenticationError AuthorizationError BiddingError CampaignBudgetError CampaignCriterionError CampaignError CampaignExperimentError CampaignSharedSetError CollectionSizeError ContextError ConversionActionError CriterionError CustomerFeedError DatabaseError DateError DateRangeError DistinctError ExtensionFeedItemError ExtensionSettingError FeedAttributeReferenceError FeedError FeedItemError FeedItemSetError FieldError FieldMaskError FunctionParsingError HeaderError ImageError InternalError KeywordPlanAdGroupKeywordError KeywordPlanCampaignError KeywordPlanError LabelError ListOperationError MediaUploadError MutateError NewResourceCreationError NullError OperationAccessDeniedError PolicyFindingError PolicyViolationError QuotaError RangeError RequestError ResourceCountLimitExceededError SettingError SharedSetError SizeLimitError StringFormatError StringLengthError UrlFieldError UserListError YoutubeVideoRegistrationError

Żądanie HTTP

POST https://googleads.googleapis.com/v19/customers/{customerId}/googleAds:mutate

Adres URL używa składni transkodowania gRPC.

Parametry ścieżki

Parametry
customerId

string

Wymagany. Identyfikator klienta, którego zasoby są modyfikowane.

Treść żądania

Treść żądania zawiera dane o następującej strukturze:

Zapis JSON 
{
  "mutateOperations": [
    {
      object (MutateOperation)
    }
  ],
  "partialFailure": boolean,
  "validateOnly": boolean,
  "responseContentType": enum (ResponseContentType)
}
Pola
mutateOperations[]

object (MutateOperation)

Wymagany. Lista operacji do wykonania na poszczególnych zasobach.
partialFailure

boolean

Jeśli wartość to prawda, operacje zakończą się powodzeniem, a nieprawidłowe operacje zwrócą błędy. Jeśli jest to wartość false, wszystkie operacje zostaną wykonane w ramach jednej transakcji, o ile wszystkie są prawidłowe. Wartość domyślna to fałsz.
validateOnly

boolean

Jeśli to prawda, żądanie jest sprawdzane, ale nie jest wykonywane. Zwracane są tylko błędy, a nie wyniki.
responseContentType

enum (ResponseContentType)

Ustawienie typu treści odpowiedzi. Określa, czy po zmianie ma zostać zwrócony zasób z możliwością zmiany, czy tylko nazwa zasobu. Zmienny zasób zostanie zwrócony tylko wtedy, gdy ma odpowiednie pole odpowiedzi. Na przykład MutateCampaignResult.campaign.

Treść odpowiedzi

Odpowiedź na pytanie „GoogleAdsService.Mutate”.

W przypadku powodzenia treść żądania zawiera dane o następującej strukturze:

Zapis JSON 
{
  "partialFailureError": {
    object (Status)
  },
  "mutateOperationResponses": [
    {
      object (MutateOperationResponse)
    }
  ]
}
Pola
partialFailureError

object (Status)

Błędy dotyczące niepowodzeń operacji w trybie częściowego niepowodzenia. Zwracany tylko wtedy, gdy partialFailure = true i wszystkie błędy występują wewnątrz operacji. Jeśli wystąpią błędy poza operacjami (np. błędy uwierzytelniania), zwracamy błąd na poziomie RPC.
mutateOperationResponses[]

object (MutateOperationResponse)

Wszystkie odpowiedzi dla operacji mutate.

Zakresy autoryzacji

Wymaga następującego zakresu OAuth:

  • https://www.googleapis.com/auth/adwords

Więcej informacji znajdziesz w OAuth 2.0 Overview.