Merchant API v1beta 将于 2026 年 2 月 28 日停用并关停。如需了解迁移到最新稳定版的步骤，请参阅从 v1beta 迁移到 v1。

管理全渠道设置

OmnichannelSettings API 是配置本地商品目录广告 (LIA) 和非付费本地商品详情 (FLL) 计划的入口点。

使用该 API 以程序化方式

管理（创建和更新）全渠道设置
提取（获取和列出）全渠道设置
为符合条件的商家申请商品目录核实

如需了解详情，请参阅本地商品目录广告和非付费本地商品详情概览。

前提条件

您应该具备

Merchant Center 账号
商家资料。如果您还没有账号，可以创建一个。请参阅注册商家资料。
商家资料与 Merchant Center 账号之间的关联。如需创建关联，您可以使用 Merchant Center 界面或 Merchant API（请参阅关联 Google 商家资料）。

创建全渠道设置

您可以使用 omnichannelSettings.create 方法创建全渠道设置。create 方法以 omnichannelSetting 资源作为输入，并在成功时返回创建的全渠道设置。

创建时，您必须同时填写 regionCode 和 LsfType：

OmnichannelSetting 是按国家/地区设置的。RegionCode 定义目标国家/地区。创建后便无法更改。RegionCode 应遵循通用语言区域数据代码库 (CLDR) 项目定义的命名规则。
LsfType是根据您的商品页面生成的。如需了解详情，请参阅 LsfType。

如需了解详情，请参阅更改本地商品目录广告的商品页面体验。

您不必在创建阶段填写所有字段，而是可以在稍后进行配置。如需更新现有 omnichannelSetting，请参阅更新全渠道设置。

如果您选择 MHLSF_BASIC 并注册 inStock，则请求示例如下：

POST https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/omnichannelSettings

{
  "regionCode": "{REGION_CODE}",
  "lsfType: "MHLSF_BASIC",
  "inStock": {
      "uri": "{URI}"
  }
}

替换以下内容：

{ACCOUNT_ID}：您的 Merchant Center 账号的唯一标识符
{REGION_CODE}：由 CLDR 定义的地区代码
{URI}：用于指定评价的有效 URI。不符合条件的 URI 可能会导致审批失败。

请求成功运行后，您应该会看到以下响应：

{
  "name": "accounts/{ACCOUNT_ID}/omnichannelSettings/{omnichannel_setting}",
  "regionCode": "{REGION_CODE}",
  "lsfType: "MHLSF_BASIC",
  "inStock": {
      "uri": "{URI}",
      "state": "RUNNING"
  }
}

使用 omnichannelSetting 字段注册不同的 LIA/FLL 功能会触发人工审核，这通常需要几个小时到几天的时间。我们建议您仔细检查输入内容，以免因数据不符合条件而造成不必要的等待时间。

如需查看新创建的全渠道设置或检查评价状态，请使用 accounts.omnichannelSettings.get 或 accounts.omnichannelSettings.list，并指定国家/地区。

本地店面页面 (LSF) 类型

根据您打算使用的商品详情页，选择一个 LsfType：

商品页面类型	LsfType	枚举值
显示实体店库存状况的商品页面	商家自管的本地店面页面（基本版）	`MHLSF_BASIC`
显示库存状况和价格的具体实体店商品页面	商家自管的本地店面页面（完整版）	`MHLSF_FULL`
不显示实体店库存状况的商品页面	Google 托管的本地店面页面 (GHLSF)	`GHLSF`

如果您选择商家自管的本地店面页面类型，还需要填写至少一个 inStock 或 pickup 的 URI 字段。

InStock

您可以使用 InStock 提供有关商品页面的更多信息。

如果您选择商家托管的 LSF 类型，并在 InStock 中指定 URI 字段，则表明您打算投放有货的商品。我们将根据提供的 URI 开始审核。

如果您选择 GHLSF 类型，则需要在请求中提供一个空的 InStock 字段。与商家托管的 LSF 类型不同，您需要完成商品目录核实流程才能完成初始配置。

