管理帐号

本指南介绍如何使用 AdWords API 管理 AdWords 帐号,包括经理帐号、客户帐号和测试帐号。

本指南假设您已熟悉 AdWords 经理帐号和客户帐号。如果您需要回顾一下有关 AdWords 帐号和访问权限级别的基础知识,请参阅 AdWords 帮助中心内的经理帐号访问权限级别页。

创建和组织帐号

CustomerServiceManagedCustomerService 这两项 API 服务用来创建帐号、获取帐号信息和管理帐号之间的关联。要管理帐号标签,请使用 AccountLabelService

CustomerService

CustomerService 提供有关您的帐号的信息。它有一个不接受任何参数的 getCustomers() 方法,该方法返回一个由包含诸如 customerIdcurrencyCodedateTimeZone 等字段的 Customer 对象组成的列表。CustomerService 还有一个 mutate() 方法,该方法可用于更新客户的各种属性,包括 autoTaggingEnabledconversionTrackingSetting 字段。

在 v201605 及更早的版本中,如果未指定 clientCustomerId,则响应中将包含一个与通过验证的帐号对应的条目。在以经理帐号身份接受身份验证时,您必须指定 clientCustomerId,才能获取特定帐号的信息(有关详情,请参阅下文中的身份验证)。

从 v201607 开始,如果未指定 clientCustomerId,且通过身份验证的帐号可以直接访问多个帐号,则响应中将包含多个条目。如果仅需要单个帐号的结果,则必须在请求中指定 clientCustomerId

响应示例:

<rval>
   <customerId>123456789</customerId>
   <currencyCode>USD</currencyCode>
   <dateTimeZone>America/New_York</dateTimeZone>
   <descriptiveName>myaccount</descriptiveName>
   <canManageClients>false</canManageClients>
</rval>

参考文档包含货币时区值的列表。

ManagedCustomerService

ManagedCustomerService 还有一个 get() 方法和一个通用选择器。与 CustomerService 相比,有更多字段可供选择:有关详细信息,请参阅参考文档。

除了符合选择器中条件的帐号列表外,您还将获取一份 ManagedCustomerLink 对象列表,这些对象用于描述帐号之间的关系。

<rval>
 <totalNumEntries>3</totalNumEntries>
 <Page.Type>ManagedCustomerPage</Page.Type>
 <entries>
    <name>Account Created with MCS</name>
    <login/>
    <companyName/>
    <customerId>789</customerId>
    <canManageClients>false</canManageClients>
    <currencyCode>ZAR</currencyCode>
    <dateTimeZone>Pacific/Pago_Pago</dateTimeZone>
 </entries>
 <entries>
    <name>Adwords Test Manager Account</name>
    <login>my-manager-account@example.com</login>
    <companyName/>
    <customerId>123</customerId>
    <canManageClients>true</canManageClients>
    <currencyCode>USD</currencyCode>
    <dateTimeZone>America/New_York</dateTimeZone>
 </entries>
 <entries>
    <name>myaccount</name>
    <login>myaccount@example.com</login>
    <companyName/>
    <customerId>456</customerId>
    <canManageClients>false</canManageClients>
    <currencyCode>USD</currencyCode>
    <dateTimeZone>America/New_York</dateTimeZone>
 </entries>
 <links>
    <managerCustomerId>123</managerCustomerId>
    <clientCustomerId>456</clientCustomerId>
 </links>
 <links>
    <managerCustomerId>123</managerCustomerId>
    <clientCustomerId>789</clientCustomerId>
 </links>
</rval>

ManagedCustomerService 还用于创建新帐号。这些新帐号将属于有效用户,该有效用户必须同时是经理帐号。以下是请求示例:

<operations>
  <operator>ADD</operator>
  <operand>
    <name>Foo</name>
    <currencyCode>USD</currencyCode>
    <dateTimeZone>America/New_York</dateTimeZone>
  </operand>
</operations>

响应示例:

<rval>
  <value>
    <name>Foo</name>
    <customerId>9876543210</customerId>
    <canManageClients>false</canManageClients>
    <currencyCode>USD</currencyCode>
    <dateTimeZone>America/New_York</dateTimeZone>
  </value>
</rval>

companyNamelogincanManageClients 等字段是只读的,在创建新的客户帐号时会被忽略。一旦创建了客户帐号,便无法使用 ManagedCustomerService 对其进行更新。

关联帐号

关联了经理帐号和客户帐号后,经理帐号就可以代表其客户帐号发出请求。

ManagedCustomerService 用于管理帐号之间的关联,可实现对您的帐号层次结构的自动管理:

