Filtersyntax

Bei einigen list-Methoden in der Merchant API, z. B. account.list, können Sie Filter anwenden, um nur die gewünschten Ergebnisse zu erhalten. Wenn Sie Ergebnisse filtern möchten, verwenden Sie den Parameter filter mit der in der EBNF-Grammatik definierten Syntax. Auf dieser Seite wird erläutert, wie Sie die Syntax zum Filtern von Konten verwenden.

Syntax

Alle Werte außer Ganzzahlen müssen in doppelte Anführungszeichen (") gesetzt werden. Welche Werte ein bestimmtes Feld akzeptiert, erfahren Sie in der Referenzdokumentation für dieses Feld.

Sie können AND verwenden, um in derselben Abfrage nach mehreren Feldern zu filtern. Sie können auch AND verwenden, um mehrere relationship(...)- und service(...)-Filter zu kombinieren. Hier ist ein Beispiel, in dem mehrere relationship(...)- und service(...)-Filter kombiniert werden:

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

In diesem Beispiel werden die folgenden Konten zurückgegeben:

• Alle Konten mit einer Kontoverwaltungsbeziehung zu einem anderen Konto und einer zusätzlichen Beziehung, die noch akzeptiert werden muss.

• Alle Konten mit dem Anzeigenamen "store", die Beziehungen zu anderen Konten haben.

Sie können AND nicht verwenden, um nach mehreren Werten im selben Feld zu filtern. Sie können beispielsweise nicht accountName = "*A*" AND accountName = "*B*" verwenden.

Sie können OR verwenden, um in derselben Abfrage nach zwei Feldern zu filtern. Setzen Sie die Filterkriterien auf beiden Seiten des Operators OR in Klammern. Beispiel: (accountName = "storeA") OR (accountName = "storeB").

Sie können OR nur verwenden, um zwei Felder zu kombinieren. Sie können beispielsweise nicht (accountName = "storeA") OR (accountName = "storeB") OR (accountName = "storeC") verwenden.

Klammern sind nur mit den Operatoren AND und OR sowie in Funktionsaufrufen wie relationship(...) und service(...) zulässig.

Bei Stringfeldern wie accountName und accountIdAlias können Sie nach Werten filtern, die ein bestimmtes Wort oder eine bestimmte Zeichenfolge enthalten, indem Sie die Zeichenfolge in Sternchen (*) setzen. Beispielsweise gibt accountName = "*foo*" alle Konten mit einem accountName zurück, das foo enthält, z. B. „storeFoo“.

Mit != und * können Sie nach Werten filtern, die eine bestimmte Sequenz nicht enthalten. Beispiel: accountName != "*foo*" gibt alle Konten mit einem accountName zurück, der nicht foo enthält.

Hinweis: Das Filtern nach accountIdAlias oder externalAccountId ist nur möglich, wenn auch ein providerId als diese Felder festgelegt ist. Die Verwendung dieser Felder ist nur im Kontext eines bestimmten providerId sinnvoll.

Zusätzliche Leerzeichen werden ignoriert. foo AND bar entspricht beispielsweise foo AND bar.

Hier sind einige Beispiele für das Filtern von Konten mit der Methode account.list:

• Alle Unterkonten eines erweiterten Kontos, die „Store“ enthalten:

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

• Alle Konten, die vom Anbieter 123456 verwaltet werden:

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

• Alle Konten, die eine Einladung an den Anbieter 123456 gesendet haben oder eine Einladung von diesem Anbieter annehmen müssen:

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

Wenn Sie nach den Konten filtern möchten, auf die der Nutzer, der die Anfrage stellt, zugreifen kann, verwenden Sie die Methode google.shopping.merchant.accounts.v1.ListAccountsRequest, wie im folgenden Beispiel gezeigt.

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

Spezifikation

Die Filter folgen einer Teilmenge der AIP-Filterspezifikation und ihrer formalen EBNF-Grammatik:

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