附加地址信息

借助 AdWords 附加地址信息,可以随广告文字一起显示您的商家地址、电话号码和地图标记。附加地址信息自推出以来发生了一些重大变化。在 2014 年年中之前,一直使用旧版附加地址信息和 CampaignAdExtensionService 管理营业地点信息。在此之后,您既可以通过 Google 我的商家管理地点,并将其与 AdWords 相关联,也可以通过升级版手动附加地址信息 Feed 创建。现在,手动附加地址信息 Feed 已经停用,所有营业地点都应由“Google 我的商家”通过“Google 我的商家”营业地点管理工具Google My Business API 进行管理。

以下指南提供了端到端的示例,说明如何使用 Google My Business API 创建营业地点以及如何使用 AdWords API 将其关联到您的广告。

借助于“Google 我的商家”管理附加地址信息

Google 我的商家是您在所有 Google 产品中用到的营业地点的集中存储位置。您无需操心如何让“Google 我的商家”营业地点与 AdWords 附加地址信息保持同步。只需对必需的 Feed 对象执行一次性设置即可!AdWords 将自动使其附加地址信息与“Google 我的商家”帐号的最新数据保持同步。

本节指导您使用 Google My Business API 以编程方式创建营业地点,并通过创建所需的 Feed 对象将其关联到 AdWords。如果您要通过“Google 我的商家”营业地点管理工具创建营业地点,请跳过以下部分,直接跳到后面过程中的第 3 步

流程

如果您不熟悉 AdWords 中 Feed 的概念,请阅读附加链接 Feed 指南。这些说明是以该指南为基础。

创建和关联营业地点的步骤如下所示:

  1. 先进行身份验证,通过验证后才有权进行 Google My Business API 和 AdWords API 调用 (OAuth 2.0)。

  2. 使用 Google My Business API 创建新的营业地点。

    1. 使用 accounts.list 提取您拥有的或有管理权限的“Google 我的商家”帐号。
    2. 选择要使用的帐号(例如,AccountType = BUSINESS)。
    3. 创建营业地点,并指定标签地址营业时间等。
  3. 创建与您的“Google 我的商家”帐号关联的新的附加地址信息 Feed。

    1. systemFeedGenerationData 设置为包含您的“Google 我的商家”帐号相关信息PlacesLocationFeedData 对象。
    2. origin 设置为 ADWORDS。
    3. 不要指定任何 feedAttributes。这是系统生成的 Feed,因此 AdWords 会自动为您创建属性。
    4. 执行 FeedService.mutate ADD 操作。
  4. 将 Feed 与客户关联起来。

    1. 使用第 3 步中的 feedId
    2. 对于 LOCATION 使用占位符类型 7。
    3. 使用相应的 matchingFunction
    4. 执行 CustomerFeedService.mutate ADD 操作。
  5. (可选)将 Feed 与特定广告系列或广告组关联起来。

    1. 使用第 3 步中的 feedId
    2. 对于 LOCATION 使用占位符类型 7。
    3. 使用 matchingFunction,根据步骤 2c 中的标签进行过滤。
    4. 执行 CampaignFeedService.mutate ADD 或 AdGroupFeedService.mutate ADD 操作。

如果您熟悉其他附加信息的 Feed,则可能已注意到,上述步骤中未包含创建 FeedMapping 的步骤。由于此 Feed 是系统生成的,因此 AdWords 已经得知如何将此 Feed 的属性映射到附加地址信息的占位符字段,您无需再提供此类信息。以下部分说明如何在创建新 Feed 时设置 systemFeedGenerationData 对象(步骤 3a)。请参见下文综合了所有部分的代码示例

在 Feed 上创建 PlacesLocationFeedData 对象

在 Feed 上设置 systemFeedGenerationData 属性意味着 AdWords 会:

  • 将您的“Google 我的商家”帐号与 AdWords 帐号关联起来。
  • 自动为您的 Feed 创建 Feed 属性。
  • 自动为您的 Feed 和地理位置定位 criterionType (77) 创建 FeedMapping
  • (可选)限制 AdWords 从“Google 我的商家”帐号同步的一组地址信息。

请参照如下说明设置 PlacesLocationFeedData 对象的属性:

