O método accounts.list
permite recuperar uma lista de
recursos Account
que
o usuário autenticado pode acessar. É possível usar o parâmetro de consulta filter
para restringir os resultados com base em vários critérios, como:
- Propriedades da conta
- Relacionamentos com outras contas (como provedores em uma estrutura de conta avançada)
- Serviços associados às contas
Isso pode ser útil para gerenciar várias contas ou encontrar contas comerciais específicas que atendam a determinadas condições.
É possível usar os seguintes campos para filtrar no nível account
:
access
: filtra pelo tipo de acesso que o usuário tem aoaccount
. Esse filtro aceita os seguintes valores:DIRECT
: retorna apenas as contas a que o usuário tem acesso direto.INDIRECT
: retorna apenas as contas a que o usuário tem acesso indireto.ALL
: retorna todas as contas a que o usuário tem acesso (direto e indireto). Esse é o comportamento padrão se o filtro não for especificado.
capabilities
: filtra pelocapabilities
do recursoaccount
. Observe que esse campo não está disponível no próprio recurso. Somente a capacidadeCAN_UPLOAD_PRODUCTS
é compatível. Esse campo aceita negação e usa a sintaxe de coleção.relationship(...)
: filtra pelo tipo de relacionamento que a conta tem com outra conta. É possível incluir vários filtrosrelationship(...)
em uma solicitação.accountName
: filtra peloaccountName
do recursoaccount
.
Para mais informações sobre a sintaxe de filtro, consulte o guia Sintaxe de filtro.
Exemplos
Os exemplos a seguir explicam como formar as consultas mais típicas. Todos os exemplos a seguir usam o método accounts.list
. Para mais informações, consulte a documentação de referência accounts.list
.
Encontrar subcontas de um provedor específico
O método
accounts.listSubaccounts
oferece uma maneira direta de listar subcontas. Você também pode usar os recursos de filtragem, conforme descrito nas seções a seguir. Se você gerencia uma conta avançada, pode listar todas as subcontas filtrando por providerId
. Substitua PROVIDER_ID
pelo ID da sua conta avançada.
Por exemplo, use relationship(providerId=123)
se o ID do provedor for
123
.
Isso é útil para gerenciar a estrutura das suas contas.
GET https://merchantapi.googleapis.com/accounts/v1/accounts?filter=relationship(providerId%20%3D%20PROVIDER_ID)
Uma solicitação bem-sucedida retorna um código de status 200 e um corpo de resposta com a lista de subcontas correspondentes:
{
"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..."
}
Encontrar contas que não podem fazer upload de produtos
É possível combinar várias condições de filtro para criar pesquisas mais específicas.
O filtro accountName=*store* AND -capabilities:CAN_UPLOAD_PRODUCTS
encontra todas as contas com "store" no nome que não estão configuradas para fazer upload de produtos diretamente. O -
antes de capabilities
funciona como um operador de negação. Isso pode ser útil para recuperar apenas contas avançadas.
GET https://merchantapi.googleapis.com/accounts/v1/accounts?filter=accountName%20%3D%20%22*store*%22%20AND%20-capabilities%3ACAN_UPLOAD_PRODUCTS
Uma solicitação bem-sucedida retorna um código de status 200 e um corpo de resposta com a lista de contas correspondentes:
{
"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..."
}
Localizar contas por nome
Você pode pesquisar contas cujo nome de exibição corresponda a um padrão específico.
Por exemplo, accountName=*store*
encontraria todas as contas com "store" no nome.
Isso ajuda a localizar rapidamente contas comerciais específicas.
GET https://merchantapi.googleapis.com/accounts/v1/accounts?filter=accountName%20%3D%20%22*store*%22
Uma solicitação bem-sucedida retorna um código de status 200 e um corpo de resposta com a lista de contas correspondentes:
{
"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..."
}
Encontrar contas vinculadas a um provedor para um serviço específico
Você pode encontrar contas que têm uma relação de serviço específica com um provedor.
Por exemplo, para encontrar todas as contas agregadas no provedor PROVIDER_ID
para agregação de contas, use o 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))
Uma solicitação bem-sucedida retorna um código de status 200 e um corpo de resposta com a lista de contas correspondentes:
{
"accounts": [
{
"name": "accounts/54321",
"accountId": "54321",
"accountName": "Aggregated Account X",
"adultContent": false,
"languageCode": "en",
"timeZone": {
"id": "America/New_York"
}
}
]
}
Encontrar contas com base no estado de aprovação da relação de serviço
É possível filtrar contas com base no status da relação de serviço com um provedor. Por exemplo, para encontrar todas as contas que não aceitaram um pedido de vinculação de conta (handshakeState = "PENDING")
de um provedor específico PROVIDER_ID
.
Por exemplo, para encontrar contas em que o ID do provedor é 123
, o tipo de serviço é ACCOUNT_MANAGEMENT
e o status é PENDING
, use 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)
Uma solicitação bem-sucedida retorna um código de status 200 e um corpo de resposta com a lista de contas correspondentes:
{
"accounts": [
{
"name": "accounts/98765",
"accountId": "98765",
"accountName": "Managed Account Y",
"adultContent": false,
"languageCode": "es",
"timeZone": {
"id": "Europe/Madrid"
}
}
]
}
Filtrar contas usando bibliotecas de cliente
Os exemplos a seguir mostram como usar bibliotecas de cliente para filtrar contas com base em critérios combinados, como nome da conta e relacionamento com um provedor. Estes exemplos usam o método accounts.list
. Para mais informações, consulte a documentação de referência do 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>'