要关联经理帐号和客户帐号,必须完成以下步骤:

  1. 经理帐号必须向客户帐号发出邀请
  2. 客户必须接受邀请

发出邀请

经理帐号可以邀请客户帐号或其他经理帐号接受管理。

在这种情况下,MANAGER_ID 可以是您在接受身份验证时作为验证身份使用的经理帐号,也可以是层次结构中的其他子级经理帐号。CLIENT_CID 必须是当前未由您层次结构中的经理帐号管理的客户帐号或经理帐号。

LinkOperation linkOp = new LinkOperation();
ManagedCustomerLink link = new ManagedCustomerLink();
link.setClientCustomerId(CLIENT_CID);
link.setLinkStatus(LinkStatus.PENDING);
link.setManagerCustomerId(MANAGER_CID);
linkOp.setOperand(link);
linkOp.setOperator(Operator.ADD);
managedCustomerService.mutateLink(new LinkOperation[]{linkOp});

发送关联状态为 PENDINGADD 操作,即可提出邀请。

获取待处理的邀请

可以使用 ManagedCustomerService.getPendingInvitations 从客户帐号或经理帐号提取未处理的邀请。在客户做出了接受或拒绝邀请的响应后,或者经理帐号撤销了邀请,则邀请不再处于待处理状态。

ManagedCustomerService.get() 调用中只会显示状态为 ACTIVE 的关联,绝不会返回状态为 CANCELLEDREFUSEDINACTIVE 的关联。

以下调用返回经理帐号的所有待处理邀请。

PendingInvitationSelector selector = new PendingInvitationSelector();
PendingInvitation[] invitations = managedCustomerService.getPendingInvitations(selector);

您还可以将 managerCustomerIdsclientCustomerIds 字段分别设置为经理帐号和客户帐号的客户 ID,以返回这些帐号的待处理邀请。请注意,clientCustomerIds 必须通过有效帐号的层次结构进行管理,才能查看其关联情况。如果该有效用户是客户帐号,那么只能查看该帐号的待处理邀请。

此请求将返回包含 ManagedCustomer 记录的 PendingInvitations。 经理和客户的 NamelogincompanyNamecustomerIdcanManageClients 字段都将被填充。

撤回邀请

如果您向客户发送了请其管理客户帐号的邀请,但后来又改变了主意,则可以撤回此邀请,具体方法为:在 SET 操作中将关联状态设置为 CANCELLED,同时将有效帐号设置为可管理此关联的经理帐号。

LinkOperation linkOp = new LinkOperation();
ManagedCustomerLink link = new ManagedCustomerLink();
link.setClientCustomerId(CLIENT_CID);
link.setLinkStatus(LinkStatus.CANCELLED);
link.setManagerCustomerId(MANAGER_CID);
linkOp.setOperand(link);
linkOp.setOperator(Operator.SET);
managedCustomerService.mutateLink(new LinkOperation[]{linkOp});

客户拒绝邀请

客户也可以拒绝邀请,只需在 SET 操作中将关联状态设置为 REFUSED 即可。有效用户必须与此请求中的 CLIENT_CID 一致,或者作为管理员所有者管理后者。

LinkOperation linkOp = new LinkOperation();
ManagedCustomerLink link = new ManagedCustomerLink();
link.setClientCustomerId(CLIENT_CID);
link.setLinkStatus(LinkStatus.REFUSED);
link.setManagerCustomerId(MANAGER_CID);
linkOp.setOperand(link);
linkOp.setOperator(Operator.SET);
managedCustomerService.mutateLink(new LinkOperation[]{linkOp});

客户接受邀请

客户通过使用 SET 将关联状态设置为 ACTIVE 来接受邀请。与拒绝邀请一样,有效用户必须与此请求中的 CLIENT_CID 一致,或者以具备管理员权限的所有者身份来管理后者。

LinkOperation linkOp = new LinkOperation();
ManagedCustomerLink link = new ManagedCustomerLink();
link.setClientCustomerId(CLIENT_CID);
link.setLinkStatus(LinkStatus.ACTIVE);
link.setManagerCustomerId(MANAGER_CID);
linkOp.setOperand(link);
linkOp.setOperator(Operator.SET);
managedCustomerService.mutateLink(new LinkOperation[]{linkOp});

如果客户或其经理决定独立管理各自的帐号,则可以终止帐号关联:使用 SETLinkStatus 设置为 INACTIVE