属性 是否必需 说明
emailAddress 您的“Google 我的商家”帐号所有者或其某个管理员的电子邮件地址。必须与 oAuthInfo 中提供的电子邮件地址相一致。
oAuthInfo 可授权您的 AdWords 帐号访问您的“Google 我的商家”帐号的 OAuth2 信息。
businessAccountIdentifier 要使用其营业地点的受管理商家的帐号 ID。如果您使用 Google My Business API 则可以从 Accountnameaccount_id 部分获得此 ID。否则,您可以复制以下格式的商家网址中的 BUSINESS_ACCOUNT_ID 部分:
https://business.google.com/b/BUSINESS_ACCOUNT_ID/...
businessNameFilter 要同步到 AdWords 的商家名称。
categoryFilters 要同步到 AdWords 的商家信息类别。
labelFilters 要同步到 AdWords 的商家信息标签。

在 PlacesLocationFeedData 上创建 OAuthInfo 对象

PlacesLocationFeedData 上的 oAuthInfo 属性提供了必要的信息,确保您的 AdWords 帐号可以从“Google 我的商家”帐号中读取地址信息。

请参照如下说明设置 OAuthInfo 对象的属性:

属性 说明
httpMethod GETPUT 用于获取授权信息的 HTTP 方法。
httpRequestUrl https://www.googleapis.com/auth/plus.business.manage “Google 我的商家”的 OAuth 范围。请务必在设置“Google 我的商家”Feed 时使用此处显示的值。
httpAuthorizationHeader Bearer OAUTH_ACCESS_TOKEN 包含 OAuth 访问令牌的授权标头,可授予您的 AdWords 帐号从您的“Google 我的商家”帐号读取的权限。代替 OAUTH_ACCESS_TOKEN,用 OAuth 凭据生成的访问令牌替代 PlacesLocationFeedDataemailAddress 和与 httpRequestUrl 匹配的范围。

完整代码示例

以下代码使用 Google My Business API 和 AdWords API 的 Java 客户端库。请参阅有关设置特定语言的相应说明。

第 1 步:进行身份验证,通过验证后才有权进行 Google My Business API 和 AdWords API 调用 (OAuth 2.0)

// Creating the default factory and transport (used later)
JsonFactory jsonFactory = JacksonFactory.getDefaultInstance();
HttpTransport httpTransport = GoogleNetHttpTransport.newTrustedTransport();

// Load the credentials from the ads.properties file.
// Please note: This example assumes that your AdWords and MyBusiness accounts
// are linked to the same Google account, and that both scopes were used when
// generating the refresh token:
// - https://www.googleapis.com/auth/adwords
// - https://www.googleapis.com/auth/plus.business.manage
// If you are using different Google accounts, you must authenticate
// separately and maintain two credentials (see
// /my-business/content/set-up-java-client).
Credential credential =
    new OfflineCredentials.Builder()
        .forApi(Api.ADWORDS)
        .withHttpTransport(httpTransport)
        .fromFile()
        .build()
        .generateCredential();

第 2 步:使用 Google My Business API 创建新的营业地点

// Initialize GMB.
Mybusiness gmb =
    new Mybusiness.Builder(httpTransport, jsonFactory, credential)
        .setApplicationName(APPLICATION_NAME)
        .build();
// Get list of GMB accounts (2a).
Mybusiness.Accounts.List listAccounts = gmb.accounts().list();
ListAccountsResponse response = listAccounts.execute();
List<Account> accounts = response.getAccounts();

// Find the account to work with (2b). The first BUSINESS account is used
// here, but you can use any other account as well (e.g., PERSONAL).
Account mainAccount = null;
for (Account account : accounts) {
  if (account.getType().equalsIgnoreCase("BUSINESS")) {
    mainAccount = account;
    break;
  }
}
if (mainAccount == null) {
  throw new RuntimeException("Main GMB account not found");
}
// Create the location (2c).
Location location = new Location();
location.setLocationName("My Company");
location.setStoreCode("Company-1");
location.setPrimaryPhone("16505550001");
location.setPrimaryCategory(new Category().setCategoryId("gcid:software_company"));
location.setWebsiteUrl("https://www.example.com/");
// Create an address.
Address address = new Address();
List<String> addressLines = new ArrayList<String>();
addressLines.add("1600 Amphitheatre Pkwy");
address.setAddressLines(addressLines);
address.setLocality("Mountain View");
address.setAdministrativeArea("CA");
address.setCountry("US");
address.setPostalCode("94043");
location.setAddress(address);
// Create business hours (optional).
BusinessHours businessHours = new BusinessHours();
List<TimePeriod> periods = new ArrayList<TimePeriod>();
List<String> days =
    Arrays.asList("Monday", "Tuesday", "Wednesday", "Thursday", "Friday");
