Esta guía contiene ejemplos de llamadas a los extremos de REST directamente, sin el uso de una biblioteca cliente.
Requisitos previos
Todas las muestras que aparecen a continuación se deben copiar y pegar en un shell de Bash con el comando curl.
También necesitas un token de desarrollador, el acceso a la cuenta de prueba está bien y una cuenta de administrador de Google Ads que contenga, al menos, una cuenta de cliente.
Variables de entorno
Ingresa las credenciales y los IDs de la cuenta a continuación y, luego, cópialos y pégalos en tu terminal para configurar las variables de entorno que se usan en los ejemplos posteriores. La guía de Autorización proporciona instrucciones para generar un token de acceso de OAuth 2.0.
API_VERSION="17"
DEVELOPER_TOKEN="DEVELOPER_TOKEN"
OAUTH2_ACCESS_TOKEN="OAUTH_ACCESS_TOKEN"
MANAGER_CUSTOMER_ID="MANAGER_CUSTOMER_ID"
CUSTOMER_ID="CUSTOMER_ID"
IDs de objeto opcionales adicionales
Algunos de los siguientes ejemplos funcionan en campañas o presupuestos preexistentes. Si tienes ID de objetos existentes para usar con estos ejemplos, ingrésalos a continuación.
BUDGET_ID=BUDGET_ID
CAMPAIGN_ID=CAMPAIGN_ID
De lo contrario, los dos valores de Mutates: Crea ejemplos crean un presupuesto y una campaña nuevos.
Buscar
La guía Guía de soluciones de consultas contiene muchas muestras de informes que corresponden a algunas de las pantallas predeterminadas de Google Ads y funcionan con las mismas variables de entorno que se usan en esta guía. Nuestra herramienta de creación de consultas interactiva también es un gran recurso para compilar consultas personalizadas de forma interactiva.
Paginado
El método search
usa paginación, con un tamaño de página fijo de 10,000 elementos y un page_token
especificado junto con el query
.
cURL
curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:search" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data '{ "query": " SELECT campaign.name, campaign_budget.amount_micros, campaign.status, campaign.optimization_score, campaign.advertising_channel_type, metrics.clicks, metrics.impressions, metrics.ctr, metrics.average_cpc, metrics.cost_micros, campaign.bidding_strategy_type FROM campaign WHERE segments.date DURING LAST_7_DAYS AND campaign.status != 'REMOVED' ", "page_token":"${PAGE_TOKEN}" }'
GAQL
SELECT campaign.name, campaign_budget.amount_micros, campaign.status, campaign.optimization_score, campaign.advertising_channel_type, metrics.clicks, metrics.impressions, metrics.ctr, metrics.average_cpc, metrics.cost_micros, campaign.bidding_strategy_type FROM campaign WHERE segments.date DURING LAST_7_DAYS AND campaign.status != 'REMOVED'
Transmisión
El método searchStream
transmite todos los resultados en una sola respuesta, por lo que no se admite el campo pageSize
.
cURL
curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:searchStream" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data '{ "query": " SELECT campaign.name, campaign_budget.amount_micros, campaign.status, campaign.optimization_score, campaign.advertising_channel_type, metrics.clicks, metrics.impressions, metrics.ctr, metrics.average_cpc, metrics.cost_micros, campaign.bidding_strategy_type FROM campaign WHERE segments.date DURING LAST_7_DAYS AND campaign.status != 'REMOVED' " }'
GAQL
SELECT campaign.name, campaign_budget.amount_micros, campaign.status, campaign.optimization_score, campaign.advertising_channel_type, metrics.clicks, metrics.impressions, metrics.ctr, metrics.average_cpc, metrics.cost_micros, campaign.bidding_strategy_type FROM campaign WHERE segments.date DURING LAST_7_DAYS AND campaign.status != 'REMOVED'
Modificaciones
Se pueden enviar varias operaciones de mutación (create
, update
o remove
) en un solo cuerpo de solicitud JSON si propagas el array operations
.
Crea
En este ejemplo, se crean dos presupuestos de campaña compartidos en una sola solicitud.
curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaignBudgets:mutate" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data "{ 'operations': [ { 'create': { 'name': 'My Campaign Budget #${RANDOM}', 'amountMicros': 500000, } }, { 'create': { 'name': 'My Campaign Budget #${RANDOM}', 'amountMicros': 500000, } } ] }"
En el siguiente ejemplo, se usa un BUDGET_ID
del presupuesto de una campaña existente. Puedes copiar y pegar desde el resultado del paso anterior.
BUDGET_ID=BUDGET_ID
Los recursos que hacen referencia a otros recursos lo hacen por nombre de recurso. La campaña creada a continuación se refiere a una campaignBudget
por su nombre de recurso con valor de cadena.
curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaigns:mutate" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data "{ 'operations': [ { 'create': { 'status': 'PAUSED', 'advertisingChannelType': 'SEARCH', 'geoTargetTypeSetting': { 'positiveGeoTargetType': 'PRESENCE_OR_INTEREST', 'negativeGeoTargetType': 'PRESENCE_OR_INTEREST' }, 'name': 'My Search campaign #${RANDOM}', 'campaignBudget': 'customers/${CUSTOMER_ID}/campaignBudgets/${BUDGET_ID}', 'targetSpend': {} } } ] }"
Actualizaciones
Actualiza los atributos de los objetos existentes con las operaciones update
. En el siguiente ejemplo, se usa una campaña existente. Puedes copiar y pegar desde el resultado del paso anterior.
CAMPAIGN_ID=CAMPAIGN_ID
Todas las actualizaciones requieren un campo updateMask
, una lista separada por comas de los atributos JSON que deben estar en la solicitud, que se debe aplicar como una actualización. Los atributos enumerados en updateMask
, pero que no están presentes en el cuerpo de la solicitud, se borran de un objeto. Se ignoran los atributos que no se enumeran en updateMask
, pero están presentes en el cuerpo de la solicitud.
curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaigns:mutate" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data "{ 'operations': [ { 'update': { 'resourceName': 'customers/${CUSTOMER_ID}/campaigns/${CAMPAIGN_ID}', 'name': 'A changed campaign name #${RANDOM}', }, 'updateMask': 'name' } ], }"
Quitar
Los objetos se quitan especificando su nombre de recurso como una operación remove
.
curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaigns:mutate" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data "{ 'operations': [ { 'remove': 'customers/${CUSTOMER_ID}/campaigns/${CAMPAIGN_ID}' } ], }"
Fallas parciales
Cuando haya varias operaciones en una sola solicitud, especifica partialFailure
de forma opcional. Si es true
, se realizan operaciones exitosas y las operaciones no válidas muestran errores. Si es false
, todas las operaciones de la solicitud se realizarán de manera correcta siempre y cuando todas sean válidas.
En el siguiente ejemplo, se usa una campaña existente. Puedes copiarla y pegarla del resultado del ejemplo de Creaciones.
CAMPAIGN_ID=CAMPAIGN_ID
La siguiente solicitud contiene dos operaciones. El primer intento de cambiar la estrategia de ofertas de la campaña proporcionada y el siguiente intenta quitar una campaña con un ID no válido. Dado que la segunda operación genera un error (el ID de la campaña no es válido) y que partialFailure
está configurado como false
, la primera operación también falla y la estrategia de oferta de la campaña existente no se actualiza.
curl --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaigns:mutate" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data "{ 'partialFailure': false, 'operations': [ { 'update': { 'resourceName': 'customers/${CUSTOMER_ID}/campaigns/${CAMPAIGN_ID}', 'manualCpc': { 'enhancedCpcEnabled': false } }, 'updateMask': 'manual_cpc.enhanced_cpc_enabled' }, { 'remove': 'customers/${CUSTOMER_ID}/campaigns/INVALID_CAMPAIGN_ID' } ] }"
Operaciones agrupadas
El método googleAds:mutate
admite el envío de grupos de operaciones con varios tipos de recursos. Puedes enviar muchas operaciones de diferentes tipos para encadenar una secuencia de operaciones que se deben realizar como grupo.
El conjunto de operaciones se realiza de forma correcta si ninguna operación falla, o todas fallan si falla alguna operación.
En este ejemplo, se muestra cómo crear un presupuesto, una campaña, un grupo de anuncios y un anuncio en conjunto como un solo conjunto de acciones. Cada operación sucesiva depende de la anterior. Si uno falla, falla todo el grupo de operaciones.
Los números enteros negativos (-1
, -2
, -3
) se usan como marcadores de posición en los nombres de los recursos y se completan de forma dinámica en el tiempo de ejecución con los resultados de la secuencia de operaciones.
curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:mutate" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data "{ 'mutateOperations': [ { 'campaignBudgetOperation': { 'create': { 'resourceName': 'customers/${CUSTOMER_ID}/campaignBudgets/-1', 'name': 'My Campaign Budget #${RANDOM}', 'deliveryMethod': 'STANDARD', 'amountMicros': 500000, 'explicitlyShared': false } } }, { 'campaignOperation': { 'create': { 'resourceName': 'customers/${CUSTOMER_ID}/campaigns/-2', 'status': 'PAUSED', 'advertisingChannelType': 'SEARCH', 'geoTargetTypeSetting': { 'positiveGeoTargetType': 'PRESENCE_OR_INTEREST', 'negativeGeoTargetType': 'PRESENCE_OR_INTEREST' }, 'name': 'My Search campaign #${RANDOM}', 'campaignBudget': 'customers/${CUSTOMER_ID}/campaignBudgets/-1', 'targetSpend': {} } } }, { 'adGroupOperation': { 'create': { 'resourceName': 'customers/${CUSTOMER_ID}/adGroups/-3', 'campaign': 'customers/${CUSTOMER_ID}/campaigns/-2', 'name': 'My ad group #${RANDOM}', 'status': 'PAUSED', 'type': 'SEARCH_STANDARD' } } }, { 'adGroupAdOperation': { 'create': { 'adGroup': 'customers/${CUSTOMER_ID}/adGroups/-3', 'status': 'PAUSED', 'ad': { 'responsiveSearchAd': { 'headlines': [ { 'pinned_field': 'HEADLINE_1', 'text': 'An example headline' }, { 'text': 'Another example headline' }, { 'text': 'Yet another headline' } ], 'descriptions': [ { 'text': 'An example description' }, { 'text': 'Another example description' } ], 'path1': 'all-inclusive', 'path2': 'deals' }, 'finalUrls': ['https://www.example.com'] } } } } ] }"
Administración de cuentas
Creación de cuentas
Crea cuentas nuevas con el método createCustomerClient
. Ten en cuenta que la URL requiere un ID de cuenta de administrador en lugar de un ID de cuenta de cliente. Se crea una cuenta de cliente nueva en la cuenta de administrador.
curl f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${MANAGER_CUSTOMER_ID}:createCustomerClient" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data "{ 'customerClient': { 'descriptiveName': 'My Client #${RANDOM}', 'currencyCode': 'USD', 'timeZone': 'America/New_York' } }"
Cómo mostrar una lista de cuentas accesibles
Usa una solicitud GET
simple al método listAccessibleCustomers
para obtener una lista de las cuentas de Google Ads a las que se puede acceder con el token de acceso de OAuth 2.0 determinado. No se deben usar IDs de cuenta de administrador ni de cuenta de cliente en esta solicitud.
curl -f --request GET "https://googleads.googleapis.com/v${API_VERSION}/customers:listAccessibleCustomers" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
Cómo subir recursos binarios
El método assets:mutate
se usa para subir y administrar recursos. Los datos binarios, como una imagen, se codifican como una string mediante la codificación base64 estándar con relleno. Se acepta la codificación en Base64 estándar o segura para URL, con o sin relleno.
En este ejemplo, se codifica un GIF de 1 píxel para que el ejemplo sea conciso. En la práctica, las cargas útiles de data
son mucho más grandes.
Usa la utilidad de línea de comandos base64
(parte de las utilidades principales de GNU) para codificar una imagen GIF de 1 píxel.
base64 1pixel.gif
El valor codificado en base64 se especifica como el atributo data
en una solicitud a la API.
curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/assets:mutate" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data "{ 'operations': [ { 'create': { 'name': 'My image asset #${RANDOM}', 'type': 'IMAGE', 'imageAsset': { 'data': 'R0lGODlhAQABAAAAACH5BAEAAAAALAAAAAABAAEAAAIA' } } } ] }"