过滤器语法

本页介绍了您必须使用的过滤账号的语法。

语法

除整数以外的所有值都必须用英文双引号 (") 括起来。如需了解特定字段接受哪些值，请参阅该字段的参考文档。

您可以使用 AND 在同一查询中按多个字段进行过滤。您还可以使用 AND 组合多个 relationship(...) 和 service(...) 过滤条件。以下示例结合使用了多个 relationship(...) 和 service(...) 过滤条件：

(relationship(service(type = "ACCOUNT_MANAGEMENT") AND service(handshakeState = "PENDING"))) OR (accountName = "store" AND relationship(...))

此示例会返回以下账号：

  • 与另一个账号存在账号管理关系的所有账号，以及存在待接受的其他关系的账号。

  • 显示名称为 "store" 且与其他账号存在关联的所有账号。

您无法使用 AND 在同一字段中过滤多个值。例如，您不能使用 accountName = "*A*" AND accountName = "*B*"。

您可以使用 OR 在同一查询中过滤两个字段。将 OR 运算符两侧的过滤条件用英文圆括号括起来。例如 (accountName = "storeA") OR (accountName = "storeB")。

您只能使用 OR 来组合两个字段。例如，您不能使用 (accountName = "storeA") OR (accountName = "storeB") OR (accountName = "storeC")。

除了 AND 和 OR 运算符以及函数调用（例如 relationship(...) 和 service(...)）之外，不允许使用圆括号。

对于 accountName 和 accountIdAlias 等字符串字段，您可以使用星号 (*) 将某个字词或字符序列括起来，以过滤包含该字词或字符序列的值。例如，accountName = "*foo*" 会返回所有 accountName 包含 foo（例如“storeFoo”）的账号。

您可以使用 != 和 * 过滤掉不包含特定序列的值。例如，accountName != "*foo*" 会返回 accountName 不包含 foo 的所有账号。

系统会忽略多余的空格。例如，foo AND bar 与 foo AND bar 是同一个路径。

以下是使用 account.list 方法过滤账号的一些示例：

“* 包含“商店”的所有 MCA 子账号

accountName = "*store*" AND relationship(service(type = "ACCOUNT_AGGREGATION"))
  • 由提供商 123456 管理的所有账号
relationship(service(type = "ACCOUNT_MANAGEMENT") AND providerId = 123456)
  • 已向提供商 123456 发送邀请或需要接受此提供商发送的邀请的所有账号
relationship(service(handshakeState = "PENDING" AND type ="ACCOUNT_MANAGEMENT")
AND providerId = 123456)

如需过滤出发出请求的用户可以访问的账号，请使用 google.shopping.merchant.accounts.v1.ListAccountsRequest 方法，如以下示例所示。

Java

import com.google.api.gax.core.FixedCredentialsProvider;
import com.google.auth.oauth2.GoogleCredentials;
import com.google.shopping.merchant.accounts.v1.Account;
import com.google.shopping.merchant.accounts.v1.AccountsServiceClient;
import com.google.shopping.merchant.accounts.v1.AccountsServiceClient.ListAccountsPagedResponse;
import com.google.shopping.merchant.accounts.v1.AccountsServiceSettings;
import com.google.shopping.merchant.accounts.v1.ListAccountsRequest;
import shopping.merchant.samples.utils.Authenticator;
import shopping.merchant.samples.utils.Config;

/** This class demonstrates how to filter the accounts the user making the request has access to. */
public class FilterAccountsSample {

  public static void filterAccounts(Config config) throws Exception {

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

    // Creates service settings using the credentials retrieved above.
    AccountsServiceSettings accountsServiceSettings =
        AccountsServiceSettings.newBuilder()
            .setCredentialsProvider(FixedCredentialsProvider.create(credential))
            .build();

    // Calls the API and catches and prints any network failures/errors.
    try (AccountsServiceClient accountsServiceClient =
        AccountsServiceClient.create(accountsServiceSettings)) {

      // Filter for accounts with display names containing "store" and a provider with the ID "123":
      String filter = "accountName = \"*store*\" AND relationship(providerId = 123)";

      // Filter for all subaccounts of account "123":
      // String filter2 = "relationship(providerId = 123 AND service(type =
      // \"ACCOUNT_AGGREGATION\"))";

      // String filter3 = "relationship(service(handshakeState = \"APPROVED\" AND type =
      // \"ACCOUNT_MANAGEMENT\") AND providerId = 123)";

      ListAccountsRequest request = ListAccountsRequest.newBuilder().setFilter(filter).build();

      System.out.println("Sending list accounts request with filter:");
      ListAccountsPagedResponse response = accountsServiceClient.listAccounts(request);

      int count = 0;

      // Iterates over all rows in all pages and prints the sub-account
      // in each row.
      // `response.iterateAll()` automatically uses the `nextPageToken` and recalls the
      // request to fetch all pages of data.
      for (Account account : response.iterateAll()) {
        System.out.println(account);
        count++;
      }
      System.out.print("The following count of elements were returned: ");
      System.out.println(count);
    } catch (Exception e) {
      System.out.println(e);
    }
  }

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

    filterAccounts(config);
  }
}
FilterAccountsSample.java

规范

过滤条件遵循 AIP 过滤条件规范及其正式 EBNF 语法的子集：

filter
    : accountFilterDisj
    | accountFilterConj

accountFilterDisj
    : "(" accountFilterConj " OR " accountFilterConj ")"
    ;
accountFilterConj
    : accountFilter {" AND " accountFilter}
    ;

accountFilter
    : accountNameFilter | capabilityFilter | relationshipFn
    ;

accountNameFilter
    : "accountName" comparator value
    ;

capabilityFilter
    : "capabilities:" capabilityValue
    | "-capabilities:" capabilityValue
    | "NOT capabilities:" capabilityValue
    ;
capabilityValue
    : "CAN_UPLOAD_PRODUCTS"
    ;

relationshipFn
    : "relationship(" relationshipConj ")"
    ;
relationshipConj
    : relationshipFilter {" AND " relationshipFilter}
    ;
relationshipFilter
    : "providerId = " numValue
    | "accountIdAlias" comparator value
    | serviceFn
    ;

serviceFn
    : "service(" serviceConj ")"
    ;
serviceConj
    : serviceFilter {" AND " serviceFilter}
    ;
serviceFilter
    : "externalAccountId" comparator value
    | "handshakeState = " handshakeState
    | "type = " serviceType
    ;

handshakeState
    : "PENDING"
    | "APPROVED"
    | "REJECTED"
    ;
serviceType
    : "ACCOUNT_AGGREGATION"
    | "ACCOUNT_MANAGEMENT"
    ;

comparator
    : " = " | " != "
    ;