Method: customers.googleAds.mutate

Tworzy, aktualizuje lub usuwa zasoby. Ta metoda obsługuje niepodzielne transakcje z wieloma typami zasobów. Możesz na przykład utworzyć kampanię i jej budżet lub wykonać nawet tysiące mutacji atomowych.

Zasadniczo metoda ta obejmuje serię metod mutacji. Jedyne funkcje, jakie oferuje, zamiast bezpośredniego wywoływania tych metod, to:

  • Transakcje Atomic
  • Nazwy zasobów tymczasowych (opisane poniżej)
  • Trochę krótszy czas oczekiwania w porównaniu z serią wywołań zmodyfikowanych

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

Zalety Atomic Transaction

Atominess znacznie ułatwia obsługę błędów. Jeśli wprowadzisz serię zmian, a jedna zakończy się niepowodzeniem, stan konta może być niespójny. Dzięki atrybutowi atomicity możesz bezpośrednio dotrzeć do wybranego stanu lub żądanie zakończy się niepowodzeniem i możesz spróbować jeszcze raz.

Nazwy zasobów tymczasowych

Tymczasowe nazwy zasobów to specjalny typ nazwy zasobu używana do utworzenia zasobu i odwołania do niego w tym samym żądaniu. Jeśli np. budżet kampanii został utworzony z wartością resourceName równą customers/123/campaignBudgets/-1, tej nazwy zasobu można użyć ponownie w polu Campaign.budget w tym samym żądaniu. W ten sposób zasoby zostaną utworzone i połączone atomowo.

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

Uwaga:

  • Zasoby muszą być utworzone z tymczasową nazwą, zanim będzie można jej użyć ponownie. Jeśli na przykład kolejność mutacji zostanie odwrócona, poprzedni przykładowy przykład kampanii Budżet kampanii i Kampania nie powiedzie się.
  • Nazwy tymczasowe nie są zapamiętywane w żądaniach.
  • Nie ma limitu liczby nazw tymczasowych w żądaniu.
  • Każda nazwa tymczasowa musi używać niepowtarzalnej liczby ujemnej, nawet jeśli typy zasobów są różne.

Czas oczekiwania

Ważne jest grupowanie mutacji według typu zasobu. W przeciwnym razie żądanie może spowodować przekroczenie limitu czasu i niepowodzenie. Czas oczekiwania jest mniej więcej taki sam jak seria wywołań poszczególnych metod mutacji, przy czym każda zmiana typu zasobu to nowe wywołanie. Na przykład przekształcenie 10 kampanii i 10 grup reklam to 2 połączenia, a zmiana jednej kampanii, 1 grupy reklam, 1 kampanii i 1 grupy reklam to 4 połączenia.

AdCustomizerErrorAdErrorAdGroupAdErrorAdGroupCriterionErrorAdGroupErrorAssetErrorAuthenticationErrorAuthorizationErrorBiddingErrorCampaignBudgetErrorCampaignCriterionErrorCampaignErrorCampaignExperimentErrorCampaignSharedSetErrorCollectionSizeErrorContextErrorConversionActionErrorCriterionErrorCustomerFeedErrorDatabaseErrorDateErrorDateRangeErrorDistinctErrorExtensionFeedItemErrorExtensionSettingErrorFeedAttributeReferenceErrorFeedErrorFeedItemErrorFeedItemSetErrorFieldErrorFieldMaskErrorFunctionParsingErrorHeaderErrorImageErrorInternalErrorKeywordPlanAdGroupKeywordErrorKeywordPlanCampaignErrorKeywordPlanErrorLabelErrorListOperationErrorMediaUploadErrorMutateErrorNewResourceCreationErrorNullErrorOperationAccessDeniedErrorPolicyFindingErrorPolicyViolationErrorQuotaErrorRangeErrorRequestErrorResourceCountLimitExceededErrorSettingErrorSharedSetErrorSizeLimitErrorStringFormatErrorStringLengthErrorUrlFieldErrorUserListErrorYoutubeVideoRegistrationError

Żądanie HTTP

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

Adres URL używa składni transkodowania gRPC.

Parametry ścieżki

Parametry
customerId

string

Wymagane. 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)

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

boolean

Jeśli ma wartość true (prawda), wykonywane są udane operacje, a nieprawidłowe – zwracają błędy. W przypadku wartości false (fałsz) wszystkie operacje będą wykonywane w ramach jednej transakcji tylko wtedy, gdy są prawidłowe. Wartość domyślna to false (fałsz).
validateOnly

boolean

Jeśli ma wartość true (prawda), żądanie jest weryfikowane, ale nie jest wykonywane. Zwracane są tylko błędy, a nie wyniki.
responseContentType

enum (ResponseContentType)

Ustawienie typu treści odpowiedzi. Określa, czy po mutacji powinien zostać zwrócony zasób zmienny, czy tylko jego nazwa. Zasób zmienny jest zwracany tylko wtedy, gdy zasób ma odpowiednie pole odpowiedzi. Na przykład MutateCampaignResult.campaign.

Treść odpowiedzi

Wiadomość z odpowiedzią dla: 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, które odnoszą się do nieudanych operacji w trybie częściowej awarii. Zwracany tylko wtedy, gdy częściowyFailure ma wartość true (prawda) i wszystkie błędy występują w ramach operacji. Jeśli wystąpią jakieś błędy poza operacjami (na przykład błędy uwierzytelniania), zwrócimy błąd na poziomie RPC.
mutateOperationResponses[]

object (MutateOperationResponse)

Wszystkie odpowiedzi mutacji.

Zakresy autoryzacji

Wymaga następującego zakresu OAuth:

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

Więcej informacji znajdziesz w artykule Omówienie protokołu OAuth 2.0.