Filtrer les comptes auxquels vous pouvez accéder

La méthode accounts.list vous permet de récupérer la liste des ressources Account auxquelles l'utilisateur authentifié peut accéder. Vous pouvez utiliser le paramètre de requête filter pour affiner les résultats en fonction de différents critères, tels que les suivants :

  • Propriétés du compte
  • Relations avec d'autres comptes (par exemple, les fournisseurs dans une structure de compte avancée)
  • Services associés aux comptes

Cela peut être utile pour gérer plusieurs comptes ou trouver des comptes d'établissement spécifiques qui répondent à certaines conditions.

Vous pouvez utiliser les champs suivants pour filtrer au niveau account :

  • access : filtre en fonction du type d'accès dont dispose l'utilisateur au account. Ce filtre accepte les valeurs suivantes :
    • DIRECT : ne renvoie que les comptes auxquels l'utilisateur a un accès direct.
    • INDIRECT : ne renvoie que les comptes auxquels l'utilisateur a un accès indirect.
    • ALL : renvoie tous les comptes auxquels l'utilisateur a accès (directement et indirectement). Il s'agit du comportement par défaut si le filtre n'est pas spécifié.
  • capabilities : filtre par capabilities de la ressource account (notez que ce champ n'est pas disponible sur la ressource elle-même). Seule la fonctionnalité CAN_UPLOAD_PRODUCTS est prise en charge. Ce champ accepte la négation et utilise la syntaxe de collection.
  • relationship(...) : filtre en fonction du type de relation entre le compte et un autre compte. Vous pouvez inclure plusieurs filtres relationship(...) dans une même requête.
  • accountName : filtre par accountName de la ressource account.

Pour en savoir plus sur la syntaxe des filtres, consultez le guide Syntaxe des filtres.

Exemples

Les exemples suivants expliquent comment formuler les requêtes les plus courantes. Tous les exemples suivants utilisent la méthode accounts.list. Pour en savoir plus, consultez la documentation de référence de accounts.list.

Rechercher les sous-comptes d'un fournisseur spécifique

La méthode accounts.listSubaccounts permet de lister directement les sous-comptes. Vous pouvez également utiliser les fonctionnalités de filtrage décrites dans les sections suivantes. Si vous gérez un compte avancé, vous pouvez lister tous ses sous-comptes en filtrant sur providerId. Remplacez PROVIDER_ID par l'ID de votre compte avancé.

Par exemple, utilisez relationship(providerId=123) si l'ID du fournisseur est 123.

Cela est utile pour gérer la structure de vos comptes.

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

Une requête réussie renvoie un code d'état 200 et un corps de réponse avec la liste des sous-comptes correspondants :

{
  "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..."
}

Identifier les comptes qui ne peuvent pas importer de produits

Vous pouvez combiner plusieurs conditions de filtrage pour affiner vos recherches.

Le filtre accountName=*store* AND -capabilities:CAN_UPLOAD_PRODUCTS trouve tous les comptes dont le nom contient "magasin" et qui ne sont pas configurés pour importer des produits directement. Le - avant capabilities agit comme un opérateur de négation. Cela peut être utile pour ne récupérer que les comptes avancés.

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

Une requête réussie renvoie un code d'état 200 et un corps de réponse contenant la liste des comptes correspondants :

{
  "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..."
}

Rechercher des comptes par nom

Vous pouvez rechercher des comptes dont le nom à afficher correspond à un modèle spécifique.

Par exemple, accountName=*store* trouverait tous les comptes dont le nom contient "magasin".

Cela permet de localiser rapidement des comptes d'entreprise spécifiques.

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

Une requête réussie renvoie un code d'état 200 et un corps de réponse contenant la liste des comptes correspondants :

{
  "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..."
}

Rechercher les comptes associés à un fournisseur pour un service spécifique

Vous pouvez trouver les comptes qui ont une relation de service spécifique avec un fournisseur. Par exemple, pour trouver tous les comptes agrégés sous le fournisseur PROVIDER_ID pour l'agrégation de comptes, utilisez le filtre 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))

Une requête réussie renvoie un code d'état 200 et un corps de réponse contenant la liste des comptes correspondants :

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

Rechercher des comptes en fonction de l'état d'approbation de la relation de service

Vous pouvez filtrer les comptes en fonction de l'état de leur relation de service avec un fournisseur. Par exemple, pour trouver tous les comptes qui n'ont pas accepté une demande d'association de compte (handshakeState = "PENDING") d'un fournisseur spécifique PROVIDER_ID.

Par exemple, pour trouver les comptes dont l'ID de fournisseur est 123, le type de service est ACCOUNT_MANAGEMENT et l'état est PENDING, utilisez 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)

Une requête réussie renvoie un code d'état 200 et un corps de réponse contenant la liste des comptes correspondants :

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

Filtrer les comptes à l'aide des bibliothèques clientes

Les exemples suivants montrent comment utiliser les bibliothèques clientes pour filtrer les comptes en fonction de critères combinés, tels que le nom du compte et la relation avec un fournisseur. Ces exemples utilisent la méthode accounts.list. Pour en savoir plus, consultez la documentation de référence de 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);
  }
}

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

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()

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

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>'