Google utiliza tecnología de IA para traducir contenido a tu idioma preferido. Las traducciones realizadas con IA pueden contener errores.

Ejemplos

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

Para obtener ejemplos de código más detallados, consulta el repositorio de GitHub de ejemplos de código REST .

Para ver los cuerpos de solicitud y respuesta de cada método de la API, consulta la documentación de referencia de los extremos de servicio específicos.

Por ejemplo, la página de referencia de GoogleAdsService.Search muestra los cuerpos de solicitud y respuesta del método Search.

Requisitos previos

Todos los ejemplos que se muestran aquí están diseñados para copiarse y pegarse en un bash shell con el comando curl.

También necesitas un token de desarrollador (el acceso a la cuenta de prueba es suficiente) 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 como se muestra y, luego, copia y pega en tu terminal para configurar las variables de entorno que se usan en los ejemplos posteriores. En la guía de autorización, se proporcionan instrucciones para generar un token de acceso de OAuth 2.0.

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

IDs de objetos opcionales adicionales

Algunos de los siguientes ejemplos funcionan en presupuestos o campañas preexistentes. Si tienes IDs de objetos existentes para usar con estos ejemplos, ingrésalos como se muestra.

BUDGET_ID=BUDGET_ID
CAMPAIGN_ID=CAMPAIGN_ID

De lo contrario, los dos ejemplos de Mutates - Creates crean un presupuesto nuevo y una campaña.

Buscar

La guía de Query Cookbook contiene muchos ejemplos 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 interactiva de creación de consultas también es un excelente recurso para crear 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 la 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'

Mutaciones

Se pueden enviar varias operaciones de mutación (create, update o remove) en un solo cuerpo de solicitud JSON propagando 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 de un presupuesto de campaña existente. Puedes copiarlo y pegarlo 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 en el siguiente ejemplo 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 con las operaciones update. En el siguiente ejemplo, se usa una campaña existente. Puedes copiarla y pegarla 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 y que se deben aplicar como una actualización. Los atributos que aparecen en updateMask pero que no están presentes en el cuerpo de la solicitud se borran en un objeto. Los atributos que no aparecen en updateMask, pero que están presentes en el cuerpo de la solicitud, se ignoran.

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 hay varias operaciones en una sola solicitud, especifica partialFailure de forma opcional. Si es true, se llevan a cabo las operaciones exitosas y las operaciones no válidas muestran errores. Si es false, todas las operaciones de la solicitud se realizan correctamente solo si todas son válidas.

En el siguiente ejemplo, se usa una campaña existente. Puedes copiarla y pegarla desde el resultado del ejemplo Creates example.

CAMPAIGN_ID=CAMPAIGN_ID

La siguiente solicitud contiene dos operaciones. La primera intenta cambiar la estrategia de oferta de la campaña proporcionada, y la 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 no se actualiza la estrategia de oferta de la campaña existente.

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 llevar a cabo como un grupo. El conjunto de operaciones se realiza correctamente si no falla ninguna operación o todas fallan si falla alguna operación.

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

Puedes crear cuentas, obtener una lista de las cuentas accesibles y subir recursos binarios.

Crea 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'
}
}"

Obtén 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 cuentas 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 recursos binarios

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

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 base64 (que forma 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'
      }
    }
  }
]
}"

Errores frecuentes

Probar

Ejemplos Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

Requisitos previos

Variables de entorno

IDs de objetos opcionales adicionales

Buscar

Paginado

curl

GAQL

Transmisión

curl

GAQL

Mutaciones

Crea

Actualizaciones

Quitar

Fallas parciales

Operaciones agrupadas

Administración de la cuenta

Crea cuentas

Obtén una lista de cuentas accesibles

Sube recursos binarios

Ejemplos