此代码示例会创建具有 GHLSF 的 omnichannelSetting：

package shopping.merchant.samples.accounts.v1;

// [START merchantapi_create_omnichannel_setting]
import com.google.api.gax.core.FixedCredentialsProvider;
import com.google.auth.oauth2.GoogleCredentials;
import com.google.shopping.merchant.accounts.v1.AccountName;
import com.google.shopping.merchant.accounts.v1.CreateOmnichannelSettingRequest;
import com.google.shopping.merchant.accounts.v1.InStock;
import com.google.shopping.merchant.accounts.v1.OmnichannelSetting;
import com.google.shopping.merchant.accounts.v1.OmnichannelSetting.LsfType;
import com.google.shopping.merchant.accounts.v1.OmnichannelSettingsServiceClient;
import com.google.shopping.merchant.accounts.v1.OmnichannelSettingsServiceSettings;
import shopping.merchant.samples.utils.Authenticator;
import shopping.merchant.samples.utils.Config;

/**
 *   This class demonstrates how to create an omnichannel setting for a given Merchant Center account
 *   in a given country
 */
public class CreateOmnichannelSettingSample {

  public static void createOmnichannelSetting(Config config, String regionCode) throws Exception {

    // Obtains OAuth token based on the user's configuration.
    GoogleCredentials credential = new Authenticator().authenticate();

    // Creates service settings using the retrieved credentials.
    OmnichannelSettingsServiceSettings omnichannelSettingsServiceSettings =
        OmnichannelSettingsServiceSettings.newBuilder()
            .setCredentialsProvider(FixedCredentialsProvider.create(credential))
            .build();

    // Calls the API and catches and prints any network failures/errors.
    try (OmnichannelSettingsServiceClient omnichannelSettingsServiceClient =
        OmnichannelSettingsServiceClient.create(omnichannelSettingsServiceSettings)) {
      String accountId = config.getAccountId().toString();
      String parent = AccountName.newBuilder().setAccount(accountId).build().toString();

      // Creates an omnichannel setting with GHLSF type in the given country.
      CreateOmnichannelSettingRequest request =
          CreateOmnichannelSettingRequest.newBuilder()
              .setParent(parent)
              .setOmnichannelSetting(
                  OmnichannelSetting.newBuilder()
                      .setRegionCode(regionCode)
                      .setLsfType(LsfType.GHLSF)
                      .setInStock(InStock.getDefaultInstance())
                      .build())
              .build();

      System.out.println("Sending create omnichannel setting request:");
      OmnichannelSetting response =
          omnichannelSettingsServiceClient.createOmnichannelSetting(request);

      System.out.println("Inserted Omnichannel Setting below:");
      System.out.println(response);
    } catch (Exception e) {
      System.out.println("An error has occurred: ");
      System.out.println(e);
    }
  }

  public static void main(String[] args) throws Exception {
    Config config = Config.load();

    // The country which you're targeting at.
    String regionCode = "{REGION_CODE}";

    createOmnichannelSetting(config, regionCode);
  }
}
// [END merchantapi_list_omnichannel_settings]

自提

除了实体店库存状况之外，您还可以使用自提功能来提升实体店商品的展示效果，但此功能仅适用于商家托管的本地商品目录广告。

如果商品标记为“自提”，则表示客户可以在线购买该商品，然后到实体店自提。通过设置 Pickup 字段，您可以表明自己打算提供具有自提 SLA 的商品。我们将根据提供的 URI 开始审核。

以下是一个示例请求，用于创建包含 Pickup 的 omnichannel 设置：

POST https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/omnichannelSettings

{
  "regionCode": "{REGION_CODE}",
  "lsfType: "MHLSF_BASIC",
  "pickup": {
     "uri: "{URI}"
  }
}

样品，仅接受预定

借助样品，仅接受预定功能，您可以展示虽然在实体店内陈列但无法立即供客户购买的商品。例如，大型家具：

