Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

示例

本指南包含直接调用 REST 端点（不使用客户端库）的示例。

如需查看更详细的代码示例，请参阅 REST 代码示例 GitHub 代码库。

如需查看每个 API 方法的请求和响应正文，请参阅特定服务端点的参考文档。

例如，GoogleAdsService.Search 的参考页面显示了 Search 方法的请求和响应正文。

前提条件

此处显示的所有示例都旨在通过 curl 命令复制并粘贴到 bash shell 中。

您还需要一个 Google Cloud 项目（测试账号访问权限即可）以及一个至少包含一个客户账号的 Google Ads 经理账号。

环境变量

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

API_VERSION="26"
OAUTH2_ACCESS_TOKEN="OAUTH_ACCESS_TOKEN"
MANAGER_CUSTOMER_ID="MANAGER_CUSTOMER_ID"
CUSTOMER_ID="CUSTOMER_ID"

其他可选对象 ID

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

BUDGET_ID=BUDGET_ID
CAMPAIGN_ID=CAMPAIGN_ID

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

搜索

查询指南包含许多报告示例，这些示例对应于一些默认的 Google Ads 界面，并使用本指南中使用的相同环境变量。我们的交互式查询构建器工具也是以交互方式构建自定义查询的绝佳资源。

分页

search 方法使用分页，固定页面大小为 10,000 项，并与 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 "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 "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 请求正文中发送多个 mutate 操作（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 "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 "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 "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 "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 "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 "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 "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。

curl -f --request GET "https://googleads.googleapis.com/v${API_VERSION}/customers:listAccessibleCustomers" \
--header "Content-Type: application/json" \
--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 "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'
      }
    }
  }
]
}"

常见错误

试试看！

示例 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

前提条件

环境变量

其他可选对象 ID

搜索

分页

curl

GAQL

流式

curl

GAQL

转变

创建

更新

移除

部分失败

分组操作

账号管理

创建账号

列出可访问的账号

上传二进制资源

示例