预算订单服务

此服务仅适用于已列入白名单并且设置为按月帐单结算的 AdWords 经理帐号。有关在经理帐号中使用此服务的详情,请与您的 Google 代表联系。

利用 BudgetOrderService (BOS),已批准的经理帐号可以为他们通过合并结算管理的客户帐号以编程方式创建帐号级预算。这样,客户帐号就可以向经理的结算帐号收取费用。

使用 API,经理可以为客户帐号创建和管理设定帐号级预算的 BudgetOrder 对象。每个 BudgetOrder 又与一个代表着帐单设置的 BillingAccount 相关联,客户的费用帐单将发送到此帐单设置中指定的帐号。经理可以将多个客户帐号中的 BudgetOrder 对象添加到同一 BillingAccount 上,以便将费用合并到单个帐单设置上。

术语

以下是使用 BOS 配置结算时要记住的主要术语。

客户帐号
包含广告系列和广告组,可以进行投放广告等操作的常规 AdWords 帐号。您也可能会看到有些材料中将其称为“客户”或“客户帐户”,但本指南采用“客户帐号”这一术语,以免与“结算客户”这一术语混淆。
结算帐号
随着时间的推移,需要创建相关帐单,而这时所需用到的一些通用信息就包含在结算帐号(也称为帐单“设置”)中。例如,其中可包括帐单所用的币种、应接收和支付帐单的实体以及可以打印在帐单上以便于参考的显示名。
  • 结算帐号可以在 AdWords 网络界面中进行修改,但无法通过 AdWords API 进行创建或修改。
  • 请注意,“结算帐号”中的“帐号”一词并非指这是用于结算的一种特殊客户帐号,而是指这是一个对象,用于保存相关帐单所用的通用信息。
  • 它们在 BOS 中以一个 BillingAccount 加以表示。
  • 可以使用 BillingAccount 中的 id 字段和 BudgetOrder 中的 billingAccountId 字段来引用它们。
预算订单
是对特定客户帐号的一种授权,允许其在某一段时间内支出一定的金额,同时将这笔支出计入特定结算帐号。
  • 例如,预算订单可能会显示“授权 AdWords 帐号 123-456-7890 在 8 月最多支出 100 美元,并且应使用结算帐号 1212-1234-3434-3434 中的信息开具这笔支出的帐单。”
  • 同一个结算帐号可用于不同客户帐号中的不同预算订单。换句话说,您可以通过将不同客户帐号的预算订单设置为指向同一个结算帐号,让这些帐号将其支出累积到同一个帐单(即合并帐单)上。
  • 在 BOS 中以一个 BudgetOrder 加以表示。
结算客户
可以实际接收和支付帐单的法律实体,类似于我们旧版结算系统中的法定客户。
  • 可以通过联系您的客户服务代表来创建结算客户。在至少创建一个结算客户并将其与您的经理帐号相关联后,您就可以开始以编程方式管理 BudgetOrder。
  • 可以使用 BillingAccountBudgetOrder 上的 primaryBillingId 字段加以引用。

经理-客户关系

由于 BOS 专供经理帐号使用,因此一定要了解发送请求的经理帐号与请求所作用于的客户帐号之间的区别。

  • 经理 - 属于经过身份验证的 API 用户的经理帐号。
  • 客户 - 在请求标头字段中设置的 clientCustomerId 所对应的客户帐号。

通过联系您的客户服务代表,便可将结算客户与特定经理帐号相关联。然后即可为客户帐号创建 BudgetOrder,条件是发出 API 请求的经理:

  • 可以访问拥有特定结算客户的经理帐号。
  • 可以访问应使用结算客户的客户帐号。
  • 已列入 BudgetOrderService 的白名单。

例如,因为顶级经理帐号可以访问经理帐号 B、经理帐号 C 和客户帐号,通过验证上面的经理帐号 A,您可以向与树中任何经理帐号相关联的 BillingAccounts 添加客户 123-456-7890

您应该使用可用的最高级别经理帐号进行身份验证,以确保您可以访问要管理的经理和客户帐号。

列出可用的 BillingAccount

您可以使用 BudgetOrderService 的 getBillingAccounts() 操作提取已通过身份验证的经理可访问的 BillingAccounts 列表。每个 BillingAccount 对象都代表与目标客户帐号的经理的经理帐号相关联的帐单设置。这些是目标客户帐号的 BudgetOrders 可以使用的 BillingAccount