客户在 Google 上搜索类似的商品时，将会在搜索结果中看到这类广告带有“实体店有售”注释。
如果客户通过 Google 搜索结果页浏览商店页面，会看到这类商品标有“可订购”字样。

他们可以选择您的本地商品目录广告或非付费本地商品详情来查看商品。如要购买此类商品，他们可以前往您的实体店、查看商品，然后订购商品并选择配送至自己的地址或配送到您的商店并自提。

简介（德国、奥地利和瑞士）

如果您在奥地利和德国投放广告，并选择 GHLSF，则必须提交简介页面。

如果您在瑞士投放广告，则无论 LsfType 的值如何，都必须提交“关于”页面。

在“简介”页面网址通过验证之前，GHLSF商家无法向 Google 申请人工商品目录核实。

对于这三个国家/地区的所有商家，在您的“关于”页面获得批准之前，该服务不会启用 FLL/LIA 功能。

商品目录核实

只有 GHLSF 商家需要进行商品目录核实。MHLSF 类型不支持此功能。

在添加商品数据和产品目录数据之前或之后（使用 accounts.products.localInventories.insert 或 Merchant Center 界面），您必须验证自己的联系信息。使用 create 或 update 方法提供商品目录验证联系人（姓名和电子邮件地址）。联系人会收到 Google 发送的电子邮件，并且能够通过点击邮件中的按钮来验证其状态。

完成此操作后，您可以申请商品目录核实。如需了解详情，请参阅商品目录核实简介。

您可以在验证过程中或验证完成后使用 omnichannelSetting.update 更改联系人。

此流程完成后，Google 会验证所提供信息的准确性。

获取全渠道设置

如需检索给定国家/地区的 omnichannelSetting 配置，或查看评价的当前状态，请使用 omnichannelSettings.get 方法。

以下是请求示例：

GET https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/omnichannelSettings/{OMNICHANNEL_SETTING}

替换以下内容：

{ACCOUNT_ID}：您的 Merchant Center 账号的唯一标识符
{OMNICHANNEL_SETTING}：目标国家/地区的地区代码

ACTIVE 状态表示相应评价已获得批准。

如果状态为 FAILED，请解决相应问题，然后通过调用 omnichannelSetting.update 触发新的审核。

只读的 LFP 字段会显示您的本地 Feed 合作伙伴关系状态。如需链接到合作伙伴关系，请使用 lfpProviders.linkLfpProvider。

如需详细了解如何查看状态及其含义，请参阅查看全渠道设置的状态。

列出全渠道设置

如需检索账号的所有 omnichannelSetting 信息，请使用 omnichannelSettings.list 方法。

以下是一个代码示例：

package shopping.merchant.samples.accounts.v1;

// [START merchantapi_list_omnichannel_settings]
import com.google.api.gax.core.FixedCredentialsProvider;
import com.google.auth.oauth2.GoogleCredentials;
import com.google.shopping.merchant.accounts.v1.AccountName;
import com.google.shopping.merchant.accounts.v1.ListOmnichannelSettingsRequest;
import com.google.shopping.merchant.accounts.v1.OmnichannelSetting;
import com.google.shopping.merchant.accounts.v1.OmnichannelSettingsServiceClient;
import com.google.shopping.merchant.accounts.v1.OmnichannelSettingsServiceClient.ListOmnichannelSettingsPagedResponse;
import com.google.shopping.merchant.accounts.v1.OmnichannelSettingsServiceSettings;
import shopping.merchant.samples.utils.Authenticator;
import shopping.merchant.samples.utils.Config;

/**
 *   This class demonstrates how to get the list of omnichannel settings for a given Merchant Center
 *   account
 */
public class ListOmnichannelSettingsSample {

