Esta página foi traduzida pela API Cloud Translation.

Filtrar contas que você pode acessar

O método accounts.list permite recuperar uma lista de recursos Account que o usuário autenticado pode acessar. É possível usar o parâmetro de consulta filter para restringir os resultados com base em vários critérios, como:

Propriedades da conta
Relacionamentos com outras contas (como provedores em uma estrutura de conta avançada)
Serviços associados às contas

Isso pode ser útil para gerenciar várias contas ou encontrar contas comerciais específicas que atendam a determinadas condições.

É possível usar os seguintes campos para filtrar no nível account:

access: filtra pelo tipo de acesso que o usuário tem ao account. Esse filtro aceita os seguintes valores:
- DIRECT: retorna apenas as contas a que o usuário tem acesso direto.
- INDIRECT: retorna apenas as contas a que o usuário tem acesso indireto.
- ALL: retorna todas as contas a que o usuário tem acesso (direto e indireto). Esse é o comportamento padrão se o filtro não for especificado.
capabilities: filtra pelo capabilities do recurso account. Observe que esse campo não está disponível no próprio recurso. Somente a capacidade CAN_UPLOAD_PRODUCTS é compatível. Esse campo aceita negação e usa a sintaxe de coleção.
relationship(...): filtra pelo tipo de relacionamento que a conta tem com outra conta. É possível incluir vários filtros relationship(...) em uma solicitação.
accountName: filtra pelo accountName do recurso account.

Para mais informações sobre a sintaxe de filtro, consulte o guia Sintaxe de filtro.

Exemplos

Os exemplos a seguir explicam como formar as consultas mais típicas. Todos os exemplos a seguir usam o método accounts.list. Para mais informações, consulte a documentação de referência accounts.list.

Encontrar subcontas de um provedor específico

O método accounts.listSubaccounts oferece uma maneira direta de listar subcontas. Você também pode usar os recursos de filtragem, conforme descrito nas seções a seguir. Se você gerencia uma conta avançada, pode listar todas as subcontas filtrando por providerId. Substitua PROVIDER_ID pelo ID da sua conta avançada.

Por exemplo, use relationship(providerId=123) se o ID do provedor for 123.

Isso é útil para gerenciar a estrutura das suas contas.

GET https://merchantapi.googleapis.com/accounts/v1/accounts?filter=relationship(providerId%20%3D%20PROVIDER_ID)

Uma solicitação bem-sucedida retorna um código de status 200 e um corpo de resposta com a lista de subcontas correspondentes:

{
  "accounts": [
    {
      "name": "accounts/77777",
      "accountId": "77777",
      "accountName": "SubAccount A of Provider",
      "adultContent": false,
      "languageCode": "fr",
      "timeZone": {
        "id": "Europe/Paris"
      }
    },
    {
      "name": "accounts/88888",
      "accountId": "88888",
      "accountName": "SubAccount B of Provider",
      "adultContent": false,
      "languageCode": "de",
      "timeZone": {
        "id": "Europe/Berlin"
      }
    }
  ],
  "nextPageToken": "XYZ123abcDEF..."
}

Encontrar contas que não podem fazer upload de produtos

É possível combinar várias condições de filtro para criar pesquisas mais específicas.

O filtro accountName=*store* AND -capabilities:CAN_UPLOAD_PRODUCTS encontra todas as contas com "store" no nome que não estão configuradas para fazer upload de produtos diretamente. O - antes de capabilities funciona como um operador de negação. Isso pode ser útil para recuperar apenas contas avançadas.

GET https://merchantapi.googleapis.com/accounts/v1/accounts?filter=accountName%20%3D%20%22*store*%22%20AND%20-capabilities%3ACAN_UPLOAD_PRODUCTS

Uma solicitação bem-sucedida retorna um código de status 200 e um corpo de resposta com a lista de contas correspondentes:

{
  "accounts": [
    {
      "name": "accounts/54321",
      "accountId": "54321",
      "accountName": "Partner Store - US",
      "adultContent": false,
      "languageCode": "en",
      "timeZone": {
        "id": "America/New_York"
      }
    },
    {
      "name": "accounts/98765",
      "accountId": "98765",
      "accountName": "Auxiliary Brand Store",
      "adultContent": false,
      "languageCode": "fr",
      "timeZone": {
        "id": "Europe/Paris"
      }
    }
  ],
  "nextPageToken": "CDEfghIJKlmnOPQ..."
}

