Filtre söz dizimi

Merchant API'deki bazı list yöntemleri (ör. account.list) için filtreleme yaparak yalnızca ilgilendiğiniz sonuçları alabilirsiniz. Sonuçları filtrelemek için EBNF dil bilgisinde tanımlanan söz dizimiyle filter parametresini kullanırsınız. Bu sayfada, hesapları filtrelemek için söz diziminin nasıl kullanılacağı açıklanmaktadır.

Söz dizimi

Tam sayı dışındaki tüm değerler çift tırnak (") içine alınmalıdır. Belirli bir alanın hangi değerleri kabul ettiğini öğrenmek için ilgili alanın referans belgelerine bakın.

Aynı sorguda birden fazla alanı filtrelemek için AND kullanabilirsiniz. Birden fazla relationship(...) ve service(...) filtresini birleştirmek için AND de kullanabilirsiniz. Birden fazla relationship(...) ve service(...) filtresini birleştiren bir örneği aşağıda görebilirsiniz:

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

Bu örnekte aşağıdaki hesaplar döndürülür:

  • Başka bir hesapla hesap yönetimi ilişkisi olan ve kabul edilmeyi bekleyen ek bir ilişkisi bulunan tüm hesaplar.

  • Görünen adı "store" olan ve diğer hesaplarla ilişkisi bulunan tüm hesaplar.

Aynı alandaki birden fazla değeri filtrelemek için AND kullanamazsınız. Örneğin, accountName = "*A*" AND accountName = "*B*" kullanamazsınız.

Aynı sorguda iki alanı filtrelemek için OR kullanabilirsiniz. OR operatörünün her iki tarafındaki filtre ölçütlerini parantez içine alın. Örneğin, (accountName = "storeA") OR (accountName = "storeB").

İki alanı birleştirmek için yalnızca OR kullanabilirsiniz. Örneğin, (accountName = "storeA") OR (accountName = "storeB") OR (accountName = "storeC") kullanamazsınız.

AND ve OR operatörleri dışında ve relationship(...) ve service(...) gibi işlev çağrılarında parantez kullanımına izin verilmez.

accountName ve accountIdAlias gibi dize alanlarında, karakter dizisini yıldız işaretleri (*) içine alarak belirli bir kelimeyi veya karakter dizisini içeren değerleri filtreleyebilirsiniz. Örneğin, accountName = "*foo*", foo içeren bir accountName değerine sahip tüm hesapları (ör. "storeFoo") döndürür.

!= ve * kullanarak belirli bir dizeyi içermeyen değerleri filtreleyebilirsiniz. Örneğin, accountName != "*foo*", foo içermeyen bir accountName değerine sahip tüm hesapları döndürür.

Fazladan boşluklar yoksayılır. Örneğin, foo AND bar ile foo AND bar aynıdır.

account.list yöntemini kullanarak hesapları filtrelemeyle ilgili birkaç örneği aşağıda bulabilirsiniz:

  • "Mağaza" içeren gelişmiş bir hesabın tüm alt hesapları:
accountName = "*store*" AND relationship(service(type = "ACCOUNT_AGGREGATION"))
  • 123456 sağlayıcısı tarafından yönetilen tüm hesaplar:
relationship(service(type = "ACCOUNT_MANAGEMENT") AND providerId = 123456)
  • 123456 sağlayıcısına davetiye gönderen veya bu sağlayıcıdan gelen davetiyeyi kabul etmesi gereken tüm hesaplar:
relationship(service(handshakeState = "PENDING" AND type ="ACCOUNT_MANAGEMENT")
AND providerId = 123456)

İstek gönderen kullanıcının erişebileceği hesapları filtrelemek için aşağıdaki örnekte gösterildiği gibi google.shopping.merchant.accounts.v1.ListAccountsRequest yöntemini kullanın.

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

Spesifikasyon

Filtreler, AIP filtre spesifikasyonunun bir alt kümesini ve resmi EBNF dil bilgisini takip eder:

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