Filtra las cuentas a las que puedes acceder

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

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

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

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

  • capabilities: Filtra por las 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 la colección.
  • relationship(...): Filtra por el tipo de relación que tiene la cuenta con otra cuenta. Puedes incluir varios filtros relationship(...) en una solicitud.
  • accountName: Filtra por el accountName del recurso account.

Para obtener información más detallada sobre la sintaxis del filtro, consulta la guía Filter syntax.

Ejemplos

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

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

El accounts.listSubaccounts método proporciona una forma directa de enumerar las cuentas secundarias. También puedes usar las capacidades de filtrado como se describe 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 "store" en su nombre que no están configuradas para subir productos directamente. El - antes de capabilities actúa como un operador de negación. Esto puede ser útil para recuperar solo 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..."
}

Cómo encontrar 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 con "store" en su nombre.

Esto ayuda a ubicar rápidamente cuentas comerciales 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 tengan 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 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 vínculo de cuenta (handshakeState = "PENDING") de un proveedor específico PROVIDER_ID.

Por ejemplo, para encontrar cuentas en las que el ID del proveedor sea 123, el tipo de servicio sea ACCOUNT_MANAGEMENT y el estado sea 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 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 accounts.list documentación de referencia.

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'
Anterior
Control access to your account
Siguiente
Filter syntax