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

Dado que el campo operations de una solicitud de modificación se repite, una sola solicitud puede contener varias operaciones (hasta 10,000 operaciones por solicitud) para ese tipo de recurso. De forma predeterminada, todas las operaciones de la solicitud se ejecutan de forma atómica, a menos que establezcas partial_failure en 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 de recursos temporales ni referencias cruzadas: Las operaciones en una llamada de mutación específica del recurso se procesan de forma independiente. No puedes asignar IDs negativos temporales (como customers/CUSTOMER_ID/campaigns/-1) ni hacer referencia a entidades creadas recientemente a partir de otras operaciones en la misma solicitud.

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

Diferencias específicas de la versión

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

• Servicios de objetivos de ciclo de vida: En la versión 25 y posteriores, todos los objetivos de ciclo de vida, incluidos los de adquisición de clientes nuevos (new_customer_acquisition_goal_settings), retención de clientes (retention_goal_settings) y retención de lealtad (loyalty_retention_goal_settings), se modifican a través de GoalService.MutateGoals y CampaignGoalConfigService.MutateCampaignGoalConfigs con un campo operations repetido estándar. Esto reemplaza a CustomerLifecycleGoalService.ConfigureCustomerLifecycleGoals y CampaignLifecycleGoalService.ConfigureCampaignLifecycleGoals (que se usan para la adquisición de clientes nuevos en la versión 24 y anteriores, y aceptan un campo operation singular).
• Campos de fecha y hora de la campaña: Cuando se crea o actualiza un objeto Campaign, la versión 23 y las posteriores usan start_date_time y end_date_time (yyyy-MM-dd HH:mm:ss), lo que reemplaza los campos start_date y end_date solo de fecha que se usaban en la versión 22.
• Mutabilidad de la certificación de contenido sintético: Si bien Asset.synthetic_content_info y Ad.synthetic_content_info aparecen en el esquema para la versión 22 y posteriores, los campos synthetic_content_info.advertiser_attestation.status y synthetic_content_info.advertiser_attestation.source solo son mutables en la versión 23 y posteriores (system_attestation siempre es OUTPUT_ONLY). Si intentas mutar los subcampos advertiser_attestation en la versión 22, se mostrará un error de campo inmutable ("The field attempted to be mutated is immutable" o "Field cannot be set").