for (String day : days) {
  TimePeriod period = new TimePeriod();
  period.setOpenDay(day);
  period.setOpenTime("9:00");
  period.setCloseTime("17:00");
  period.setCloseDay(day);
  periods.add(period);
}
businessHours.setPeriods(periods);
location.setRegularHours(businessHours);

// Assign a label to the location (optional). This example uses the AdWords
// customer ID as a label to associate the location with an ad group in AdWords.
// You can use any label value to identify locations, or no label at all
// (e.g., filter by business name or category).
location.setLabels(Collections.singletonList(INSERT_CUSTOMER_ID_HERE));
CreateLocationRequest createLocationRequest = new CreateLocationRequest();
createLocationRequest.setLocation(location);
createLocationRequest.setLanguageCode("en-US");
// Use a random request ID.
createLocationRequest.setRequestId(UUID.randomUUID().toString());
Mybusiness.Accounts.Locations.Create createLocation =
    gmb.accounts().locations().create(mainAccount.getName(),
    createLocationRequest);
Location createdLocation = createLocation.execute();

第 3 步:创建关联到“Google 我的商家”的新 Feed

// Initialize AdWords.
AdWordsSession session = new AdWordsSession.Builder()
    .fromFile()
    .withOAuth2Credential(credential)
    .build();
session.setClientCustomerId(INSERT_CUSTOMER_ID_HERE);
AdWordsServices services = new AdWordsServices();
FeedServiceInterface feedService =
    services.get(session, FeedServiceInterface.class);
// Create the feed object.
Feed gmbFeed = new Feed();
gmbFeed.setName("GMB feed #" + System.currentTimeMillis());
// Create the PlacesLocationFeedData object (3a).
PlacesLocationFeedData feedData = new PlacesLocationFeedData();
feedData.setEmailAddress(GMB_ACCOUNT_EMAIL);
OAuthInfo oAuthInfo = new OAuthInfo();
oAuthInfo.setHttpMethod("GET");
oAuthInfo.setHttpRequestUrl(
    "https://www.googleapis.com/auth/plus.business.manage");
oAuthInfo.setHttpAuthorizationHeader(
    String.format("Bearer %s", credential.getAccessToken()));
feedData.setOAuthInfo(oAuthInfo);
gmbFeed.setSystemFeedGenerationData(feedData);
// Since this feed's feed items will be managed by AdWords,
// you must set its origin to ADWORDS (3b).
gmbFeed.setOrigin(FeedOrigin.ADWORDS);
// Note: No feed attributes for the feed were specified, as this is a
// system-generated feed (3c).
// Create an operation to add the feed.
FeedOperation feedOperation = new FeedOperation();
feedOperation.setOperand(gmbFeed);
feedOperation.setOperator(Operator.ADD);
// Add the feed (3d).
FeedReturnValue addFeedResult = feedService.mutate(
    new FeedOperation[] {feedOperation});
Feed createdFeed = addFeedResult.getValue(0);

第 4 步:将 Feed 关联到客户

CustomerFeedServiceInterface customerFeedService =
    services.get(session, CustomerFeedServiceInterface.class);
CustomerFeed customerFeed = new CustomerFeed();
// Set feedId and placeholder type (4a + 4b).
customerFeed.setFeedId(createdFeed.getId());
customerFeed.setPlaceholderTypes(new int[] {PLACEHOLDER_LOCATION});
// Create a matching function that will always evaluate to true (4c).
Function customerMatchingFunction = new Function();
ConstantOperand constOperand = new ConstantOperand();
constOperand.setType(ConstantOperandConstantType.BOOLEAN);
constOperand.setBooleanValue(true);
customerMatchingFunction.setLhsOperand(
    new FunctionArgumentOperand[] {constOperand});
customerMatchingFunction.setOperator(FunctionOperator.IDENTITY);
customerFeed.setMatchingFunction(customerMatchingFunction);
// Create an operation to add the customer feed.
CustomerFeedOperation customerFeedOperation = new CustomerFeedOperation();
customerFeedOperation.setOperand(customerFeed);
customerFeedOperation.setOperator(Operator.ADD);
// Add the feed (4d).
CustomerFeedReturnValue customerFeedResult = customerFeedService.mutate(
    new CustomerFeedOperation[] {customerFeedOperation});
CustomerFeed createdCustomerFeed = customerFeedResult.getValue(0);

第 5 步:将 Feed 与特定广告组关联(类似于广告系列)

AdGroupFeedServiceInterface adgroupFeedService =
    services.get(session, AdGroupFeedServiceInterface.class);
