Sintaxe do filtro

Em alguns métodos list da API Merchant, como account.list é possível fazer filtragem para receber apenas os resultados que interessam. Para filtrar resultados, use o parâmetro filter com a sintaxe definida na gramática EBNF. Esta página explica como usar a sintaxe para filtrar contas.

Sintaxe

Todos os valores que não forem números inteiros precisam ser colocados entre aspas duplas ("). Para saber quais valores um campo específico aceita, consulte a documentação de referência desse campo.

É possível usar AND para filtrar vários campos na mesma consulta. Também é possível usar AND para combinar vários filtros relationship(...) e service(...). Confira um exemplo que combina vários filtros relationship(...) e service(...):

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

Este exemplo retorna as seguintes contas:

• Todas as contas com uma relação de gerenciamento de conta com outra conta e uma relação adicional pendente de aceitação.

• Todas as contas com o nome de exibição "store" que têm relações com outras contas.

Não é possível usar AND para filtrar vários valores no mesmo campo. Por exemplo, não é possível usar accountName = "*A*" AND accountName = "*B*".

É possível usar OR para filtrar dois campos na mesma consulta. Coloque os critérios de filtro entre parênteses de cada lado do operador OR. Por exemplo, (accountName = "storeA") OR (accountName = "storeB").

Só é possível usar OR para combinar dois campos. Por exemplo, não é possível usar (accountName = "storeA") OR (accountName = "storeB") OR (accountName = "storeC").

Não é permitido usar parênteses, exceto com os operadores AND e OR e em invocações de função, como relationship(...) e service(...).

Para campos de string, como accountName e accountIdAlias, é possível filtrar valores que contêm uma determinada palavra ou sequência de caracteres colocando a sequência entre asteriscos (*). Por exemplo, accountName = "*foo*" retorna todas as contas com um accountName que contém foo, como "storeFoo".

É possível filtrar valores que não contêm uma determinada sequência usando != e *. Por exemplo, accountName != "*foo*" retorna todas as contas com um accountName que não contém foo.

Observação: o filtro por accountIdAlias ou externalAccountId só é possível se um providerId também estiver definido como esses campos. Usar esses campos só faz sentido no contexto de um providerId específico.

Espaços em branco extras são ignorados. Por exemplo, foo AND bar é o mesmo que foo AND bar.

Confira alguns exemplos de filtragem de contas usando o método account.list:

• Todas as subcontas de uma conta avançada que contêm "Loja":

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

• Todas as contas gerenciadas pelo provedor 123456:

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

• Todas as contas que enviaram um convite para o provedor 123456 ou precisam aceitar um convite dele:

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

Para filtrar as contas a que o usuário que faz a solicitação pode acessar, use o método google.shopping.merchant.accounts.v1.ListAccountsRequest, conforme mostrado no exemplo a seguir.

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

Especificação

Os filtros seguem um subconjunto da especificação de filtro da AIP e sua gramática EBNF formal:

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