Video: Consulta la charla sobre servicios y recursos del taller de 2019
En esta guía, se presentan los componentes principales de 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 las entidades de Google Ads.
Jerarquía de objetos
Una cuenta de Google Ads se puede ver 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 usan para agrupar los anuncios en colecciones lógicas.
Un anuncio del grupo de anuncios representa un anuncio que estás publicando. Excepto en el caso de las campañas de aplicaciones que solo pueden tener un anuncio por grupo de anuncios, cada grupo de anuncios contiene uno o más anuncios.
Puedes adjuntar uno o más AdGroupCriterion o CampaignCriterion a un grupo de anuncios o una campaña. Estos representan los criterios que definen cómo se activan los anuncios.
Existen muchos tipos de criterios, como palabras clave, rangos de edad y ubicaciones. Los criterios definidos a nivel de la campaña afectan a todos los demás recursos dentro de la campaña. También puedes especificar presupuestos y fechas para toda la campaña.
Por último, puedes adjuntar extensiones a nivel de la cuenta, la campaña o el grupo de anuncios. Las extensiones te permiten proporcionar información adicional a tus anuncios, como el número de teléfono, la dirección o promociones.
Recursos
Los recursos representan las entidades que se encuentran dentro de tu cuenta de Google Ads. Campaign y AdGroup son dos ejemplos de recursos.
IDs de objeto
Cada objeto en 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 son únicos solo dentro de un alcance limitado.
| ID de objeto | Alcance de la singularidad | ¿Es único a nivel global? |
|---|---|---|
| ID de presupuesto | Global | Sí |
| Campaign ID | 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 |
| ID de AdGroupCriterion | Grupo de anuncios | No, pero el par (AdGroupId, CriterionId) es único a nivel global |
| ID de criterio de campaña | Campaña | No, pero el par (CampaignId, CriterionId) es único a nivel global |
| Extensiones de anuncios | Campaña | No, pero el par (CampaignId, AdExtensionId) es único a nivel global |
| ID del feed | Global | Sí |
| ID de elemento del feed | Global | Sí |
| ID del atributo del feed | Feed | No |
| ID de asignación de feeds | Global | Sí |
| ID de etiqueta | Global | Sí |
| ID de lista de usuarios | Global | Sí |
Estas reglas de ID pueden ser útiles cuando diseñas el almacenamiento local para tus objetos de Google Ads.
Algunos objetos se pueden usar para varios tipos de entidades. En esos casos, el objeto incluye un campo type que describe su contenido. Por ejemplo, AdGroupAd puede hacer referencia a un objeto, como un anuncio de texto, un anuncio de hotel o un anuncio local. Se puede acceder a este valor a través del campo AdGroupAd.ad.type, y muestra un valor de la enum AdType.
Nombres de recursos
Cada recurso se identifica de forma única mediante una cadena resource_name, que concatena el recurso y sus elementos superiores en una ruta de acceso. 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: de modificación, de recuperación de objetos y estadísticas, y de recuperación de metadatos.
Modificar (mutar) objetos
Estos servicios modifican las instancias de un tipo de recurso asociado mediante una solicitud mutate. También proporcionan una solicitud get que recupera una única instancia de recurso, lo que puede ser útil para examinar la estructura de un recurso.
Ejemplos de servicios:
CustomerServicepara modificar clientes.CampaignServicepara modificar campañas.AdGroupServicepara modificar grupos de anuncios.
Cada solicitud mutate debe incluir los objetos operation correspondientes. Por ejemplo, el método CampaignService.MutateCampaigns espera una o más instancias de CampaignOperation. Consulta Cómo inspeccionar y cambiar objetos para obtener un análisis detallado de las operaciones.
Mutaciones simultáneas
Un objeto de Google Ads no puede ser modificado por más de una fuente de forma simultánea. Esto podría provocar errores si varios usuarios actualizan el mismo objeto con la app o si cambias objetos de Google Ads en paralelo con varios subprocesos. Esto incluye la actualización del objeto desde varios subprocesos en la misma aplicación o desde diferentes aplicaciones (por ejemplo, tu app 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 al mismo tiempo, la API genera un DatabaseError.CONCURRENT_MODIFICATION_ERROR.
Mutaciones asíncronas en comparación con síncronos
Los métodos de modificación de la API de Google Ads son síncronos. Las llamadas a la API muestran una respuesta solo después de que los objetos mutan, por lo que debes esperar una respuesta a cada solicitud. Si bien este enfoque es relativamente sencillo de programar, podría tener un impacto negativo en 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 mediante 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 los procesos para que realicen otras operaciones. Puedes verificar periódicamente el estado del trabajo para confirmarlo.
Consulta la Guía de procesamiento por lotes para obtener más información sobre el procesamiento asíncrono.
Validación de modificación
La mayoría de las solicitudes de mutación pueden validarse sin ejecutar la llamada con datos reales. Puedes probar la solicitud en busca de parámetros faltantes y valores de campo incorrectos sin ejecutar la operación realmente.
Para usar esta función, establece el campo booleano validate_only opcional de la solicitud en true. La solicitud se validaría por completo como si se ejecutara, pero se omite la ejecución final. Si no se encuentran errores, se muestra una respuesta vacía. Si la validación falla, los mensajes de error en la respuesta indicarían los puntos de falla.
validate_only es muy útil para probar anuncios en busca de incumplimientos de política comunes. Los anuncios se rechazan automáticamente si infringen políticas como el uso de palabras específicas, puntuación, mayúsculas o longitud. Un solo anuncio inapropiado podría provocar que falle todo el lote. Probar un anuncio nuevo en una solicitud validate_only
puede revelar esos incumplimientos. Consulta el ejemplo de código para manejar errores de incumplimiento de política a fin de ver esto en acción.
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 debe 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 consulta, revisa la guía sobre el lenguaje de consulta de Google Ads.
Cómo recuperar metadatos
GoogleAdsFieldService recupera los metadatos sobre los recursos de la API de Google Ads, como los atributos disponibles para un recurso y su tipo de datos.
Este servicio proporciona la información necesaria para crear una consulta en GoogleAdsService. Para mayor comodidad, la información que muestra GoogleAdsFieldService también está disponible en la documentación de referencia de campos.