نحو فیلتر

برای برخی‌از روش‌های 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 نیستند برمی‌گرداند.

توجه: فیلتر کردن براساس accountIdAlias یا externalAccountId فقط زمانی امکان‌پذیر است که providerId نیز به‌عنوان این فیلدها تنظیم شده باشد. استفاده از این فیلدها فقط در بافت providerId خاصی منطقی است.

فاصله‌های سفید اضافی نادیده گرفته می‌شود. برای مثال، foo AND bar همان foo AND bar است.

در اینجا چند نمونه از فیلتر کردن حساب‌ها بااستفاده از روش account.list آورده شده است:

• همه حساب‌های فرعی حساب پیشرفته‌ای که حاوی «فروشگاه» است:

accountName = "*store*" AND relationship(service(type = "ACCOUNT_AGGREGATION"))

• همه حساب‌هایی که توسط ارائه‌دهنده ۱۲۳۴۵۶ مدیریت می‌شوند:

relationship(service(type = "ACCOUNT_MANAGEMENT") AND providerId = 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);
  }
}
FilterAccountsSample.java

مشخصات

فیلترها از زیرمجموعه‌ای از مشخصات فیلتر 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
    : " = "
    | " != "
    ;