Składnia filtra

W przypadku niektórych metod list w Merchant API, takich jak account.list możesz filtrować wyniki, aby wyświetlać tylko te, które Cię interesują. Aby filtrować wyniki, użyj parametru filter ze składnią zdefiniowaną w gramatyce EBNF. Na tej stronie dowiesz się, jak używać tej składni do filtrowania kont.

Składnia

Wszystkie wartości inne niż liczby całkowite muszą być ujęte w podwójne cudzysłowy ("). Aby dowiedzieć się jakie wartości akceptuje dane pole, zapoznaj się z dokumentacją referencyjną dotyczącą tego pola.

Aby filtrować według wielu pól w tym samym zapytaniu, możesz użyć operatora AND. Możesz też użyć operatora AND, aby połączyć kilka filtrów relationship(...) i service(...). Oto przykład, który łączy kilka filtrów relationship(...) i service(...):

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

Ten przykład zwraca te konta:

• Wszystkie konta, które mają relację zarządzania kontem z innym kontem, oraz dodatkową relację oczekującą na akceptację.

• Wszystkie konta o nazwie wyświetlanej "store", które mają relacje z innymi kontami.

Nie możesz używać operatora AND do filtrowania według wielu wartości w tym samym polu. Na przykład, nie możesz użyć accountName = "*A*" AND accountName = "*B*".

Aby filtrować według 2 pól w tym samym zapytaniu, możesz użyć operatora OR. Kryteria filtrowania po obu stronach operatora OR ujmij w nawiasy. Na przykład, (accountName = "storeA") OR (accountName = "storeB").

Operatora OR możesz używać tylko do łączenia 2 pól. Nie możesz na przykład użyć wyrażenia (accountName = "storeA") OR (accountName = "storeB") OR (accountName = "storeC").

Nawiasy są dozwolone tylko w połączeniu z operatorami AND i OR oraz w wywołaniach funkcji, takich jak relationship(...) i service(...).

W przypadku pól tekstowych, takich jak accountName i accountIdAlias, możesz filtrować według wartości zawierających określone słowo lub sekwencję znaków, ujmując tę sekwencję w gwiazdki (*). Na przykład accountName = "*foo*" zwraca wszystkie konta, których pole accountName zawiera ciąg znaków foo, np. „storeFoo”.

Możesz filtrować według wartości, które nie zawierają określonej sekwencji, używając operatorów != i *. Na przykład accountName != "*foo*" zwraca wszystkie konta, których pole accountName nie zawiera ciągu znaków foo.

Uwaga: filtrowanie według accountIdAlias lub externalAccountId jest możliwe tylko wtedy, gdy w tych polach jest też ustawiony providerId. Używanie tych pól ma sens tylko w kontekście konkretnego providerId.

Dodatkowe spacje są ignorowane. Na przykład foo AND bar jest tym samym co foo AND bar.

Oto kilka przykładów filtrowania kont za pomocą metody account.list:

• Wszystkie konta podrzędne konta zaawansowanego zawierające „Store”:

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

• Wszystkie konta zarządzane przez dostawcę 123456:

relationship(service(type = "ACCOUNT_MANAGEMENT") AND providerId = 123456)

• Wszystkie konta, które wysłały zaproszenie do dostawcy 123456 lub muszą zaakceptować zaproszenie od tego dostawcy:

relationship(service(handshakeState = "PENDING" AND type ="ACCOUNT_MANAGEMENT")
AND providerId = 123456)

Aby filtrować według kont, do których ma dostęp użytkownik wysyłający żądanie, użyj metody google.shopping.merchant.accounts.v1.ListAccountsRequest, jak pokazano w tym przykładzie.

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

Specyfikacja

Filtry są zgodne z podzbiorem specyfikacji filtrów AIP i jej formalną gramatyką 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
    : " = "
    | " != "
    ;