Localizar contas por nome

Você pode pesquisar contas cujo nome de exibição corresponda a um padrão específico.

Por exemplo, accountName=*store* encontraria todas as contas com "store" no nome.

Isso ajuda a localizar rapidamente contas comerciais específicas.

GET https://merchantapi.googleapis.com/accounts/v1/accounts?filter=accountName%20%3D%20%22*store*%22

Uma solicitação bem-sucedida retorna um código de status 200 e um corpo de resposta com a lista de contas correspondentes:

{
  "accounts": [
    {
      "name": "accounts/12345",
      "accountId": "12345",
      "accountName": "My Awesome Store",
      "adultContent": false,
      "languageCode": "en",
      "timeZone": {
        "id": "America/Los_Angeles"
      }
    },
    {
      "name": "accounts/67890",
      "accountId": "67890",
      "accountName": "Another Store Online",
      "adultContent": false,
      "languageCode": "en",
      "timeZone": {
        "id": "Europe/London"
      }
    }
  ],
  "nextPageToken": "ABSdefGHIjklMNO..."
}

Encontrar contas vinculadas a um provedor para um serviço específico

Você pode encontrar contas que têm uma relação de serviço específica com um provedor. Por exemplo, para encontrar todas as contas agregadas no provedor PROVIDER_ID para agregação de contas, use o filtro relationship(providerId=PROVIDER_ID) AND service(type="ACCOUNT_AGGREGATION").

GET https://merchantapi.googleapis.com/accounts/v1/accounts?filter=relationship(providerId%20%3D%20PROVIDER_ID%20AND%20service(type%20%3D%20%22ACCOUNT_AGGREGATION%22))

Uma solicitação bem-sucedida retorna um código de status 200 e um corpo de resposta com a lista de contas correspondentes:

{
  "accounts": [
    {
      "name": "accounts/54321",
      "accountId": "54321",
      "accountName": "Aggregated Account X",
      "adultContent": false,
      "languageCode": "en",
      "timeZone": {
        "id": "America/New_York"
      }
    }
  ]
}

Encontrar contas com base no estado de aprovação da relação de serviço

É possível filtrar contas com base no status da relação de serviço com um provedor. Por exemplo, para encontrar todas as contas que não aceitaram um pedido de vinculação de conta (handshakeState = "PENDING") de um provedor específico PROVIDER_ID.

Por exemplo, para encontrar contas em que o ID do provedor é 123, o tipo de serviço é ACCOUNT_MANAGEMENT e o status é PENDING, use relationship(service(handshakeState = "PENDING" AND type = "ACCOUNT_MANAGEMENT") AND providerId = 123).

GET https://merchantapi.googleapis.com/accounts/v1/accounts?filter=relationship(service(handshakeState%20%3D%20%22PENDING%22%20AND%20type%20%3D%20%22ACCOUNT_MANAGEMENT%22)%20AND%20providerId%20%3D%20PROVIDER_ID)

Uma solicitação bem-sucedida retorna um código de status 200 e um corpo de resposta com a lista de contas correspondentes:

{
  "accounts": [
    {
      "name": "accounts/98765",
      "accountId": "98765",
      "accountName": "Managed Account Y",
      "adultContent": false,
      "languageCode": "es",
      "timeZone": {
        "id": "Europe/Madrid"
      }
    }
  ]
}

Filtrar contas usando bibliotecas de cliente

Os exemplos a seguir mostram como usar bibliotecas de cliente para filtrar contas com base em critérios combinados, como nome da conta e relacionamento com um provedor. Estes exemplos usam o método accounts.list. Para mais informações, consulte a documentação de referência do accounts.list.

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

PHP

use Google\ApiCore\ApiException;
use Google\Shopping\Merchant\Accounts\V1\Client\AccountsServiceClient;
use Google\Shopping\Merchant\Accounts\V1\ListAccountsRequest;

/**
 * This class demonstrates how to filter the accounts the user making the request has access to.
 */