  public static void omnichannelSettings(Config config) throws Exception {

    // Obtains OAuth token based on the user's configuration.
    GoogleCredentials credential = new Authenticator().authenticate();

    // Creates service settings using the retrieved credentials.
    OmnichannelSettingsServiceSettings omnichannelSettingsServiceSettings =
        OmnichannelSettingsServiceSettings.newBuilder()
            .setCredentialsProvider(FixedCredentialsProvider.create(credential))
            .build();

    String accountId = config.getAccountId().toString();
    String parent = AccountName.newBuilder().setAccount(accountId).build().toString();

    // Calls the API and catches and prints any network failures/errors.
    try (OmnichannelSettingsServiceClient omnichannelSettingsServiceClient =
        OmnichannelSettingsServiceClient.create(omnichannelSettingsServiceSettings)) {
      ListOmnichannelSettingsRequest request =
          ListOmnichannelSettingsRequest.newBuilder().setParent(parent).build();

      System.out.println("Sending list omnichannel setting request:");
      ListOmnichannelSettingsPagedResponse response =
          omnichannelSettingsServiceClient.listOmnichannelSettings(request);

      int count = 0;

      // Iterates over all the entries in the response.
      for (OmnichannelSetting omnichannelSetting : response.iterateAll()) {
        System.out.println(omnichannelSetting);
        count++;
      }
      System.out.println(String.format("The following count of elements were returned: %d", count));
    } catch (Exception e) {
      System.out.println("An error has occurred: ");
      System.out.println(e);
    }
  }

  public static void main(String[] args) throws Exception {
    Config config = Config.load();

    omnichannelSettings(config);
  }
}
// [END merchantapi_list_omnichannel_settings]

更新全渠道设置

如需更新现有全渠道设置的配置，请使用 omnichannelSettings.update 方法。

如需更新，您必须将要更新的功能添加到更新掩码，并在更新请求的 omnichannelSetting 字段中填写相应字段。您可以更新以下任意一项：

lsfType
inStock
pickup
odo
about
inventoryVerification

如果某个属性未包含在更新掩码中，则不会更新该属性。

如果某个属性包含在更新掩码中，但未在请求中设置，则该属性将被清除。

以下代码示例演示了如何更新商品目录验证字段。

package shopping.merchant.samples.accounts.v1;

// [START merchantapi_update_omnichannel_setting]
import com.google.api.gax.core.FixedCredentialsProvider;
import com.google.auth.oauth2.GoogleCredentials;
import com.google.protobuf.FieldMask;
import com.google.shopping.merchant.accounts.v1.InventoryVerification;
import com.google.shopping.merchant.accounts.v1.OmnichannelSetting;
import com.google.shopping.merchant.accounts.v1.OmnichannelSettingName;
import com.google.shopping.merchant.accounts.v1.OmnichannelSettingsServiceClient;
import com.google.shopping.merchant.accounts.v1.OmnichannelSettingsServiceSettings;
import com.google.shopping.merchant.accounts.v1.UpdateOmnichannelSettingRequest;
import shopping.merchant.samples.utils.Authenticator;
import shopping.merchant.samples.utils.Config;

/**
 *   This class demonstrates how to update an omnichannel setting for a given Merchant Center account
 *   in a given country
 */
public class UpdateOmnichannelSettingSample {

