Cambia objetos

Objetivo: Comprender cómo modificar objetos con la API de Google Ads.

Como se explica en la guía de estructura de la API, cada recurso de nivel superior de la API de Google Ads tiene un servicio específico del tipo de recurso correspondiente que admite la modificación de instancias del recurso. También puedes usar GoogleAdsService.Mutate para mutar varios tipos de recursos de forma atómica en una sola solicitud.

En esta guía, se usa CampaignService para demostrar cómo modificar objetos Campaign, pero los mismos conceptos se aplican a todos los demás servicios específicos del tipo de recurso.

Término clave: Un recurso de nivel superior es un recurso cuyo nombre no incluye un punto (.). Por ejemplo, Campaign es un recurso de nivel superior, pero Campaign.NetworkSettings no lo es.

Solicitudes de mutación

Cada servicio específico del tipo de recurso tiene un método mutate que acepta una solicitud de mutación. Esta solicitud consta de lo siguiente:

• Un customer_id (o customerId en las URLs de REST)
• Una colección de operations
• Configuración de ejecución opcional, como partial_failure, validate_only y response_content_type (que determina si se devuelve el recurso mutable o solo el nombre del recurso después de la mutación)

Por ejemplo, el método MutateCampaigns de CampaignService acepta un MutateCampaignsRequest que consta de lo siguiente:

• A customer_id
• Una colección de objetos CampaignOperation (operations)
• Configuración de ejecución opcional (partial_failure, validate_only y response_content_type que indican el tipo de respuesta preferido)

Nota: Los servicios y métodos disponibles pueden variar según las versiones de la API. Por ejemplo, para configurar los objetivos de ciclo de vida de los clientes y las campañas, usa los métodos Mutate* en GoalService y CampaignGoalConfigService en la versión 25 y posteriores, o los métodos Configure* en CustomerLifecycleGoalService y CampaignLifecycleGoalService en la versión 24 y anteriores.

Operaciones

Un objeto de operación, como CampaignOperation, te permite especificar la acción que deseas realizar en un solo recurso configurando su campo operation. Este campo es un campo oneof que consta de los siguientes atributos:

create

Crea una instancia nueva del recurso.

update

Actualiza el recurso para que coincida con los atributos del recurso update. Cuando se establece este campo, también debes establecer la update_mask de la operación, que le indica a la API de Google Ads qué atributos modificar durante la operación de actualización. Cada biblioteca cliente incluye una utilidad de máscara de campo o un método auxiliar que genera la update_mask por ti.

remove

Quita el recurso especificado por su cadena de nombre de recurso (por ejemplo, customers/1234567890/campaigns/987654321).

Dado que el campo operation es un campo oneof, no puedes usar una sola operación para modificar varios objetos. Por ejemplo, si deseas crear una campaña y quitar otra, agrega dos instancias de CampaignOperation a tu solicitud: una con create establecido y otra con remove establecido.

Operaciones por lotes

Aunque una sola operación solo puede crear, actualizar o quitar un único recurso, una sola solicitud de mutación puede contener varias operaciones. Debes combinar tus operaciones en una sola solicitud de mutación en lugar de enviar varias solicitudes de mutación que contengan una sola operación.

Por ejemplo, si deseas crear diez campañas, debes enviar una única MutateCampaignsRequest que tenga diez objetos CampaignOperation. Para agrupar operaciones en diferentes tipos de recursos en una sola solicitud, usa GoogleAdsService.Mutate o recursos de mutación.

Respuestas de mutación

Lo que se devuelve en la respuesta depende de lo que se envió en el campo response_content_type de la solicitud de mutación. Por ejemplo, si se especifica MUTABLE_RESOURCE, la respuesta contiene el resource_name del recurso y los campos mutables de la campaña en campaign. De forma predeterminada (RESOURCE_NAME_ONLY), solo se propaga el resource_name en cada MutateCampaignResult.

Errores de mutación

De forma predeterminada (partial_failure = false), las operaciones de una solicitud de mutación se aplican a tu cuenta de Google Ads solo si todas las operaciones de la solicitud se realizan correctamente. Si alguna operación falla, se revierte toda la solicitud. En el caso de las solicitudes de mutación que admiten errores parciales (aquellas con un campo partial_failure en el mensaje de solicitud), establecer partial_failure = true confirma las operaciones válidas, mientras que las operaciones con errores devuelven errores específicos de la operación en el campo partial_failure_error de la respuesta. Consulta la guía de fallas parciales y la guía de errores comunes para obtener detalles sobre cómo controlar los errores.

Realiza un seguimiento de los cambios

Para hacer un seguimiento de los cambios realizados en los objetos de tu cuenta de Google Ads o recuperar el estado actual de los objetos, puedes usar los recursos change_status y change_event.

• change_status proporciona un resumen de los recursos que cambiaron en un período determinado.
• change_event proporciona un historial detallado de los cambios, incluidos los valores antiguos y nuevos de los campos modificados.

Para consultar estos recursos, usa el método GoogleAdsService.SearchStream o GoogleAdsService.Search. Obtén más información para transmitir informes con GoogleAdsService.