注意：您正在查看 API 的 REST 接口的文档。我们的大多数官方客户端库都使用 gRPC。如需了解详情，请参阅 REST 简介。

此页面由 Cloud Translation API 翻译。

示例

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

前提条件

下面的所有示例都旨在使用 curl 命令复制并粘贴到 bash shell 中。

此外，您还需要拥有开发者令牌、测试帐号访问权限以及至少包含一个客户帐号的 Google Ads 经理帐号。

环境变量

在下方输入帐号凭据和 ID，然后复制并粘贴到您的终端，以配置后续示例中使用的环境变量。授权指南提供了有关如何生成 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"

其他可选对象 ID

下面的一些示例适用于预先存在的预算或广告系列。如果您有要用于这些示例的现有对象的 ID，请在下面输入。

BUDGET_ID=BUDGET_ID
CAMPAIGN_ID=CAMPAIGN_ID

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

搜索

查询实战宝典指南包含许多报告示例，这些示例对应于一些默认 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 "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 请求正文中发送多项 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 "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 方法用于上传和管理 Assets。二进制数据（例如图像）使用带填充的标准 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'
      }
    }
  }
]
}"

其他方法

试试看！