ManagedCustomerLink link = new ManagedCustomerLink();
link.setClientCustomerId(CLIENT_CID);
link.setLinkStatus(LinkStatus.INACTIVE);
link.setManagerCustomerId(MANAGER_CID);
linkOp.setOperand(link);
linkOp.setOperator(Operator.SET);
managedCustomerService.mutateLink(new LinkOperation[]{linkOp});

以经理帐号或客户帐号身份都可以执行上述操作。

迁移客户帐号

使用 ManagedCustomerService.mutateManager(),您可以轻松地将 AdWords 帐号从一个经理帐号迁移到另一个经理帐号。客户帐号和经理帐号都可以使用 mutateManager() 方法迁移。

MoveOperation op = new MoveOperation();
op.setOldManagerCustomerId(MANAGER_CID);
op.setOperator(Operator.SET);
ManagedCustomerLink link = new ManagedCustomerLink();
link.setClientCustomerId(CLIENT_CID);
link.setLinkStatus(LinkStatus.ACTIVE);
link.setManagerCustomerId(NEW_MANAGER_CID);
op.setOperand(link);
managedCustomerService.mutateManager(new MoveOperation[]{op});

新旧经理帐号都必须通过有效帐号加以管理。关联状态必须为 ACTIVE。需使用 NEW_MANAGER_CID 作为关联的 managerCustomerId,并在 MoveOperationoldManagerCustomerId 中指定原来的 MANAGER_CID

AccountLabelService

帐号标签有助于组织和管理帐号。通过 AccountLabelService,您可以在帐号一级添加、更新或移除标签。借助 API,您还可以管理子级经理的帐号标签。

经理帐号限制

使用经理帐号时,应该留意一些限制。您可以在系统限制参考页中找到它们,该页还完整列出了其他系统限制。

AdWords 帐号极少会接近这些限制值。如果您需要管理的 AdWords 帐号已达到任何最高限额,则您必须在关联该帐号之前先修正这些问题。

此外,请注意不要超过操作速率限制

身份验证

针对 AdWords API 进行的调用需要已批准的开发者令牌以及在 OAuth2 中为目标帐号生成的凭据。

最简单的方法是以经理帐号身份接受身份验证。验证通过后,您就可以访问该经理帐号下的所有帐号。身份验证使用 OAuth2 加以处理。

开发者令牌

在您注册 AdWords API 时,系统会自动为您生成一个开发者令牌。在您提出申请后,令牌立刻进入待审批状态。

While waiting for token approval, you'll be able to make calls against test accounts.在令牌获得批准后,您可以指定在生产环境中使用的目标 AdWords 帐号。

OAuth2 凭据

每次向 AdWords API 发出的请求都必须获得授权,才能更改或提取指定 AdWords 帐号的数据。用于 API 调用的 OAuth2 凭据决定了您可以针对哪些帐号发出调用。

使用经理帐号凭据发出的调用可以以经理帐号或您拥有 OAuth2 凭据的任何帐号为调用目标。例如,让我们看一个典型的 AdWords 帐号层次结构:

您的开发者令牌可以属于根经理帐号 1,甚至可以属于另一个层次结构中的其他经理帐号:只要您提供目标帐号的客户 ID,就不会影响您可以指定哪些目标帐号。

要对客户帐号 A 进行 API 调用,您可以使用与客户帐号 A 关联的登录信息的 OAuth2 凭据,并将 clientCustomerId 请求标头设置为客户 A、经理帐号 2 或根经理帐号 1 的客户 ID。

在此结构中,经理帐号 3 只能调用客户帐号 C,不能调用客户帐号 A 或 B,原因是该经理帐号并不管理后两者。根经理帐号 1 可以对该层次结构中的任何帐号进行调用。

使用经理帐号凭据进行的调用只能针对该经理帐号或层次结构中位于其下的帐号。因此,在这一层次结构中,只有根经理帐号 1 可以对客户帐号 D 进行调用。

如果您使用任一经理帐号,请将 clientCustomerId 设置为该经理帐号或其某个子级帐号。

测试帐号

经理和客户帐号有助于进行组织整理,但如何做到测试实验性更改或在开发时测试 API 调用,同时又不影响您的生产环境?这就是测试帐号的用武之地。

测试帐号允许您在生产环境中实施更改之前试用新的 API 实现或帐号配置。

可以在层次结构中设置测试帐号,并且像组织生产帐号一样组织它们,但测试帐号可在动态开发期间提供一些额外的优势。特别是,测试帐号有以下特点:

  • 不需要经过批准的开发者令牌,因此即使您的申请还没有得到审核或批准,您都可以立即开始试验 API。
  • 无法以任何方式投放广告或与您的生产帐号互动。
  • 可以在 AdWords 网络界面中查看和操作,就像常规帐号一样。

