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

Использование выделенного сервиса ресурса — это наиболее прямой способ создания, обновления или удаления сущностей одного типа ресурса в 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 операций на запрос или 20 000 для AdGroupCriterionService.MutateAdGroupCriteria ; CustomerService.MutateCustomer принимает поле "одна operation "). По умолчанию все операции в запросе выполняются атомарно, если только сервис не поддерживает partial_failure и вы не установите для него значение true .

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

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

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

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

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

• Сервисы целей жизненного цикла: Цели удержания клиентов изменяются во всех поддерживаемых версиях с помощью GoalService.MutateGoals ( retention_goal_settings ) и CampaignGoalConfigService.MutateCampaignGoalConfigs ( campaign_retention_settings ) с использованием стандартного поля повторяющихся operations . В версии 25 и более поздних версиях цели привлечения новых клиентов ( new_customer_acquisition_goal_settings / campaign_new_customer_acquisition_settings ) и удержания лояльных клиентов ( loyalty_retention_goal_settings / campaign_loyalty_retention_settings ) также изменяются с помощью GoalService.MutateGoals и CampaignGoalConfigService.MutateCampaignGoalConfigs . Это заменяет CustomerLifecycleGoalService.ConfigureCustomerLifecycleGoals и CampaignLifecycleGoalService.ConfigureCampaignLifecycleGoals , которые использовались для привлечения новых клиентов в версиях 23 и 24 и принимали одно поле operation .