Ejemplos

Esta guía contiene ejemplos de cómo llamar a los extremos de REST directamente, sin tener que usar una biblioteca cliente.

Requisitos previos

Todos los ejemplos que aparecen a continuación deben copiarse y pegarse en una shell de Bash con el comando curl.

También necesitas un token de desarrollador, el acceso a la cuenta de prueba es correcto 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) de un usuario que tiene acceso de administrador a una cuenta de administrador (MANAGER_CUSTOMER_ID) que administra directamente la cuenta de cliente. Si, en cambio, accedes a una cuenta de cliente individual directamente, omite el encabezado login-customer-id o configúralo con el mismo valor que CUSTOMER_ID. Ten en cuenta que algunos ejemplos, como Crea cuentas, requieren una cuenta de administrador.

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="16"
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, las dos opciones Mutates: Creates example crean un presupuesto y una campaña nuevos.

Buscar

La 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 compilación de consultas interactivas 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, 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'

Modificación

Se pueden enviar varias operaciones de mutación (create, update o remove) en un solo cuerpo de solicitud JSON si se propaga 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 mediante su nombre de recurso. La campaña que se crea a continuación hace referencia a un 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 mediante 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 incluirse en la solicitud y que se deben aplicar como una actualización. Los atributos enumerados en updateMask, pero que no están presentes en el cuerpo de la solicitud, se borran en un objeto. Se ignoran los atributos que no figuran en updateMask, pero que 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 los objetos, debes especificar el nombre de su 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 sola solicitud, puedes especificar partialFailure de manera 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 tienen éxito solo si todas son válidas.

En el siguiente ejemplo, se usa una campaña existente. Puedes copiar y pegar el resultado del ejemplo Creaciones.

CAMPAIGN_ID=CAMPAIGN_ID

La siguiente solicitud contiene dos operaciones. El primero intenta cambiar la estrategia de oferta 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 da como resultado un error (el ID de la campaña no es válido) y debido a que partialFailure se establece en 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 no falla ninguna operación o todas fallan si falla alguna de ellas.

En este ejemplo, se muestra cómo crear una campaña, un presupuesto, una campaña, un grupo de anuncios y un anuncio de forma conjunta en un solo conjunto de acciones. Cada operación sucesiva depende de la anterior. Si una 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 durante 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'
}
}"

Haz una lista de las 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 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}" \

Sube elementos 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 en base64 estándar con padding. Se acepta la codificación en base64 estándar o segura para URLs 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'
      }
    }
  }
]
}"