نحو فیلتر

برای برخی‌از روش‌های list در Merchant API، مانند account.list می‌توانید فیلتر کردن را انجام دهید تا فقط نتایجی را که به آن‌ها علاقه‌مندید دریافت کنید. برای فیلتر کردن نتایج، از پارامتر filter با دستور زبان تعریف‌شده در دستور زبان EBNF استفاده می‌کنید. این صفحه توضیح می‌دهد چگونه از دستور زبان برای فیلتر کردن حساب‌ها استفاده کنید.

نحو

همه مقادیر غیر از اعداد صحیح باید در گیومه دوتایی («) قرار بگیرند. برای اینکه بدانید یک فیلد خاص چه مقادیری را می‌پذیرد، به مستندات مرجع آن فیلد مراجعه کنید.

می‌توانید از 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 آورده شده است:

  • همه حساب‌های فرعی حساب پیشرفته‌ای که حاوی «فروشگاه» است:
accountName = "*store*" AND relationship(service(type = "ACCOUNT_AGGREGATION"))
  • همه حساب‌هایی که توسط ارائه‌دهنده ۱۲۳۴۵۶ مدیریت می‌شوند:
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 استفاده کنید، همان‌طور که در نمونه زیر نشان داده شده است.

جاوا

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);
  }
}

مشخصات

فیلترها از زیرمجموعه‌ای از مشخصات فیلتر AIP پیروی می‌کنند و دستور زبان رسمی EBNF آن به این صورت است:

filter
    : accountFilterDisj
    | accountFilterConj

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

accountFilter
    : accountNameFilter | capabilityFilter | relationshipFn | accessFilter
    ;

accountNameFilter
    : "accountName" comparator value
    ;

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

accessFilter
    : "access = " accessType
    ;

accessType
    : "DIRECT"
    | "INDIRECT"
    | "ALL"
    ;

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"
    | "WAITING"
    | "ESTABLISHED"
    | "REJECTED"
    ;
serviceType
    : "ACCOUNT_AGGREGATION"
    | "ACCOUNT_MANAGEMENT"
    ;

comparator
    : " = "
    | " != "
    ;