示例

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

本指南中的脚本位于 REST 代码示例 GitHub 代码库中,包括 rest_guide 目录。

如需查看每个 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”示例会创建新的预算和广告系列。

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

分页

search 方法使用分页,固定页面大小为 10,000 项,并与 query 一起指定 page_token。

对于第一个请求,请将 PAGE_TOKEN 留空。如需获取下一页,请将 PAGE_TOKEN 设置为上一个响应中的 nextPageToken 值,然后再次运行请求。

PAGE_TOKEN=""

curl

curl --compressed --fail-with-body --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 @- <<EOF
{
  "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}"
}
EOF

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 --compressed --fail-with-body --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 @- <<'EOF'
{
  "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'
  "
}
EOF

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 --compressed --fail-with-body --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 @- <<EOF
{
  "operations": [
    {
      "create": {
        "name": "My Campaign Budget #${RANDOM}",
        "amountMicros": 500000
      }
    },
    {
      "create": {
        "name": "My Campaign Budget #${RANDOM}",
        "amountMicros": 500000
      }
    }
  ]
}
EOF

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

BUDGET_ID=BUDGET_ID

引用其他资源的资源通过资源名称进行引用。以下示例中创建的广告系列通过其字符串值资源名称引用 campaignBudget。

curl --compressed --fail-with-body --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 @- <<EOF
{
  "operations": [
    {
      "create": {
        "status": "PAUSED",
        "advertisingChannelType": "SEARCH",
        "geoTargetTypeSetting": {
          "positiveGeoTargetType": "PRESENCE_OR_INTEREST",
          "negativeGeoTargetType": "PRESENCE"
        },
        "name": "My Search campaign #${RANDOM}",
        "campaignBudget": "customers/${CUSTOMER_ID}/campaignBudgets/${BUDGET_ID}",
        "targetSpend": {},
        "containsEuPoliticalAdvertising": "DOES_NOT_CONTAIN_EU_POLITICAL_ADVERTISING"
      }
    }
  ]
}
EOF

更新

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

CAMPAIGN_ID=CAMPAIGN_ID

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

curl --compressed --fail-with-body --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 @- <<EOF
{
  "operations": [
    {
      "update": {
        "resourceName": "customers/${CUSTOMER_ID}/campaigns/${CAMPAIGN_ID}",
        "name": "A changed campaign name #${RANDOM}"
      },
      "updateMask": "name"
    }
  ]
}
EOF

移除

通过将对象的资源名称指定为 remove 操作来移除对象。

curl --compressed --fail-with-body --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 @- <<EOF
{
  "operations": [
    {
      "remove": "customers/${CUSTOMER_ID}/campaigns/${CAMPAIGN_ID}"
    }
  ]
}
EOF

部分失败

如果单个请求中包含多项操作,您可以选择指定 partialFailure。如果为 true,则系统会执行成功的操作,而无效的操作会返回错误。如果为 false,则当且仅当请求中的所有操作都有效时,这些操作才会成功。

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

CAMPAIGN_ID=CAMPAIGN_ID

以下请求包含两项操作:第一项操作在指定广告系列中停用智能点击付费,第二项操作尝试移除 ID 无效的广告系列。由于 partialFailure 字段设置为 true,因此第一个操作成功,而响应会在 partialFailureError 字段中返回无效的第二个操作的错误。

curl --compressed --fail-with-body --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 @- <<EOF
{
  "partialFailure": true,
  "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"
    }
  ]
}
EOF

已分组的操作

googleAds:mutate 方法支持发送包含多种资源类型的操作组。您可以发送许多不同类型的操作,将应作为一个组执行的一系列操作链接在一起。如果没有任何操作失败,则该组操作成功;如果任何单个操作失败,则所有操作都失败。

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

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

curl --compressed --fail-with-body --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 @- <<EOF
{
  "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"
          },
          "name": "My Search campaign #${RANDOM}",
          "campaignBudget": "customers/${CUSTOMER_ID}/campaignBudgets/-1",
          "targetSpend": {},
          "containsEuPoliticalAdvertising": "DOES_NOT_CONTAIN_EU_POLITICAL_ADVERTISING"
        }
      }
    },
    {
      "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": [
                {
                  "pinnedField": "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"
            ]
          }
        }
      }
    }
  ]
}
EOF

账号管理

您可以创建账号、列出可访问的账号以及上传二进制资源。

创建账号

使用 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 @- <<EOF
{
  "customerClient": {
    "descriptiveName": "Account created with CustomerService #${RANDOM}",
    "currencyCode": "USD",
    "timeZone": "America/New_York"
  }
}
EOF

列出可访问的账号

使用对 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 字符串。该 API 接受标准或网址安全的 base64 编码(带或不带填充)。

此示例对 1 像素 GIF 图片进行编码,以使载荷保持简洁。在实际应用中,data 载荷要大得多。下载图片并使用 base64 命令行实用程序对其进行编码:

curl -sLO https://developers.google.com/google-ads/api/images/1pixel.gif
IMAGE_CONTENT="$(base64 < 1pixel.gif | tr -d '[:space:]')"

在 assets:mutate 请求的 data 字段中发送 base64 编码值:

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 @- <<EOF
{
  "operations": [
    {
      "create": {
        "imageAsset": {
          "data": "${IMAGE_CONTENT}"
        },
        "name": "Marketing Image"
      }
    }
  ]
}
EOF