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 aaccount
. 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 elcapabilities
del recursoaccount
(ten en cuenta que este campo no está disponible en el recurso en sí). Solo se admite la capacidadCAN_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 filtrosrelationship(...)
en una misma solicitud.accountName
: Filtra por elaccountName
del recursoaccount
.
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>'