  public static void updateOmnichannelSettings(
      Config config, String regionCode, String contact, String email) throws Exception {

    // Obtains OAuth token based on the user's configuration.
    GoogleCredentials credential = new Authenticator().authenticate();

    // Creates service settings using the retrieved credentials.
    OmnichannelSettingsServiceSettings omnichannelSettingsServiceSettings =
        OmnichannelSettingsServiceSettings.newBuilder()
            .setCredentialsProvider(FixedCredentialsProvider.create(credential))
            .build();

    // Calls the API and catches and prints any network failures/errors.
    try (OmnichannelSettingsServiceClient omnichannelSettingsServiceClient =
        OmnichannelSettingsServiceClient.create(omnichannelSettingsServiceSettings)) {
      String accountId = config.getAccountId().toString();
      String name =
          OmnichannelSettingName.newBuilder()
              .setAccount(accountId)
              .setOmnichannelSetting(regionCode)
              .build()
              .toString();

      OmnichannelSetting omnichannelSetting =
          OmnichannelSetting.newBuilder()
              .setName(name)
              .setInventoryVerification(
                  InventoryVerification.newBuilder()
                      .setContact(contact)
                      .setContactEmail(email)
                      .build())
              .build();
      FieldMask fieldMask = FieldMask.newBuilder().addPaths("inventory_verification").build();
      UpdateOmnichannelSettingRequest request =
          UpdateOmnichannelSettingRequest.newBuilder()
              .setOmnichannelSetting(omnichannelSetting)
              .setUpdateMask(fieldMask)
              .build();

      System.out.println("Sending update omnichannel setting request:");
      OmnichannelSetting response =
          omnichannelSettingsServiceClient.updateOmnichannelSetting(request);

      System.out.println("Updated Omnichannel Setting below:");
      System.out.println(response);
    } catch (Exception e) {
      System.out.println("An error has occurred: ");
      System.out.println(e);
    }
  }

  public static void main(String[] args) throws Exception {
    Config config = Config.load();

    // The country which you're targeting at.
    String regionCode = "{REGION_CODE}";
    // The name of the inventory verification contact you want to update.
    String contact = "{NAME}";
    // The address of the inventory verification email you want to update.
    String email = "{EMAIL}";

    updateOmnichannelSettings(config, regionCode, contact, email);
  }
}
// [END merchantapi_update_omnichannel_setting]

申请商品目录核实

omnichannelSettings.requestInventoryVerification 仅适用于 GHLSF 商家。

在调用此 RPC 之前，您需要执行以下操作：

上传商品和产品目录数据。
验证商品目录核实联系人。
对于奥地利、德国或瑞士的商家，请完成About页面审核。

如需确定您是否符合条件，请调用 omnichannelSettings.get 并检查 omnichannelSetting.inventoryVerification.state。如果显示 INACTIVE，则表示您已准备好调用 omnichannelSettings.requestInventoryVerification。

package shopping.merchant.samples.accounts.v1;

// [START merchantapi_request_inventory_verification]
import com.google.api.gax.core.FixedCredentialsProvider;
import com.google.auth.oauth2.GoogleCredentials;
import com.google.shopping.merchant.accounts.v1.OmnichannelSettingName;
import com.google.shopping.merchant.accounts.v1.OmnichannelSettingsServiceClient;
import com.google.shopping.merchant.accounts.v1.OmnichannelSettingsServiceSettings;
import com.google.shopping.merchant.accounts.v1.RequestInventoryVerificationRequest;
import com.google.shopping.merchant.accounts.v1.RequestInventoryVerificationResponse;
import shopping.merchant.samples.utils.Authenticator;
import shopping.merchant.samples.utils.Config;

/**
 *   This class demonstrates how to request inventory verification for a given Merchant Center account
 *   in a given country
 */
public class RequestInventoryVerificationSample {

  public static void requestInventoryVerification(Config config, String regionCode)
      throws Exception {

    // Obtains OAuth token based on the user's configuration.
    GoogleCredentials credential = new Authenticator().authenticate();

    // Creates service settings using the retrieved credentials.
    OmnichannelSettingsServiceSettings omnichannelSettingsServiceSettings =
        OmnichannelSettingsServiceSettings.newBuilder()
            .setCredentialsProvider(FixedCredentialsProvider.create(credential))
            .build();

    // Calls the API and catches and prints any network failures/errors.
    try (OmnichannelSettingsServiceClient omnichannelSettingsServiceClient =
        OmnichannelSettingsServiceClient.create(omnichannelSettingsServiceSettings)) {
      String accountId = config.getAccountId().toString();
      String name =
          OmnichannelSettingName.newBuilder()
              .setAccount(accountId)
              .setOmnichannelSetting(regionCode)
              .build()
              .toString();
      RequestInventoryVerificationRequest request =
          RequestInventoryVerificationRequest.newBuilder().setName(name).build();

      System.out.println("Sending request inventory verification request:");
      RequestInventoryVerificationResponse response =
          omnichannelSettingsServiceClient.requestInventoryVerification(request);

      System.out.println("Omnichannel Setting after inventory verification request below:");
      System.out.println(response);
    } catch (Exception e) {
      System.out.println("An error has occurred: ");
      System.out.println(e);
    }
  }

