Ejemplos

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

Requisitos previos

Las siguientes muestras están diseñadas para copiarse y pegarse en un bash shell con el comando curl.

También necesitas un token de desarrollador; prueba acceso a la cuenta está bien, y La cuenta de administrador de Google Ads debe contener, 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 usadas 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 tienen los IDs de los objetos existentes para usar en estos ejemplos, ingrésalos a continuación.

BUDGET_ID=BUDGET_ID
CAMPAIGN_ID=CAMPAIGN_ID

De lo contrario, los dos valores Mutates - Creates Examples (Mutates: Crea ejemplos) crean un presupuesto nuevo. y la campaña.

La guía Guía de soluciones de consultas contiene muchos informes que corresponden a algunas de las pantallas predeterminadas de Google Ads y que trabajan con las mismas variables de entorno que se usan en esta guía. Nuestra consulta interactiva Builder es También es un gran recurso para crear consultas personalizadas de manera 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 tanto, el 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 cuerpo de la solicitud JSON individual 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 del presupuesto de una campaña existente. puedes cópialos y pégalos del resultado del paso anterior.

BUDGET_ID=BUDGET_ID

Los recursos que hacen referencia a otros recursos lo hacen nombre del recurso. La campaña creada a continuación hace referencia a 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. Los siguientes ejemplo, usa una campaña existente; que puedes copiar y pegar el resultado del paso.

CAMPAIGN_ID=CAMPAIGN_ID

Todas las actualizaciones requieren un campo updateMask, una lista separada por comas de qué atributos JSON deben incluirse en la solicitud y cuáles deben aplicarse como actualización. Atributos enumerados en updateMask, pero que no están presentes en la solicitud cuerpo se borran en un objeto. Atributos no enumerados en updateMask, pero presentes en el cuerpo de la solicitud, se ignorarán.

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, puedes especificar partialFailure Si es true, se llevan a cabo operaciones exitosas y las operaciones no válidas devuelven errores. Si es false, todas las operaciones de la solicitud tendrán éxito solo si son todas válidas.

En el siguiente ejemplo, se usa una campaña existente. que puedes copiar y pegar Una salida de ejemplo de Crea

CAMPAIGN_ID=CAMPAIGN_ID

La siguiente solicitud contiene dos operaciones. El primer intento de cambiar de ofertas de la campaña proporcionada y la siguiente intenta quitar un campaña con un ID no válido. Dado que la segunda operación da como resultado un error (el el ID de la campaña no es válido) y como partialFailure se estableció en false, el primera operación también falla, y la estrategia de oferta de la campaña existente es sin actualizar.

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 a encadenan una secuencia de operaciones que deben realizarse en grupo. El conjunto de operaciones se realiza de forma correcta si ninguna operación falla o si todas fallan si alguna falla una sola operación.

Este ejemplo demuestra cómo crear el presupuesto de una campaña, una campaña, un grupo de anuncios y un solo conjunto de acciones. Cada operación sucesiva depende en el 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 el recurso. y se completan de forma dinámica en el tiempo de ejecución con los resultados de la secuencia de las 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

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. Un cliente nuevo se crea 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 proporcionado. Sin administrador o IDs de cuentas de cliente deben usarse 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 Activos. Los datos binarios, como una imagen, se codifican de la siguiente manera: Una cadena que usa la codificación Base64 estándar con relleno. Ya sea estándar o Se acepta la codificación Base64 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, el Las cargas útiles de data son mucho más grandes.

Usa la utilidad de línea de comandos base64 (parte de 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'
      }
    }
  }
]
}"
Anterior
Otros métodos
Siguiente
Pruébalo