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 consulta filter para
reducir los resultados según varios criterios, como los siguientes:
- Propiedades de la cuenta
- Relaciones con otras cuentas (como proveedores en una estructura de cuenta avanzada)
- Servicios asociados con las cuentas
Esto puede ser útil para administrar varias cuentas o encontrar cuentas de empresa 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 laaccount. Este filtro acepta los siguientes valores:DIRECT: Devuelve solo las cuentas a las que el usuario tiene acceso directo. Estas son las cuentas a las que se agregó directamente al usuario.INDIRECT: Solo devuelve las cuentas a las que el usuario tiene acceso indirecto. Estas son cuentas a las que el usuario puede acceder sin ser un usuario de la cuenta. Por ejemplo, un usuario de una MCA tendría acceso "INDIRECTO" a una cuenta secundaria de la MCA. Del mismo modo, los usuarios de un CSS tendrían acceso indirecto a las cuentas que trabajan con el CSS.ALL: Devuelve todas las cuentas a las que tiene acceso el usuario (tanto directas como indirectas). Este es el comportamiento predeterminado si no se especifica el filtro.
capabilities: Filtra por elcapabilitiesdel 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 solicitud.accountName: Filtra por elaccountNamedel recursoaccount.
Para obtener información más detallada sobre la sintaxis de los filtros, consulta la guía Sintaxis de los 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 buscar 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
funciones 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 que coinciden:
{
"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..."
}
Busca cuentas que no puedan 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 que tienen "store" en su nombre y 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 que coinciden:
{
"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 tengan "tienda" en su nombre.
Esto ayuda a encontrar rápidamente cuentas de empresa 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 que coinciden:
{
"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..."
}
Busca 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 que coinciden:
{
"accounts": [
{
"name": "accounts/54321",
"accountId": "54321",
"accountName": "Aggregated Account X",
"adultContent": false,
"languageCode": "en",
"timeZone": {
"id": "America/New_York"
}
}
]
}
Busca 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 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 que coinciden:
{
"accounts": [
{
"name": "accounts/98765",
"accountId": "98765",
"accountName": "Managed Account Y",
"adultContent": false,
"languageCode": "es",
"timeZone": {
"id": "Europe/Madrid"
}
}
]
}
Filtra 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;
const pageSize = 500;
// Call the Accounts.list API method with a filter. Use the pageToken to iterate through
// all pages of results.
do {
const 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'