Ejemplos

Esta guía contiene ejemplos de llamadas a los extremos de REST directamente, sin el uso de una biblioteca cliente.

Prerequisites

Todas las muestras que se muestran a continuación deben copiarse y pegarse fácilmente en una Shell de Bash con un comando curl.

También necesitarás un token de desarrollador (está bien el acceso a la cuenta de prueba) y una cuenta de administrador de Google Ads que contenga al menos una cuenta de cliente.

Importante: En estos ejemplos, suponemos que accedes a una cuenta de cliente (CUSTOMER_ID) por un usuario que tiene acceso de administrador a una cuenta de administrador (MANAGER_CUSTOMER_ID) que administra directamente la cuenta de cliente. En cambio, si accedes directamente a una cuenta de cliente individual, omite el encabezado login-customer-id o establécelo en el mismo valor que CUSTOMER_ID. Ten en cuenta que algunos ejemplos, como Crear cuentas, requieren una cuenta de administrador.

Variables de entorno

Ingresa los ID y las credenciales de la cuenta a continuación y, luego, cópialos y pégalos en tu terminal para configurar las variables de entorno utilizadas en los ejemplos siguientes.

Nota: En la guía sobre autorización, se proporcionan instrucciones para generar un token de acceso de OAuth 2.0.

API_VERSION="11"
DEVELOPER_TOKEN="DEVELOPER_TOKEN"
OAUTH2_ACCESS_TOKEN="OAUTH_ACCESS_TOKEN"
MANAGER_CUSTOMER_ID="MANAGER_CUSTOMER_ID"
CUSTOMER_ID="CUSTOMER_ID"

ID de objetos opcionales adicionales

Algunos de los siguientes ejemplos funcionan en presupuestos o campañas 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 Mutates: Crea ejemplos crearán una campaña y un presupuesto nuevos.

Búsqueda

Nota: La guía de 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 compilador de consultas interactivo también es un gran recurso para compilar consultas personalizadas de manera interactiva.

Paginado

El método search usa la paginación, con un parámetro pageSize ajustable especificado junto con 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 '{
"pageSize": 10,
"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'

Transmisión

El método searchStream transmite todos los resultados en una sola respuesta y, por lo tanto, 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'

Silenciaciones

Se pueden enviar varias operaciones de mutación (create, update o remove) en un solo cuerpo de solicitud JSON. Para ello, propaga el array de operations.

Crea

En este ejemplo, se crean dos presupuestos de campañas 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 utiliza un BUDGET_ID de un presupuesto de campaña existente (puedes copiar y pegar el resultado del paso anterior).

BUDGET_ID=BUDGET_ID

Los recursos que hacen referencia a otros recursos lo hacen por nombre del recurso. La campaña creada a continuación hace referencia a una campaignBudget por su nombre de recurso con valor de string.

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 objetos existentes mediante operaciones update. En el siguiente ejemplo, se usa una campaña existente (puedes copiarla y pegarla a partir del resultado anterior).

CAMPAIGN_ID=CAMPAIGN_ID

Todas las actualizaciones requieren un campo updateMask, que es una lista separada por comas en la que se deben aplicar los atributos JSON de la solicitud. Los atributos que se enumeran 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 aparecen en el 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

Para quitar objetos, simplemente especifica 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 hay varias operaciones en una única solicitud, puedes especificar partialFailure. Si es true, se realizarán operaciones correctas y las operaciones no válidas mostrarán errores. Si es false, todas las operaciones de la solicitud serán exitosas si solo son válidas.

En el siguiente ejemplo, se usa una campaña existente (puedes copiarla y pegarla desde el resultado Creas).

CAMPAIGN_ID=CAMPAIGN_ID

La siguiente solicitud contiene dos operaciones. El primer intento de cambiar la estrategia de oferta de la campaña proporcionada y el siguiente intento de 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 como partialFailure se establece en false, la primera operación también falla y, por lo tanto, no se actualiza la estrategia de oferta existente de la campaña.

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 un grupo. El conjunto de operaciones tendrá éxito si ninguna operación falla o todas fallan si una sola operación falla.

En este ejemplo, se muestra cómo crear un presupuesto de campaña, una campaña, un grupo de anuncios y un anuncio de texto en conjunto como un conjunto único de acciones. Cada operación sucesiva depende de la anterior. Si uno falla, todo el grupo de operaciones falla.

Nota: Ten en cuenta que los números enteros negativos (-1, -2, -3) se usan como marcadores de posición en los siguientes nombres de recursos. Se completan de forma dinámica en el entorno de ejecución con los resultados del procesamiento 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': {
          'expandedTextAd': {
            'headlinePart1': 'An example headline1',
            'headlinePart2': 'An example headline2',
            'description': 'An example description'
          },
          '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 creará 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'
}
}"

Muestra una lista de cuentas a las que se puede acceder

Usa una solicitud GET simple al método listAccessibleCustomers para obtener una lista de cuentas de Google Ads accesibles con el token de acceso de OAuth 2.0 determinado. Ten en cuenta que no se deben usar ID de cuenta de cliente ni de administrador 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}" \

Subir elementos binarios

El método assets:mutate se usa para subir y administrar elementos. Los datos binarios, como una imagen, se codifican como una string con relleno base64 estándar con paddings. Se aceptan la codificación base64 estándar o segura para URL con paddings o sin ellos.

Nota: En este ejemplo, se codifica un GIF de 1 píxel para que la muestra sea concisa. En la práctica, las cargas útiles de data son mucho más grandes.

Usa la utilidad de línea de comandos de base64 (parte de las utilidades principales de GNU) para codificar una imagen de 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'
      }
    }
  }
]
}"