例如,要获取客户 123-456-7890 可以使用的 BillingAccounts 的列表,您可以通过认证为其父经理帐号之一来调用 getBillingAccounts()。使用 Java 与我们的客户端库,您可以使用以下代码:

session.setClientCustomerId("123-456-7890");
BudgetOrderServiceInterface bos = services.get(session, BudgetOrderServiceInterface.class);
BillingAccount[] accts = bos.getBillingAccounts();

认证为哪个经理可以影响对 getBillingAccounts() 的调用返回哪个 BillingAccounts。该操作将返回与特定客户的所有经理相关联的 BillingAccounts。但是,它只会遍历到与已验证经理相同的那一层次结构。

例如,如果上述两个经理帐号 AC 都有活动 BillingAccounts,作为 AclientCustomerId 123-456-7890 调用 getBillingAccounts() 将返回两组帐号。但是,如果作为 C 进行调用,则只会显示 CBillingAccounts

每个 BillingAccount 对象都有 IDprimaryBillingIdID 唯一标识 BillingAccount,在其他对象中称为 billingAccountIdprimaryBillingId 表示支付帐单费用的结算客户。

primaryBillingId 还在 AdWords 界面结算 > 结算设置下被标记为“付款人”。

创建新的 BudgetOrder

要将客户添加到其中一个可访问的 BillingAccounts,请创建 BudgetOrder 以建立帐号级预算,其中包括客户的开始时间、结束时间和支出限额等详细信息。

在提取到上述可用的 BillingAccounts 之后,您可以使用上一个示例中返回的第一个 BillingAccount,为 8 月份创建新的帐号级预算,支出上限为 100 美元:

BillingAccount acct = accts[0];
BudgetOrder order = new BudgetOrder();
order.setBillingAccountId(acct.getId());
order.setStartDateTime("20140801 000000 America/New_York");
order.setEndDateTime("20140831 235959 America/New_York");
Money amt = new Money();
amt.setMicroAmount(100000000L);  // $100 in micros
order.setSpendingLimit(amt);

BudgetOrderOperation op = new BudgetOrderOperation();
op.setOperator(Operator.ADD);
op.setOperand(order);
BudgetOrderReturnValue response = bos.mutate(new BudgetOrderOperation[] {op});

从 mutate 操作返回的 BudgetOrderReturnValue 将包含新的 BudgetOrder 的 ID。BudgetOrder 将包含 lastRequest 字段,其中包含有关请求状态的信息。新提交的 BudgetOrder 的状态为 UNDER_REVIEW,直到它们获得批准并生效。

新的 BudgetOrders 可能需要一些时间(通常不到一个小时)才能生效,因此最好早于它们预期的 startDateTime,提前创建。虽然一个客户一次只能有一个活动 BudgetOrder,但可以随时创建未来的预算,并将其排入队列。例如,在上面为 clientCustomerId 123-456-7890 创建 8 月的 BudgetOrder 之后,您可以立即该客户创建 9 月和 10 月的 BudgetOrder

任意时刻只能有一个 BudgetOrder 有效,因此请确保新 BudgetOrderstartDateTimeendDateTime 字段没有落在任何其他现有 BudgetOrder(活动或未来待处理)的持续时间内。注意,startDateTimeendDateTime 定义了一个闭合间隔:BudgetOrder 的持续时间包括 startDateTimeendDateTime 在内。在上面的例子中,endDateTime20140831 235959 America/New_York,因此它不会与 startDateTime20140901 000000 America/New_York 的未来可能的 9 月 BudgetOrder 重叠。如果您尝试创建其持续时间与同一帐号的另一个 BudgetOrder 重叠的 BudgetOrder,您将收到 INVALID_BUDGET_DATE_RANGE 错误。

如上例所示,指定的 startDateTimeendDateTime 精确到秒。对于大多数使用情况,时区应为客户的 dateTimeZone

修改 BudgetOrder

您可以通过在 mutate 操作中引用现有 BudgetOrder 的 ID 来更新该 BudgetOrder。因为对可以使用给定 BillingAccountBudgetOrder 的数量有限制,所以最好更新现有的 BudgetOrder,而不是去新建一个。

您可以使用新的 spendingLimitendDateTime 值更新现有的 BudgetOrder 对象,从而增加上一节中创建的帐号级预算的支出限额和持续时间:

