بنية الفلتر

بالنسبة إلى بعض طرق 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:

• جميع الحسابات الفرعية لحساب بامتيازات متقدّمة يحتوي على "Store":

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، كما هو موضّح في المثال التالي.

جافا

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
    : " = "
    | " != "
    ;