由于测试帐号与生产帐号不能以任何方式互动,因此您不能在现有生产经理帐号下使用测试帐号。要使用测试帐号,您需要一个新的帐号层次结构,并以测试经理帐号为根帐号。

可通过 AdWords 网络界面访问测试帐号,这类帐号会带红色标签(请参阅下文)。

测试帐号与生产帐号受同样的限制(包括速率限制)。

开始使用测试帐号

在向测试帐号发出 API 请求之前,请确保您还具有生产(非测试)经理帐号和开发者令牌(即使该令牌仍在等待审批)。

使用生产经理帐号,必须先创建测试经理帐号,然后再创建测试客户帐号。在测试经理帐号下创建的所有客户帐号将自动标记为测试帐号。

要创建和使用测试帐号,请按以下步骤操作:

  1. 如果您还没有生产经理帐号和/或生产经理开发者令牌:
    1. 创建生产经理帐号(例如,production-manager@mycompany.example.com
    2. 在生产经理帐号中请求开发者令牌
  2. 创建测试经理帐号(例如,test-manager@mycompany.example.com)。要创建测试帐号,您必须拥有尚未关联到 AdWords 帐号的 Google 帐号。您可以在 accounts.google.com 中创建新的 Google 帐号。
  3. 在针对测试经理帐号提出请求时使用生产经理帐号的开发者令牌。
  4. 请求 OAuth2 刷新令牌时,请确保您以测试经理帐号用户身份登录(例如 test-manager@mycompany.example.com

下表说明了处于各种审批状态的不同 AdWords 帐号类型与开发者令牌之间所允许的互动:

生产开发者令牌状态 AdWords 帐号类型 是否允许
待审批 测试
待审批 非测试
已批准 测试
已批准 非测试

将 OAuth2 与测试帐号配合使用

要使用 OAuth2 访问测试帐号,测试经理帐号用户必须向您的客户端应用授予权限。因此,当请求刷新令牌时,请确保以测试经理帐号而不是生产经理帐号登录。

当您要从测试经理帐号切换到生产经理帐号时,只需重新配置客户端库即可使用生产经理帐号的刷新令牌。

请求标头

对测试帐号的所有请求应作为生产请求发送到同一端点:

https://www.googleapis.com/auth/adwords/

请求和响应 SOAP 标头与生产帐号中返回的标头相同。对于授权标头,请务必使用您的测试帐号凭据。

测试帐号的其他特征

使用测试帐号时,请注意以下几点:

用测试帐号开发

通过注册申请 AdWords API 访问权限时,系统可能会要求您演示应用的某些功能。报告就是这样的一个功能,仅使用测试帐号可能难以模拟该功能。

由于测试帐号不投放广告进行展示,因此不会生成任何指标。您仍可以下载结构化报告,但您将只会看到展示次数为零的行,也就是说细分不会起作用。

我们建议显示伪数据,作为一种权宜之计。令牌审核团队需要看到您的应用可以显示报告数据并与之互动。通过模拟报告调用(即假装报告调用成功,并使用包含模拟报告数据的本地文件),您可以添加报告数据,而无需通过 API 实际获取这类数据。

确保您的测试报告数据格式正确。例如,如果您生成的广告系列效果报告包含日期、广告系列名称、广告系列 ID、展示次数、点击次数和费用,则您会看到类似下面内容的文件:

"CAMPAIGN_PERFORMANCE_REPORT (Mar 20, 2013-Mar 23, 2013)"
Day,Campaign,Campaign ID,Impressions,Clicks,Cost
20130320,Widgets,123,1211,19,14.92
20130320,Sprockets,456,300,4,2.92
20130321,Widgets,123,901,12,9.86
20130321,Sprockets,456,340,5,3.86
20130322,Widgets,123,1065,16,11.23
20130322,Sprockets,456,509,6,5.23
20130323,Widgets,123,1005,15,10.12
20130323,Sprockets,456,287,3,1.12

通过构造这样的文件并将其存储在本地,您的应用可以模拟对 API 的调用。当请求报告时,返回存储的文件并对其进行处理,而不是进行实际的 API 调用。您可以为要显示的每个报告创建一个这样的文件。

使用生产数据进行测试

如果您在请求中使用 validateOnly 标头,并且您拥有已批准的开发者令牌,则您可以在生产帐号上以只读方式使用生产数据进行测试。

发送以下问题的反馈:

此网页
AdWords API
AdWords API
需要帮助?请访问我们的支持页面