Filtre söz dizimi

Merchant API'deki bazı list yöntemlerde (ör. account.list ) yalnızca ilgilendiğiniz sonuçları alacak şekilde filtreleme yapabilirsiniz. Sonuçları filtrelemek için filter parametresini EBNF gramerinde tanımlanan söz dizimiyle birlikte 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ılar 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ı sorgudaki birden fazla alanı filtrelemek için AND simgesini kullanabilirsiniz. Birden fazla relationship(...) ve service(...) filtresini birleştirmek için AND simgesini de kullanabilirsiniz. Birden fazla relationship(...) ve service(...) filtresini birleştiren bir örneği aşağıda bulabilirsiniz:

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

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

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

  • Görünen adı "store" olan ve diğer hesaplarla ilişkisi olan 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 işlecini kullanabilirsiniz. Örneğin, (accountName = "storeA") OR (accountName = "storeB") OR (accountName = "storeC") kullanamazsınız.

Parantezlere yalnızca AND ve OR operatörleriyle birlikte ve relationship(...) ile service(...) gibi işlev çağrılarında izin verilir.

accountName ve accountIdAlias gibi dize alanlarında, belirli bir kelime veya karakter dizisi içeren değerleri filtrelemek için diziyi yıldız işaretleri (*) içine alabilirsiniz. Örneğin, accountName = "*foo*", accountName alanında foo içeren tüm hesapları ("storeFoo" gibi) döndürür.

!= ve * kullanarak belirli bir diziyi içermeyen değerleri filtreleyebilirsiniz. Örneğin, accountName != "*foo*", foo içermeyen bir accountName ile 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.

Aşağıda, account.list yöntemini kullanarak hesapları filtrelemeyle ilgili birkaç örnek verilmiştir:

  • "Mağaza" kelimesini içeren bir gelişmiş 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 davet gönderen veya bu sağlayıcıdan gelen daveti kabul etmesi gereken tüm hesaplar:
relationship(service(handshakeState = "PENDING" AND type ="ACCOUNT_MANAGEMENT")
AND providerId = 123456)

İsteği 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 filtresi spesifikasyonunun bir alt kümesini ve resmi EBNF gramerini takip eder:

filter
    : accountFilterDisj
    | accountFilterConj

accountFilterDisj
    : "(" accountFilterConj " OR " accountFilterConj ")"
    ;
accountFilterConj
    : accountFilter {" AND " accountFilter}
    ;

accountFilter
    : accountNameFilter | capabilityFilter | relationshipFn
    ;

accountNameFilter
    : "accountName" comparator value
    ;

capabilityFilter
    : "capabilities:" capabilityValue
    | "-capabilities:" capabilityValue
    | "NOT capabilities:" capabilityValue
    ;
capabilityValue
    : "CAN_UPLOAD_PRODUCTS"
    ;

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