class FilterAccounts
{
    public static function filterAccounts(array $config): void
    {

        // Gets the OAuth credentials to make the request.
        $credentials = Authentication::useServiceAccountOrTokenFile();

        // Creates options config containing credentials for the client to use.
        $options = ['credentials' => $credentials];

        // Creates a client.
        $accountsServiceClient = new AccountsServiceClient($options);

        // Calls the API and catches and prints any network failures/errors.
        try {

            // Filter for accounts with display names containing "store" and a provider with the ID "123":
            $filter = "accountName = \"*store*\" AND relationship(providerId = 123)";

            // Filter for all subaccounts of account "123":
            // $filter = "relationship(providerId = 123 AND service(type = \"ACCOUNT_AGGREGATION\"))";

            // $filter = "relationship(service(handshakeState = \"APPROVED\" AND type =
            // \"ACCOUNT_MANAGEMENT\") AND providerId = 123)";

            $request = new ListAccountsRequest(['filter' => $filter]);

            print "Sending list accounts request with filter:\n";
            $response = $accountsServiceClient->listAccounts($request);

            $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.
            foreach ($response->iterateAllElements() as $account) {
                print_r($account); 
                $count++;
            }
            print "The following count of elements were returned: ";
            print $count . PHP_EOL;
        } catch (ApiException $e) {
            print $e->getMessage();
        }
    }

    public function callSample(): void
    {
        $config = Config::generateConfig();
        self::filterAccounts($config);
    }
}

$sample = new FilterAccounts();
$sample->callSample();FilterAccountsSample.php

Python

from examples.authentication import generate_user_credentials
from google.shopping.merchant_accounts_v1 import AccountsServiceClient
from google.shopping.merchant_accounts_v1 import ListAccountsRequest


def filter_accounts():
  """Filters the accounts the user making the request has access to."""

  # Get OAuth credentials.
  credentials = generate_user_credentials.main()

  # Create a client.
  client = AccountsServiceClient(credentials=credentials)

  # Create the filter string.
  filter_string = 'accountName = "*store*" AND relationship(providerId = 123)'

  # Create the request.
  request = ListAccountsRequest(filter=filter_string)

  # Make the request and print the response.
  try:
    print("Sending list accounts request with filter:")
    response = client.list_accounts(request=request)

    count = 0
    for account in response:
      print(account)
      count += 1

    print(f"The following count of elements were returned: {count}")

  except RuntimeError as e:
    print(e)


if __name__ == "__main__":
  filter_accounts()
filter_accounts_sample.py

AppsScript


/**
 * Filters and lists accounts for which the logged-in user has access to
 */
function filterAccounts() {
  // IMPORTANT:
  // Enable the Merchant API Accounts sub-API Advanced Service and call it
  // "MerchantApiAccounts"

  // Create the filter string.
  // Documentation can be found at
  // https://developers.google.com/merchant/api/guides/accounts/filter-syntax
  const filter = 'accountName = "*store*" AND relationship(providerId = 123)';
  try {
    console.log('Sending filter Accounts request');
    let pageToken;
    let pageSize = 500;
    // Call the Accounts.list API method with a filter. Use the pageToken to iterate through
    // all pages of results.
    do {
      response =
          MerchantApiAccounts.Accounts.list({pageSize, pageToken, filter});
      for (const account of response.accounts) {
        console.log(account);
      }
      pageToken = response.nextPageToken;
    } while (pageToken);  // Exits when there is no next page token.

  } catch (e) {
    console.log('ERROR!');
    console.log(e);
  }
}filter_accounts_sample.gs

cURL

curl --location 'https://merchantapi.googleapis.com/accounts/v1/accounts?filter=accountName%20%3D%20%22*store*%22%20AND%20relationship(providerId%20%3D%20PROVIDER_ID)' \
--header 'Authorization: Bearer <API_TOKEN>'

Create and manage sub-accounts

Avançar

Control access to your account

Filtrar contas que você pode acessar Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Exemplos

Encontrar subcontas de um provedor específico

Encontrar contas que não podem fazer upload de produtos

Localizar contas por nome

Encontrar contas vinculadas a um provedor para um serviço específico

Encontrar contas com base no estado de aprovação da relação de serviço

Filtrar contas usando bibliotecas de cliente

Java

PHP

Python

AppsScript

cURL

Filtrar contas que você pode acessar