Cambia objetos

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 la modificación de objetos Campaign, pero los mismos conceptos se aplican a todos los demás servicios específicos del tipo de recurso.

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
• Parámetros de configuración de ejecución opcionales, como partial_failure, validate_only y response_content_type (que determina si se muestra 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:

• Un customer_id
• Una colección de objetos CampaignOperation (operations)
• Parámetros de configuración de ejecución opcionales (partial_failure, validate_only y response_content_type que indican el tipo de respuesta preferido)

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 oneof campo 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 el 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 el 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 establecida y otra con remove establecida.

Operaciones por lotes

Si bien una sola operación solo puede crear, actualizar o quitar un solo 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 un MutateCampaignsRequest único 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 muestra en la respuesta depende de lo que se envió en el response_content_type campo de la solicitud de mutación. Por ejemplo, si MUTABLE_RESOURCE se especifica, entonces 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 falla alguna operación, se revierte toda la solicitud. Para las solicitudes de mutación que admiten fallas parciales (aquellas con un campo partial_failure en el mensaje de solicitud), si se establece partial_failure = true, se confirman las operaciones válidas, mientras que las operaciones fallidas muestran 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 el manejo de 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 GoogleAdsService.SearchStream o el GoogleAdsService.Search método. Obtén más información sobre la transmisión de informes con GoogleAdsService.