  public static void main(String[] args) throws Exception {
    Config config = Config.load();

    // The country which you're targeting at.
    String regionCode = "{REGION_CODE}";

    requestInventoryVerification(config, regionCode);
  }
}
// [END merchantapi_request_inventory_verification]

查看全渠道设置的状态。

如需查看 LIA 启用审核的审核状态，请检查 omnichannelSettings.get 或 omnichannelSettings.list 方法返回的 omnichannelSetting 的相应属性 ReviewState。

ReviewState 字段适用于所有初始配置审核（商品目录验证流程除外），并且可以具有以下值：

ACTIVE：已获批准。
FAILED：已被拒绝。
RUNNING：仍在审核中。
ACTION_REQUIRED：此字段仅在 InStock.state 中针对 GHLSF 商家存在。这意味着您需要申请商品目录核实，才能投放 LIA。

InventoryVerification.State 具有以下值：

SUCCEEDED：已获批准。
INACTIVE：您已准备好申请商品目录核实。
RUNNING：正在接受审核
SUSPENDED：您未通过商品目录核实的次数过多（通常为 5 次），需要等待一段时间才能再次申请核实。
ACTION_REQUIRED：您需要先采取其他措施，然后才能申请核实商品目录。

排查与 `OmnichannelSettings` API 相关的问题

本部分介绍了如何排查常见问题。

创建全渠道设置

请务必同时设置 LsfType 和 RegionCode。
如果您选择 GHLSF，请在请求中提供空的 InStock。
如果您选择商家托管的 LSF 类型，请在 InStock 或 Pickup 中提供至少一个 URI。

更新全渠道设置

此资源的更新方法需要遵循以下附加规则：

您无法修改区号。
在 LIA/FLL 功能运行或获得批准后，您无法进行更新。
从商家托管的 LSF 类型更改为 GHLSF 时，如果之前配置了 InStock 和 Pickup，则必须将它们与 LsfType 更新一起包含在更新掩码中。

例如，如果您之前应用了 MHLSF_BASIC 和 Pickup，但它们被拒绝了，那么您可以通过发送如下请求来切换到 GHLSF：

PATCH https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/omnichannelSettings/{REGION_CODE}?update_mask=lsf_type,in_stock,pickup

{
  "lsfType: "GHLSF",
  "inStock": {},
}

替换以下内容：

{ACCOUNT_ID}：您的 Merchant Center 账号的唯一标识符
{REGION_CODE}：CLDR 中定义的地区代码

申请商品目录核实

如果尽管更新了商品或商品目录 Feed 并确认了联系信息，但 InventoryVerification.state 仍不是 INACTIVE，请执行以下操作：

对于奥地利、德国和瑞士境内的商家：请确保您已完成“简介”页面审核。
大约会有 48 小时的延迟。
如果重复出现库存检查失败的情况（超过 5 次），服务会强制执行 30 天的冷却期，然后才允许再次发出请求。如果您想申请更早的退款，请与 Google 支持团队联系。

了解详情

如需了解详情，请参阅本地商品目录广告和非付费本地商品详情帮助中心。

管理全渠道设置 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

前提条件

创建全渠道设置

本地店面页面 (LSF) 类型

InStock

自提

样品，仅接受预定

简介（德国、奥地利和瑞士）

商品目录核实

获取全渠道设置

列出全渠道设置

更新全渠道设置

申请商品目录核实

查看全渠道设置的状态。

排查与 OmnichannelSettings API 相关的问题

创建全渠道设置

更新全渠道设置

申请商品目录核实

了解详情

管理全渠道设置

排查与 `OmnichannelSettings` API 相关的问题