// Create the ad group feed.
AdGroupFeed adgroupFeed = new AdGroupFeed();
adgroupFeed.setAdGroupId(AD_GROUP_ID);
// Set feedId and placeholder type (5a + 5b).
adgroupFeed.setFeedId(createdFeed.getId());
adgroupFeed.setPlaceholderTypes(new int[] {PLACEHOLDER_LOCATION});
// Define matching function based on the label (5c).
Function matchingFunction = new Function();
String matchingFunctionString = String.format(
    "EQUALS(FeedAttribute[%d, 14], \"%s\")",
    createdFeed.getId(),
    createdLocation.getLabels().get(0));
matchingFunction.setFunctionString(matchingFunctionString);
adgroupFeed.setMatchingFunction(matchingFunction);
// Create an operation to add the ad group feed.
AdGroupFeedOperation operation = new AdGroupFeedOperation();
operation.setOperand(adgroupFeed);
operation.setOperator(Operator.ADD);
// Add the feed (5d).
AdGroupFeedReturnValue result = adgroupFeedService.mutate(
    new AdGroupFeedOperation[]{operation});
AdGroupFeed createdAdGroupFeed = result.getValue(0);

过滤附加地址信息

附加地址信息会自动应用于帐号下的每个广告系列和广告组。您可以通过过滤器将附加地址信息应用于特定的广告组或广告系列。

过滤策略

借助于附加地址信息,您可以使用各种机制,在帐号的多个级别设定地址信息过滤条件。如果您希望对不同的广告系列或广告组的广告显示不同的地址,请使用 CampaignFeedAdGroupFeedmatchingFunction

过滤条件越具体,优先级越高。例如,假设您有:

  • CustomerFeed
  • 广告系列 ACampaignFeed
  • AdGroupFeed,用于广告系列 A 中的广告组 G
  • 另一个既没有 CampaignFeed 也没有 AdGroupFeed 的广告系列 B

使用此设置,您会发现以下情况(虚线显示哪个广告使用了哪个匹配函数):

  • 广告组 G 中投放的广告仅显示与 AdGroupFeed 的匹配函数对应的项的附加地址信息。
  • 广告系列 A 中所有其他广告组投放的广告仅显示与 CampaignFeed 匹配函数对应的项的附加地址信息。
  • 广告系列 B 中投放的广告显示与 CustomerFeed 匹配函数对应的项的附加地址信息。

使用属性进行过滤

Feed 对象中的过滤条件限制通过 PlacesLocationFeedData 对象的 businessNameFiltercategoryFilterslabelFilters 属性同步的 Feed 项。其他对象中的过滤条件则决定 AdWords 中的哪些 Feed 项会被用作客户、广告系列和广告组的指定组合的附加地址信息。如果属于下述情况,则可使用这些过滤条件:

  • 您对多个 AdWords 帐号使用同一个“Google 我的商家”帐号,每个 AdWords 帐号在逻辑上与一个地址子集相关联。
  • 您的“Google 我的商家”帐号中有您不希望展示在广告中的地址。

对于帐号、广告系列或广告组,您可以根据附加地址信息 Feed 中的任何可用属性指定 matchingFunctions 进行过滤。我们建议根据以下属性进行过滤:

  • 标签(占位符 14):通过在“Google 我的商家”中为每个地址指定标签,并使用这些标签在 AdWords 中进行过滤,您完全可以对过滤进行自定义。例如,您可以使用客户 ID 或应用生成的唯一 ID。

    如果指定了 labelFilters,则只有具有任意指定标签的商家信息才是要同步到 FeedItems 的候选项。如果 labelFilters 没有条目,则所有商家信息都是同步的候选项。此外,“Google 我的商家”信息的所有标签都会同步到 feedAttributeId = 14type = STRING_LIST 的 Feed 属性。您可以通过在匹配函数中指定条件来过滤具有一个或多个标签的 Feed 项,如下所示:

    CONTAINS_ANY(FeedAttribute[FeedId,14],{"label1","label2","label3"})
    
  • 商家名称(占位符 1):您可以使用相应地址的商家名称进行细粒度过滤。

  • 业务类别(占位符 9):按类别过滤可让您在对商家名称进行 AND 合并时定义更广泛的匹配或解决歧义。

有关按 Feed 属性 ID 进行过滤的详情,请参阅匹配函数指南;有关如何创建 CampaignFeed 和 AdGroupFeed 的示例,请参阅附加链接 Feed 指南

发送以下问题的反馈:

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