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:

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

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

1. Crea un objeto Campaign con los atributos que elijas.
2. Asígnalo 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 de la API de Google Ads:

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

La siguiente carga útil de 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 mutació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:

• Tipo de recurso único: 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 de un recurso solo acepta un tipo de recurso, no puedes asignar un ID negativo temporal a un recurso superior (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 mutan 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, la adquisición de clientes nuevos (new_customer_acquisition_goal_settings/campaign_new_customer_acquisition_settings) y la retención de clientes leales (loyalty_retention_goal_settings/campaign_loyalty_retention_settings) también se mutan a través de GoalService.MutateGoals y CampaignGoalConfigService.MutateCampaignGoalConfigs. Esto reemplaza a CustomerLifecycleGoalService.ConfigureCustomerLifecycleGoals y CampaignLifecycleGoalService.ConfigureCampaignLifecycleGoals, que se usan para la adquisición de clientes nuevos en las versiones 23 y 24, y aceptan un campo operation singular.