En esta guía, se presentan los componentes principales que conforman la API de Google Ads. La API de Google Ads consta de recursos y servicios. Un recurso representa una entidad de Google Ads, mientras que los servicios recuperan y manipulan entidades de Google Ads.
Jerarquía de objetos
Una cuenta de Google Ads se puede considerar como una jerarquía de objetos.
El recurso de nivel superior de una cuenta es el cliente.
Cada cliente contiene una o más campañas activas.
Cada campaña contiene uno o más grupos de anuncios, que se utilizan para agrupar tus anuncios en colecciones lógicas.
Un anuncio del grupo de anuncios representa un anuncio que publicas en un grupo de anuncios. A excepción de las campañas de aplicaciones, que solo pueden tener un anuncio del grupo de anuncios por grupo de anuncios, cada grupo de anuncios contiene uno o más anuncios del grupo de anuncios.
Las campañas de máximo rendimiento utilizan una estructura diferente a la de otros tipos de campañas: en lugar de grupos de anuncios y anuncios del grupo de anuncios, una campaña de máximo rendimiento contiene grupos de recursos. Vinculas los recursos de creatividad a un grupo de recursos con AssetGroupAsset y adjuntas indicadores de público o de tema de búsqueda con AssetGroupSignal.
Puedes adjuntar uno o más recursos de AdGroupCriterion o CampaignCriterion a un grupo de anuncios o una campaña. Representan los criterios que definen cómo se activan los anuncios.
Existen muchos tipos de criterios, como palabras clave, rangos de edades y ubicaciones. Los criterios definidos a nivel de la campaña afectan a todos los demás recursos de la campaña. También puedes especificar presupuestos, así como fechas y horas de inicio y finalización para las campañas o para los anuncios individuales con AdGroupAd.start_date_time y AdGroupAd.end_date_time.
Por último, puedes adjuntar recursos a nivel de la cuenta, la campaña, el grupo de anuncios o el grupo de recursos. Los recursos te permiten proporcionar información adicional a tus anuncios, como números de teléfono, direcciones o promociones. Consulta la descripción general de los recursos.
Recursos
Los recursos representan las entidades dentro de tu cuenta de Google Ads.
Campaign y AdGroup son dos ejemplos de recursos.
IDs de objetos
Cada objeto de Google Ads se identifica con su propio ID. Algunos de estos IDs son únicos a nivel global en todas las cuentas de Google Ads, mientras que otros solo son únicos dentro de un alcance limitado.
| ID de objeto | Alcance de la unicidad | ¿Es único a nivel global? |
|---|---|---|
| ID de presupuesto | Global | Sí |
| ID de la campaña | Global | Sí |
| ID del grupo de anuncios | Global | Sí |
| ID del anuncio | Grupo de anuncios | No, pero el par (AdGroupId, AdId) es único a nivel global. Se prohíbe compartir un AdId en varios grupos de anuncios. |
| ID del criterio del grupo de anuncios | Grupo de anuncios | No, pero el par (AdGroupId, CriterionId) es único a nivel global |
| ID de CampaignCriterion | Campaña | No, pero el par (CampaignId, CriterionId) es único a nivel global |
| ID de etiqueta | Cliente | No, pero el par (CustomerId, LabelId) es único a nivel global |
| ID de UserList | Global | Sí |
| ID del recurso | Global | Sí |
Estas reglas de ID pueden ser útiles cuando diseñes el almacenamiento local para tus objetos de Google Ads.
Algunos objetos se pueden usar para varios tipos de entidades. En esos casos, el objeto contiene un campo type que describe su contenido. Por ejemplo, AdGroupAd puede hacer referencia a un objeto, como un anuncio de búsqueda responsivo, un anuncio de hotel o un anuncio de generación de demanda. Se puede acceder a este valor a través del campo AdGroupAd.ad.type y devuelve un valor en la enumeración AdType. Ten en cuenta que la mutabilidad puede variar según la versión (por ejemplo, VideoResponsiveAdInfo en Ad es mutable en la versión 24 y posteriores).
Nombres de recursos
Cada recurso se identifica de forma única con una cadena de resource_name que concatena el recurso y sus elementos superiores en una ruta. Por ejemplo, los nombres de recursos de las campañas tienen el siguiente formato:
customers/customer_id/campaigns/campaign_id
Por lo tanto, para una campaña con el ID 987654 en la cuenta de Google Ads con el ID de cliente 1234567, el resource_name sería el siguiente:
customers/1234567/campaigns/987654
Servicios
Los servicios te permiten recuperar y modificar tus entidades de Google Ads. Existen tres tipos de servicios: modificación, recuperación de objetos y estadísticas, y recuperación de metadatos.
Modifica (muta) objetos
Los servicios específicos del recurso modifican instancias de un tipo de recurso asociado con una solicitud mutate. También puedes usar GoogleAdsService.Mutate para realizar mutaciones atómicas en varios tipos de recursos en una sola solicitud (por ejemplo, crear un presupuesto de la campaña, una campaña y un grupo de anuncios juntos).
Ejemplos de servicios específicos de recursos:
CustomerServicepara modificar clientesCampaignServicepara modificar campañasAdGroupServicepara modificar grupos de anuncios
Cada solicitud de mutate debe incluir los objetos operation correspondientes. Por ejemplo, el método CampaignService.MutateCampaigns espera una o más instancias de CampaignOperation. Consulta Objetos de cambio para obtener una explicación detallada de las operaciones.
Mutaciones simultáneas
Más de una fuente no puede modificar un objeto de Google Ads de forma simultánea. Esto podría provocar errores si varios usuarios actualizan el mismo objeto con tu app o si mutas objetos de Google Ads en paralelo con varios subprocesos. Esto incluye actualizar el objeto desde varios subprocesos en la misma aplicación o desde diferentes aplicaciones (por ejemplo, tu aplicación y una sesión simultánea de la IU de Google Ads).
La API no proporciona una forma de bloquear un objeto antes de actualizarlo. Si dos fuentes intentan mutar un objeto de forma simultánea, la API genera un DatabaseError.CONCURRENT_MODIFICATION_ERROR.
Mutaciones síncronas y asíncronas
Los métodos de mutación de la API de Google Ads son síncronos. Las llamadas a la API devuelven una respuesta solo después de que se modifican los objetos, lo que requiere que esperes una respuesta a cada solicitud. Si bien este enfoque es relativamente sencillo de codificar, podría afectar negativamente el balanceo de cargas y desperdiciar recursos si los procesos se ven obligados a esperar a que se completen las llamadas.
Un enfoque alternativo es mutar objetos de forma asíncrona con BatchJobService, que realiza lotes de operaciones en varios servicios sin esperar a que se completen. Una vez que se envía un trabajo por lotes, los servidores de la API de Google Ads ejecutan operaciones de forma asíncrona, lo que libera procesos para realizar otras operaciones. Puedes verificar periódicamente el estado del trabajo para ver si se completó.
Consulta la guía de procesamiento por lotes para obtener más información sobre el procesamiento asíncrono.
Validación de la mutación
La mayoría de las solicitudes de mutación se pueden validar sin ejecutar realmente la llamada con datos reales. Puedes probar la solicitud para detectar parámetros faltantes y valores de campos incorrectos sin ejecutar la operación.
Para usar esta función, establece el campo booleano opcional validate_only de la solicitud en true. La solicitud se valida por completo como si se fuera a ejecutar, pero se omite la ejecución final. Si no se encuentran errores, se devuelve la respuesta sin ningún resultado mutado propagado (results está vacío). Si falla la validación, la solicitud falla con un error de RPC GoogleAdsFailure de forma predeterminada (partial_failure = false) o devuelve una respuesta normal con errores específicos de la operación en partial_failure_error cuando partial_failure = true.
validate_only es particularmente útil para probar anuncios en busca de incumplimientos comunes de políticas. Los anuncios se rechazan automáticamente si incumplen políticas como tener palabras, signos de puntuación, uso de mayúsculas o longitud específicos. Un solo anuncio que infringe las políticas podría hacer que falle todo un lote. Probar un anuncio nuevo en una solicitud validate_only puede revelar cualquier incumplimiento de este tipo. Consulta el ejemplo de código para controlar errores de incumplimiento de políticas y ver cómo funciona.
Cómo obtener objetos y estadísticas de rendimiento
GoogleAdsService es el servicio único y unificado para recuperar objetos y estadísticas de rendimiento.
Todas las solicitudes de Search y SearchStream para GoogleAdsService requieren una consulta que especifique el recurso que se consultará, los atributos del recurso y las métricas de rendimiento que se recuperarán, los predicados que se usarán para filtrar la solicitud y los segmentos que se usarán para desglosar aún más las estadísticas de rendimiento. Para obtener más información sobre el formato de las consultas, consulta la guía del lenguaje de consultas de Google Ads.
Recupera metadatos
GoogleAdsFieldService recupera metadatos sobre los recursos en la API de Google Ads, como los atributos disponibles para un recurso y su tipo de datos. Consulta la Guía de metadatos de recursos para obtener detalles sobre cómo consultar este servicio.
Este servicio proporciona la información necesaria para construir una consulta a GoogleAdsService. Para mayor comodidad, la información que devuelve GoogleAdsFieldService también está disponible en la documentación de referencia de los campos.