示例

本指南包含一些示例，展示了如何在不使用客户端库的情况下直接调用 REST 端点。

前提条件

以下所有示例都应使用 curl 命令复制并粘贴到 bash shell 中。

您还需要一个开发者令牌（测试账号访问权限即可），以及一个包含至少一个客户账号的 Google Ads 经理账号。

重要提示： 在这些示例中，我们假设您是通过对直接管理客户账号的经理账号 (MANAGER_CUSTOMER_ID) 拥有管理员权限的用户来访问客户账号 (CUSTOMER_ID)。如果您要直接访问单个客户账号，请省略 login-customer-id 标头或将其设置为与 CUSTOMER_ID 相同的值。请注意，某些示例（例如创建账号）需要经理账号。

环境变量

在下方输入账号凭据和 ID，然后复制并粘贴到终端，以配置后续示例中使用的环境变量。授权指南提供了有关生成 OAuth 2.0 访问令牌的说明。

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

其他可选对象 ID

以下示例中的某些示例适用于现有预算或广告系列。如果您有要与这些示例搭配使用的现有对象的 ID，请在下方输入这些 ID。

BUDGET_ID=BUDGET_ID
CAMPAIGN_ID=CAMPAIGN_ID

否则，两个 Mutates - Creates examples 会创建新的预算和广告系列。

搜索

查询食谱指南包含许多与部分默认 Google Ads 界面对应的报告示例，并且与本指南中使用的环境变量兼容。我们的交互式查询构建器工具也是构建交互式自定义查询的绝佳资源。

分页

search 方法使用分页，固定页面大小为 1 万个项，并在 query 旁边指定 page_token。

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'

流式

searchStream 方法会在单个响应中流式传输所有结果，因此不支持 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'

转变

您可以通过填充 operations 数组，在单个 JSON 请求正文中发送多个更改操作 (create、update 或 remove)。

创建

此示例会在单个请求中创建两个共享广告系列预算。

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,
    }
  }
]
}"

下一个示例使用现有广告系列预算的 BUDGET_ID；您可以从上一步的输出中复制并粘贴。

BUDGET_ID=BUDGET_ID

引用其他资源的资源是通过资源名称进行引用的。下面创建的广告系列会通过其字符串值资源名称引用 campaignBudget。

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': {}
    }
  }
]
}"

更新

使用 update 运算更新现有对象的属性。下一个示例使用现有广告系列；您可以从上一步的输出中复制并粘贴。

CAMPAIGN_ID=CAMPAIGN_ID

所有更新都需要 updateMask 字段，该字段是一个逗号分隔的列表，其中列出了应在请求中作为更新应用的 JSON 属性。updateMask 中列出但请求正文中不存在的属性会从对象中清除。updateMask 中未列出但请求正文中存在的属性将被忽略。

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'
  }
],
}"

移除

通过将对象的资源名称指定为 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}'
  }
],
}"

部分失败

在单个请求中执行多项操作时，可以选择指定 partialFailure。如果为 true，则执行成功的操作，无效的操作会返回错误。如果为 false，则当且仅当请求中的所有操作都有效时，请求中的所有操作才会成功。

下一个示例使用现有广告系列；您可以从创建示例输出中复制并粘贴。

CAMPAIGN_ID=CAMPAIGN_ID

以下请求包含两项操作。第一个尝试更改所提供广告系列的出价策略，而下一个尝试移除 ID 无效的广告系列。由于第二个操作会导致错误（广告系列 ID 无效），并且 partialFailure 已设为 false，因此第一个操作也会失败，并且现有广告系列的出价策略不会更新。

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

分组操作

googleAds:mutate 方法支持发送包含多种类型资源的一组操作。您可以发送许多不同类型的操作，以串联一系列应作为一组执行的操作。如果没有任何操作失败，则这组操作会成功；如果任何单个操作失败，则所有操作都会失败。

此示例演示了如何将广告系列预算、广告系列、广告组和广告作为一组操作一起创建。每项后续操作都依赖于前一项操作。如果其中一个操作失败，整个操作组都会失败。

负整数（-1、-2、-3）在资源名称中用作占位符，并会在运行时使用操作序列的结果进行动态填充。

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

账号管理

创建账户

使用 createCustomerClient 方法创建新账号。请注意，网址需要使用经理账号 ID，而不是客户账号 ID。系统会在经理账号下创建一个新的客户账号。

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

列出可访问的账号

对 listAccessibleCustomers 方法发出简单的 GET 请求，即可获取可使用给定 OAuth 2.0 访问令牌访问的 Google Ads 账号的列表。此请求中不应使用经理账号 ID 或客户账号 ID。

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}" \

上传二进制资源

assets:mutate 方法用于上传和管理素材资源。二进制数据（例如图片）使用带填充的标准 base64 编码编码为字符串。我们接受标准或网址安全型 base64 编码（无论是否填充）。

此示例编码了 1 像素的 GIF，以使示例简洁明了。实际上，data 载荷要大得多。

使用 base64 命令行实用程序（属于 GNU 核心实用程序）编码1 像素 GIF 图片。

base64 1pixel.gif

base64 编码的值在 API 请求中指定为 data 属性。

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