Method: customers.googleAds.mutate

Создает, обновляет или удаляет ресурсы. Этот метод поддерживает атомарные транзакции с несколькими типами ресурсов. Например, вы можете атомарно создать кампанию и бюджет кампании или выполнить до тысячи изменений атомарно.

Этот метод по сути является оболочкой ряда методов mutate. Единственные функции, которые он предлагает при непосредственном вызове этих методов:

  • Атомарные транзакции
  • Имена временных ресурсов (описаны ниже)
  • Несколько уменьшена задержка при выполнении серии вызовов мутации.

Примечание. Включены только ресурсы, поддерживающие атомарные транзакции, поэтому этот метод не может заменить все вызовы отдельных служб.

Преимущества атомарных транзакций

Атомарность значительно упрощает обработку ошибок. Если вы вносите серию изменений и одно из них не удалось, это может привести к тому, что ваша учетная запись окажется в несогласованном состоянии. При атомарности вы либо напрямую достигаете выбранного состояния, либо запрос завершается неудачно, и вы можете повторить попытку.

Имена временных ресурсов

Имена временных ресурсов — это особый тип имени ресурса, используемый для создания ресурса и ссылки на этот ресурс в одном запросе. Например, если бюджет кампании создается с resourceName равным customers/123/campaignBudgets/-1 , это имя ресурса можно повторно использовать в поле Campaign.budget в том же запросе. Таким образом, два ресурса создаются и связываются атомарно.

Чтобы создать имя временного ресурса, укажите отрицательное число в той части имени, которую обычно выделяет сервер.

Примечание:

  • Ресурсы должны быть созданы с временным именем, прежде чем это имя можно будет использовать повторно. Например, предыдущий пример CampaignBudget+Campaign завершится ошибкой, если порядок изменения будет изменен на обратный.
  • Имена временных файлов не запоминаются при выполнении запросов.
  • Количество временных имен в запросе не ограничено.
  • Каждое временное имя должно использовать уникальное отрицательное число, даже если типы ресурсов различаются.

Задержка

Важно группировать изменения по типу ресурса, иначе запрос может истечь и завершиться ошибкой. Задержка примерно равна серии вызовов отдельных методов mutate, где каждое изменение типа ресурса представляет собой новый вызов. Например, изменение 10 кампаний, а затем 10 групп объявлений — это 2 звонка, а изменение 1 кампании, 1 группы объявлений, 1 кампании, 1 группы объявлений — это 4 звонка.

Список выброшенных ошибок : AdCustomizerError AdError AdGroupAdError AdGroupCriterionError AdGroupError AssetError AuthenticationError AuthorizationError 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

HTTP-запрос

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

URL-адрес использует синтаксис транскодирования gRPC .

Параметры пути

Параметры
customerId

string

Необходимый. Идентификатор клиента, ресурсы которого изменяются.

Тело запроса

Тело запроса содержит данные следующей структуры:

JSON-представление
{
  "mutateOperations": [
    {
      object (MutateOperation)
    }
  ],
  "partialFailure": boolean,
  "validateOnly": boolean,
  "responseContentType": enum (ResponseContentType)
}
Поля
mutateOperations[]

object ( MutateOperation )

Необходимый. Список операций, которые необходимо выполнить над отдельными ресурсами.

partialFailure

boolean

Если это правда, будут выполнены успешные операции, а недопустимые операции вернут ошибки. Если false, все операции будут выполняться за одну транзакцию тогда и только тогда, когда все они действительны. По умолчанию — ложь.

validateOnly

boolean

Если это правда, запрос проверяется, но не выполняется. Возвращаются только ошибки, а не результаты.

responseContentType

enum ( ResponseContentType )

Настройка типа контента ответа. Определяет, должен ли быть возвращен после мутации изменяемый ресурс или только имя ресурса. Изменяемый ресурс будет возвращен только в том случае, если ресурс имеет соответствующее поле ответа. Например, MutateCampaignResult.campaign.

Тело ответа

Ответное сообщение для GoogleAdsService.Mutate .

В случае успеха тело ответа содержит данные следующей структуры:

JSON-представление
{
  "partialFailureError": {
    object (Status)
  },
  "mutateOperationResponses": [
    {
      object (MutateOperationResponse)
    }
  ]
}
Поля
partialFailureError

object ( Status )

Ошибки, относящиеся к сбоям работы в режиме частичного отказа. Возвращается только в том случае, если partialFailure = true и все ошибки происходят внутри операций. Если возникают какие-либо ошибки вне операций (например, ошибки аутентификации), мы возвращаем ошибку уровня RPC.

mutateOperationResponses[]

object ( MutateOperationResponse )

Все ответы на mutate.

Области авторизации

Требуется следующая область действия OAuth:

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

Дополнительную информацию см. в обзоре OAuth 2.0 .