Сервис ресурсов мутирует

Использование выделенного сервиса ресурса — это наиболее прямой способ создания, обновления или удаления сущностей одного типа ресурса в API Google Ads.

Мутация конечных точек

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

• Создать ( create ): Новый ресурсный объект для создания.
• Обновление ( update ): Измененный объект ресурса, сопровождаемый маской update_mask , указывающей на измененные поля.
• Remove ( remove ): Строка resource_name целевого ресурса, который нужно удалить.

Например, для создания новой Campaign выполните следующие шаги:

1. Создайте объект Campaign с выбранными вами атрибутами.
2. Присвойте его полю create CampaignOperation .
3. Отправьте операцию в запросе MutateCampaignsRequest в CampaignService.MutateCampaigns .

Та же закономерность применима ко всем сервисам, специфичным для конкретных ресурсов, в API Google Ads:

• AdGroup : Передайте объект AdGroupOperation в метод AdGroupService.MutateAdGroups .
• CampaignCriterion : Передайте объект CampaignCriterionOperation в метод CampaignCriterionService.MutateCampaignCriteria .

Приведенный ниже REST JSON-код иллюстрирует запрос к CampaignService.MutateCampaigns :

{
  "customerId": "CUSTOMER_ID",
  "operations": [
    {
      "create": {
        "name": "Interplanetary Cruise #1",
        "advertisingChannelType": "SEARCH",
        "status": "PAUSED",
        "manualCpc": {},
        "campaignBudget": "customers/CUSTOMER_ID/campaignBudgets/BUDGET_ID",
        "containsEuPoliticalAdvertising": "DOES_NOT_CONTAIN_EU_POLITICAL_ADVERTISING"
      }
    }
  ],
  "partialFailure": false,
  "validateOnly": false
}

Множество операций и ограничений

Поскольку поле operations в запросе на изменение повторяется, один запрос может содержать несколько операций (до 10 000 операций на запрос) для данного типа ресурса. По умолчанию все операции в запросе выполняются атомарно, если только вы не установите partial_failure в true .

Однако индивидуальные ресурсные услуги имеют два важных ограничения:

• Тип ресурса: Запрос к службе ресурсов может изменять только ресурсы, управляемые этой конкретной службой.
• Запрещено присваивать временные идентификаторы ресурсов или использовать перекрестные ссылки: операции в вызове mutate, специфичном для ресурса, обрабатываются независимо. Нельзя присваивать временные отрицательные идентификаторы (например, customers/CUSTOMER_ID/campaigns/-1 ) или ссылаться на вновь созданные сущности из других операций в том же запросе.

Если вам необходимо изменять несколько типов ресурсов в одном запросе или ссылаться на имена временных ресурсов в зависимых операциях, используйте вместо этого GoogleAdsService.Mutate .

Различия, специфичные для каждой версии

При изменении ресурсов учитывайте следующие различия между поддерживаемыми версиями Google Ads API:

• Сервисы целей жизненного цикла: В версии 25 и более поздних версиях все цели жизненного цикла, включая привлечение новых клиентов ( new_customer_acquisition_goal_settings ), удержание клиентов ( retention_goal_settings ) и удержание лояльных клиентов ( loyalty_retention_goal_settings ), изменяются с помощью GoalService.MutateGoals и CampaignGoalConfigService.MutateCampaignGoalConfigs , используя стандартное поле повторяющихся operations . Это заменяет CustomerLifecycleGoalService.ConfigureCustomerLifecycleGoals и CampaignLifecycleGoalService.ConfigureCampaignLifecycleGoals (которые используются для привлечения новых клиентов в версии 24 и более ранних версиях и принимают поле одной operation ).
• Поля даты и времени кампании: При создании или обновлении Campaign в версиях 23 и выше используются поля start_date_time и end_date_time ( yyyy-MM-dd HH:mm:ss ), заменяющие поля start_date и end_date , содержащие только дату, которые использовались в версии 22.
• Изменяемость синтетического контента при аттестации: Хотя поля Asset.synthetic_content_info и Ad.synthetic_content_info присутствуют в схеме для версий 22 и более поздних, поля synthetic_content_info.advertiser_attestation.status и synthetic_content_info.advertiser_attestation.source изменяемы только в версиях 23 и более поздних ( system_attestation всегда имеет OUTPUT_ONLY ). Попытка изменить подполя advertiser_attestation в версии 22 приводит к ошибке неизменяемого поля ( "The field attempted to be mutated is immutable" или "Field cannot be set" ).