Video: Consulta la charla sobre recursos y servicios 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 entidades de Google Ads.
Jerarquía de objetos
Una cuenta de Google Ads puede verse 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 tus anuncios en colecciones lógicas.
Un anuncio del grupo de anuncios representa un anuncio que usted publica. A excepción de las campañas de aplicaciones que solo pueden tener un anuncio de grupo de anuncios, cada uno contiene uno o más anuncios.
Puede adjuntar uno o más AdGroupCriterion o CampaignCriterion a un grupo de anuncios o una campaña. Representan 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 ella. También puedes especificar fechas y presupuestos 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 le permiten proporcionar información adicional a sus anuncios, como número de teléfono, dirección o promociones.
Recursos
Los recursos representan las entidades en su cuenta de Google Ads.
Campaign y AdGroup son dos ejemplos de recursos.
ID de objeto
Cada objeto en Google Ads se identifica por su propio ID. Algunos de estos ID son únicos a nivel global en todas las cuentas de Google Ads, mientras que otros son únicos de manera limitada.
| ID de objeto | Alcance de la singularidad | ¿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 | Ad Group | No, pero el par (AdGroupId, AdId) es único a nivel global |
| ID del grupo de anuncios | Ad Group | 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 |
| 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 a la hora de diseñar 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 anuncio de texto, un anuncio de hotel, un anuncio local, etc. Se puede acceder a este valor a través del campo AdGroupAd.ad.type y muestra un valor en la enumeración AdType.
Nombres de recursos
Cada recurso se identifica de forma única mediante una string resource_name, que concatena el recurso y sus elementos superiores en una ruta de acceso. Por ejemplo, los nombres de los recursos de campaña 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:
customers/1234567/campaigns/987654
Servicios
Los servicios le permiten recuperar y modificar sus entidades de Google Ads. Existen tres tipos de servicios: modificación, recuperación de objetos y estadísticas, y servicios de recuperación de metadatos.
Modificar (mutar) objetos
Estos servicios modifican instancias de un tipo de recurso asociado mediante una solicitud mutate. También proporcionan una solicitud get que recupera una sola instancia de recurso, lo que puede ser útil para examinar la estructura de un recurso.
Ejemplos de servicios:
CustomerServicepara modificar los clientesCampaignServicepara modificar campañasAdGroupServicepara modificar los 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 una explicación detallada de las operaciones.
Mutaciones simultáneas
Un objeto de Google Ads no puede ser modificado simultáneamente en más de una fuente. Esto podría provocar errores si tienes varios usuarios que actualizan el mismo objeto con tu app o si estás mutando objetos de Google Ads en paralelo con varios subprocesos. Esto incluye la actualización del objeto de varios subprocesos en la misma aplicación o de diferentes aplicaciones (por ejemplo, tu app y una sesión simultánea de IU de Google Ads).
La API no proporciona una forma de bloquear un objeto antes de la actualización; si dos fuentes intentan mutar un objeto al mismo tiempo, la API genera un DatabaseError.CONCURRENT_MODIFICATION_ERROR.
Mutaciones asíncronas y síncronas
Los métodos de mutación de la API de Google Ads son síncronos. Las llamadas a la API muestran una respuesta solo después de que se mutan los objetos, lo que requiere que esperes una respuesta a cada solicitud. Si bien este enfoque es relativamente sencillo de codificar, podría afectar de forma negativa 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 manera asíncrona, lo que libera procesos para realizar otras operaciones. Puedes verificar de forma periódica el estado del trabajo para completarlo.
Consulta la Guía de procesamiento por lotes para obtener más información sobre el procesamiento asíncrono.
Silenciar validación
La mayoría de las solicitudes de mutación se pueden validar sin ejecutar la llamada con datos reales. Puedes probar la solicitud de parámetros faltantes y valores de campo incorrectos sin ejecutar la operación.
Para usar esta función, establece el campo booleano validate_only opcional de la solicitud en true. La solicitud se validará por completo como si fuera a ejecutarse, pero se omite la ejecución final. Si no se encuentran errores, se muestra una respuesta vacía. Si falla la validación, los mensajes de error en la respuesta indicarán los puntos de error.
validate_only es particularmente útil para probar anuncios que incumplen
las políticas comunes. Los anuncios se rechazan automáticamente si infringen políticas, como tener palabras, puntuación, mayúsculas o longitud específicas. Un único anuncio incorrecto puede provocar la falla de todo un lote. Probar un anuncio nuevo en una solicitud de
validate_only puede revelar tales incumplimientos. Consulta el ejemplo de código a fin de manejar errores de incumplimiento de política para ver esto en acción.
Obtén objetos y estadísticas de rendimiento
GoogleAdsService es el único servicio unificado para recuperar objetos y estadísticas de rendimiento.
Todas las solicitudes Search y SearchStream para GoogleAdsService requieren una consulta que especifique el recurso que se consultará, los atributos de recurso y las métricas de rendimiento que se recuperarán, los predicados que se usarán a fin de 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 búsqueda, revisa la guía de lenguaje de consultas de Google Ads.
Recuperar metadatos
GoogleAdsFieldService recupera metadatos sobre recursos en la API de Google Ads, como los atributos disponibles para un recurso y su tipo de datos.
Este servicio proporciona información que necesitarás para construir una consulta a GoogleAdsService. Para mayor comodidad, la información que muestra GoogleAdsFieldService también está disponible en la documentación de referencia de campos.