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 |
Wymagane. Identyfikator klienta, którego zasoby są modyfikowane. |
Treść żądania
Treść żądania zawiera dane o następującej strukturze:
Zapis JSON |
---|
{ "mutateOperations": [ { object ( |
Pola | |
---|---|
mutateOperations[] |
Wymagane. Lista operacji do wykonania na poszczególnych zasobach. |
partialFailure |
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 |
Jeśli ma wartość true (prawda), żądanie jest weryfikowane, ale nie jest wykonywane. Zwracane są tylko błędy, a nie wyniki. |
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 ( |
Pola | |
---|---|
partialFailureError |
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[] |
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.