El servicio de recursos realiza mutaciones

Usar el servicio dedicado de un recurso es la forma más directa de crear, actualizar o quitar entidades de un solo tipo de recurso en la API de Google Ads.

Endpoints de mutación

Cada recurso mutable tiene un servicio y un tipo de operación correspondientes. Para mutar un recurso con su servicio dedicado, completa uno de los siguientes campos en la operación y envíalo al extremo de mutación del servicio:

• Create (create): Es un objeto de recurso nuevo que se creará.
• Actualización (update): Es el objeto de recurso modificado, acompañado de un update_mask que especifica los campos modificados.
• Quitar (remove): Es la cadena resource_name del recurso de destino que se quitará.

Por ejemplo, para crear un nuevo Campaign, completa los siguientes pasos:

1. Construye un objeto Campaign con los atributos que elegiste.
2. Asigna el valor al campo create de un CampaignOperation.
3. Envía la operación en un MutateCampaignsRequest a CampaignService.MutateCampaigns.

Este mismo patrón se aplica a todos los servicios específicos de recursos en la API de Google Ads:

• AdGroup: Pasa un AdGroupOperation a AdGroupService.MutateAdGroups.
• CampaignCriterion: Pasa un CampaignCriterionOperation a CampaignCriterionService.MutateCampaignCriteria.

La siguiente carga útil JSON de REST ilustra una solicitud a 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
}

Varias operaciones y limitaciones

La mayoría de las solicitudes de modificación específicas de recursos aceptan un campo operations repetido, por lo que una sola solicitud puede contener varias operaciones para ese tipo de recurso (hasta 10,000 operaciones por solicitud o 20,000 para AdGroupCriterionService.MutateAdGroupCriteria; CustomerService.MutateCustomer acepta un campo operation singular). De forma predeterminada, todas las operaciones de la solicitud se ejecutan de forma atómica, a menos que el servicio admita partial_failure y lo configures como true.

Sin embargo, los servicios de recursos individuales tienen dos limitaciones importantes:

• Un solo tipo de recurso: Una solicitud a un servicio de recursos solo puede mutar los recursos administrados por ese servicio específico.
• No hay IDs temporales entre recursos: Debido a que una llamada de mutación específica del recurso solo acepta un tipo de recurso, no puedes asignar un ID negativo temporal a un recurso principal (como customers/CUSTOMER_ID/campaigns/-1) y hacer referencia a él desde un recurso secundario de un tipo diferente (como un AdGroup) en la misma solicitud. (Se admiten los IDs temporales que hacen referencia a sí mismos dentro del mismo tipo de recurso para los árboles jerárquicos, como los grupos de fichas AdGroupCriterion y los nodos AssetGroupListingGroupFilter).

Si necesitas mutar varios tipos de recursos en una sola solicitud o hacer referencia a nombres de recursos temporales en diferentes tipos de recursos, usa GoogleAdsService.Mutate en su lugar.

Diferencias específicas de la versión

Ten en cuenta la siguiente diferencia entre las versiones compatibles de la API de Google Ads cuando modifiques recursos:

• Servicios de objetivos de ciclo de vida: Los objetivos de retención de clientes se modifican en todas las versiones compatibles a través de GoalService.MutateGoals (retention_goal_settings) y CampaignGoalConfigService.MutateCampaignGoalConfigs (campaign_retention_settings) con un campo operations repetido estándar. En la versión 25 y posteriores, los objetivos de adquisición de clientes nuevos (new_customer_acquisition_goal_settings / campaign_new_customer_acquisition_settings) y de retención de clientes leales (loyalty_retention_goal_settings / campaign_loyalty_retention_settings) también se modifican a través de GoalService.MutateGoals y CampaignGoalConfigService.MutateCampaignGoalConfigs. Esto reemplaza a CustomerLifecycleGoalService.ConfigureCustomerLifecycleGoals y CampaignLifecycleGoalService.ConfigureCampaignLifecycleGoals, que se utilizan para la adquisición de clientes nuevos en las versiones 23 y 24, y aceptan un campo operation singular.