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 cómo modificar 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 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
• 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 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 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 cada una.

Por ejemplo, si deseas crear diez campañas, debes enviar un solo objeto 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 campo 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 modificació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 fallas 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 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 control 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 método GoogleAdsService.SearchStream o GoogleAdsService.Search. Obtén más información sobre la transmisión de informes con GoogleAdsService.