Long existingId = response.getValue()[0].getId();
BudgetOrder existingOrder = new BudgetOrder();
existingOrder.setId(existingId);
Money newAmt = new Money();
newAmt.setMicroAmount(200000000L);
existingOrder.setSpendingLimit(newAmt);
existingOrder.setEndDateTime("20140930 235959 America/New_York");

BudgetOrderOperation op = new BudgetOrderOperation();
op.setOperator(Operator.SET);
op.setOperand(order);
bos.mutate(new BudgetOrderOperation[] {op});

也可以减少 BudgetOrder 的支出限额,但是,您不能将其设置为低于订单已支出的金额。

支出限额和调整

改变 BudgetOrder 的支出限额时,一定要注意调整项。调整项是应用于预算订单的抵免额,可使您的支出超过正常支出限额,而不会被收取费用。

mutate() 请求中,支出限额不会考虑任何调整项。您发送的值是您在调整前愿意支出的金额。但是,对于 get() 请求,spendingLimit 包括对您的 BudgetOrder 所做的任何调整。如果您尝试相对于之前提交的支出限额设置支出限额,请务必将调整项考虑在内。

移除 BudgetOrder

结束 BudgetOrder 的方法可以是等待其达到支出时间段的结束点,也可以是主动取消。BudgetOrder 结束后,需要创建新的订单,才能重新启用客户帐号的支出。

可以通过 API 发送 REMOVE 请求来取消活动的 BudgetOrder。这将确切地将其 endDateTime 设置为当前时间,从而结束预算时间段并防止进一步支出。

BudgetOrder o = new BudgetOrder();
o.setId(budgetOrderId);
BudgetOrderOperation op = new BudgetOrderOperation();
op.setOperator(Operator.REMOVE);
op.setOperand(o);
bos.mutate(new BudgetOrderOperation[] {op});

更改结算客户

您可以更改为客户帐号支出进行支付的底层结算客户,方法是创建一个 BudgetOrder,让其指向新结算客户的某个 BillingAccounts。然而,对于任何给定的客户帐号,只能有一个这类收单方信息变更 (CBT) 操作可以待处理。

例如,要更改在 8 月 BudgetOrder 到期后为客户 123-456-7890 支付费用的客户,您可以为 9 月添加使用与新结算客户相关的 BillingAccount 的新 BudgetOrder;然而,所有后续的 BudgetOrders 必须使用该新的结算客户,原因在于对客户帐号仅可以安排一个 CBT 操作。

限制

说明 错误 备注
每个 BillingAccountBudgetOrder 对象数 75000 BudgetOrderError.GENERIC_BILLING_ERROR, trigger: TOO_MANY_ORDER_LINES_NEW_BILLING_ACCOUNT_REQUIRED

每个 BillingAccount 最多有 75000 个 BudgetOrders

如果您已达到此上限,请在 AdWords 界面中创建新的帐单设置,并将未来的 BudgetOrders 添加到新的 BillingAccount

每个 mutate 请求的操作数 1 BudgetOrderError.MORE_THAN_ONE_OPERATIONS 多个操作需要在单独的请求中发送。
每秒请求数 1 RateExceededError.RATE_EXCEEDED

此服务的速率限制为 1 qps。

确保请求的速度不超过每秒 1 个,且避免发送并发请求。

常见错误

错误 备注和解决办法
BudgetOrderError.INVALID_BUDGET_DATE_RANGE, trigger: Overlapping budget found

无法创建重叠的 BudgetOrder 对象。

更改 BudgetOrderstartDateTimeendDateTime,使其不与其他活动预算或待处理预算重叠。

如果您尝试通过 AdWords 界面创建新的预算订单,可能是因为这个过程尚未完成,因此有一个待处理预算订单处于打开状态。请在界面中完成订单创建过程,或与 AdWords API 支持团队联系以获得帮助。

BudgetOrderError.INVALID_BUDGET_ALREADY_SPENT

无法将支出限额设置为低于在给定时间段内已支出的金额。

BudgetOrderspendingLimit 设置为大于在 BudgetOrderstartDateTimeendDateTime 之间已经支出的值。

BudgetOrderError.CUSTOMER_NOT_WHITELISTED_FOR_NEW_BILLING

经理帐号未启用合并结算。

请与您的 Google 代表联系,为您的帐号启用合并结算。

NotWhitelistedError.CUSTOMER_NOT_WHITELISTED_FOR_API

经理帐号未列入可使用 BudgetOrderService API 的白名单。

有关 API 服务访问权限的信息,请与您的 Google 代表联系。

发送以下问题的反馈:

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