Filtra las cuentas a las que puedes acceder

El método accounts.list te permite recuperar una lista de recursos Account a los que puede acceder el usuario autenticado. Puedes usar el parámetro de búsqueda filter para limitar los resultados según varios criterios, como los siguientes:

  • Propiedades de la cuenta
  • Relaciones con otras cuentas (por ejemplo, proveedores en una estructura de cuentas avanzada)
  • Servicios asociados con las cuentas

Esto puede ser útil para administrar varias cuentas o encontrar cuentas de empresas específicas que cumplan con ciertas condiciones.

Puedes usar los siguientes campos para filtrar a nivel de account:

  • access: Filtra por el tipo de acceso que tiene el usuario a account. Este filtro acepta los siguientes valores:
    • DIRECT: Solo devuelve las cuentas a las que el usuario tiene acceso directo.
    • INDIRECT: Solo devuelve las cuentas a las que el usuario tiene acceso indirecto.
    • ALL: Devuelve todas las cuentas a las que el usuario tiene acceso (tanto directo como indirecto). Este es el comportamiento predeterminado si no se especifica el filtro.
  • capabilities: Filtra por el capabilities del recurso account (ten en cuenta que este campo no está disponible en el recurso en sí). Solo se admite la capacidad CAN_UPLOAD_PRODUCTS. Este campo admite la negación y usa la sintaxis de colección.
  • relationship(...): Filtra por el tipo de relación que tiene la cuenta con otra cuenta. Puedes incluir varios filtros relationship(...) en una misma solicitud.
  • accountName: Filtra por el accountName del recurso account.

Para obtener información más detallada sobre la sintaxis de los filtros, consulta la guía de sintaxis de filtros.

Ejemplos

En los siguientes ejemplos, se explica cómo formar las consultas más típicas. En todos los ejemplos siguientes, se usa el método accounts.list. Para obtener más información, consulta la documentación de referencia de accounts.list.

Cómo encontrar las cuentas secundarias de un proveedor específico

El método accounts.listSubaccounts proporciona una forma directa de enumerar las cuentas secundarias. También puedes usar las capacidades de filtrado que se describen en las siguientes secciones. Si administras una cuenta avanzada, puedes enumerar todas sus cuentas secundarias filtrando por providerId. Reemplaza PROVIDER_ID por el ID de tu cuenta avanzada.

Por ejemplo, usa relationship(providerId=123) si el ID del proveedor es 123.

Esto es útil para administrar la estructura de tus cuentas.

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

Una solicitud correcta devuelve un código de estado 200 y un cuerpo de respuesta con la lista de cuentas secundarias coincidentes:

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

Cómo encontrar cuentas que no pueden subir productos

Puedes combinar varias condiciones de filtro para crear búsquedas más específicas.

El filtro accountName=*store* AND -capabilities:CAN_UPLOAD_PRODUCTS encuentra todas las cuentas con la palabra "tienda" en su nombre que no están configuradas para subir productos directamente. El - que precede a capabilities actúa como operador de negación. Esto puede ser útil para recuperar solo las cuentas avanzadas.

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

Una solicitud correcta devuelve un código de estado 200 y un cuerpo de respuesta con la lista de cuentas coincidentes:

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

Buscar cuentas por nombre

Puedes buscar cuentas cuyo nombre visible coincida con un patrón específico.

Por ejemplo, accountName=*store* encontraría todas las cuentas que contengan "tienda" en su nombre.

Esto ayuda a ubicar rápidamente cuentas de empresas específicas.

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

Una solicitud correcta devuelve un código de estado 200 y un cuerpo de respuesta con la lista de cuentas coincidentes:

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

Cómo encontrar cuentas vinculadas a un proveedor para un servicio específico

Puedes encontrar cuentas que tienen una relación de servicio específica con un proveedor. Por ejemplo, para encontrar todas las cuentas agregadas en el proveedor PROVIDER_ID para la agregación de cuentas, usa el 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))

Una solicitud correcta devuelve un código de estado 200 y un cuerpo de respuesta con la lista de cuentas coincidentes:

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

Cómo encontrar cuentas según el estado de aprobación de la relación de servicio

Puedes filtrar las cuentas según el estado de su relación de servicio con un proveedor. Por ejemplo, para encontrar todas las cuentas que no aceptaron una solicitud de vinculación de cuenta (handshakeState = "PENDING") de un proveedor específico PROVIDER_ID.

Por ejemplo, para encontrar las cuentas en las que el ID del proveedor es 123, el tipo de servicio es ACCOUNT_MANAGEMENT y el estado es PENDING, usa 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)

Una solicitud correcta devuelve un código de estado 200 y un cuerpo de respuesta con la lista de cuentas coincidentes:

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

Cómo filtrar cuentas con bibliotecas cliente

En los siguientes ejemplos, se muestra cómo usar las bibliotecas cliente para filtrar cuentas según criterios combinados, como el nombre de la cuenta y la relación con un proveedor. En estos ejemplos, se usa el método accounts.list. Para obtener más información, consulta la documentación de referencia 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>'