Metoda accounts.list
umożliwia pobranie listy zasobów Account
, do których ma dostęp uwierzytelniony użytkownik. Za pomocą parametru zapytania filter
możesz zawęzić wyniki na podstawie różnych kryteriów, takich jak:
- Właściwości konta
- Powiązania z innymi kontami (np. dostawcami w zaawansowanej strukturze konta)
- usługi powiązane z kontami,
Może to być przydatne do zarządzania wieloma kontami lub znajdowania konkretnych kont firmowych, które spełniają określone warunki.
Do filtrowania na poziomie account
możesz użyć tych pól:
access
: filtruje według typu dostępu użytkownika doaccount
. Ten filtr akceptuje te wartości:DIRECT
: zwraca tylko konta, do których użytkownik ma bezpośredni dostęp.INDIRECT
: zwraca tylko konta, do których użytkownik ma dostęp pośredni.ALL
: zwraca wszystkie konta, do których użytkownik ma dostęp (bezpośredni i pośredni). Jest to domyślne działanie, jeśli filtr nie jest określony.
capabilities
: Filtruje wedługcapabilities
zasobuaccount
(pamiętaj, że to pole nie jest dostępne w samym zasobie). Obsługiwana jest tylko funkcjaCAN_UPLOAD_PRODUCTS
. To pole obsługuje negację i korzysta ze składni kolekcji.relationship(...)
: Filtruje według typu relacji między kontami. W jednym żądaniu możesz uwzględnić kilka filtrówrelationship(...)
.accountName
: filtruje wedługaccountName
zasobuaccount
.
Więcej informacji o składni filtra znajdziesz w przewodniku Składnia filtra.
Przykłady
Z przykładów poniżej dowiesz się, jak tworzyć najczęstsze zapytania. Wszystkie przykłady poniżej korzystają z metody accounts.list
. Więcej informacji znajdziesz w accounts.list
dokumentacji referencyjnej.
Znajdowanie subkont określonego dostawcy
Metoda
accounts.listSubaccounts
umożliwia bezpośrednie wyświetlanie listy subkont. Możesz też korzystać z funkcji filtrowania opisanych w kolejnych sekcjach. Jeśli zarządzasz kontem zaawansowanym, możesz wyświetlić listę wszystkich jego subkont, filtrując je według ikony providerId
. Zastąp PROVIDER_ID
identyfikatorem konta zaawansowanego.
Na przykład użyj relationship(providerId=123)
, jeśli identyfikator dostawcy to 123
.
Jest to przydatne do zarządzania strukturą kont.
GET https://merchantapi.googleapis.com/accounts/v1/accounts?filter=relationship(providerId%20%3D%20PROVIDER_ID)
Żądanie zakończone powodzeniem zwraca kod stanu 200 i treść odpowiedzi z listą pasujących kont podrzędnych:
{
"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..."
}
Znajdowanie kont, na których nie można przesyłać produktów
Możesz połączyć kilka warunków filtrowania, aby utworzyć bardziej szczegółowe wyszukiwania.
Filtr accountName=*store* AND -capabilities:CAN_UPLOAD_PRODUCTS
znajduje wszystkie konta, które mają w nazwie słowo „store” i nie są skonfigurowane do bezpośredniego przesyłania produktów. Symbol -
przed symbolem capabilities
działa jako operator negacji. Może to być przydatne, jeśli chcesz pobrać tylko konta zaawansowane.
GET https://merchantapi.googleapis.com/accounts/v1/accounts?filter=accountName%20%3D%20%22*store*%22%20AND%20-capabilities%3ACAN_UPLOAD_PRODUCTS
Żądanie zakończone powodzeniem zwraca kod stanu 200 i treść odpowiedzi z listą pasujących kont:
{
"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..."
}
Znajdź konta według nazwy
Możesz wyszukiwać konta, których nazwa wyświetlana pasuje do określonego wzorca.
Na przykład accountName=*store*
znajdzie wszystkie konta, których nazwa zawiera słowo „store”.
Ułatwia to szybkie znajdowanie konkretnych kont firmowych.
GET https://merchantapi.googleapis.com/accounts/v1/accounts?filter=accountName%20%3D%20%22*store*%22
Żądanie zakończone powodzeniem zwraca kod stanu 200 i treść odpowiedzi z listą pasujących kont:
{
"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..."
}
Znajdowanie kont powiązanych z dostawcą w przypadku konkretnej usługi
Możesz znaleźć konta, które mają określone relacje z usługodawcą.
Aby na przykład znaleźć wszystkie konta zgrupowane w ramach dostawcy PROVIDER_ID
na potrzeby grupowania kont, użyj filtra 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))
Żądanie zakończone powodzeniem zwraca kod stanu 200 i treść odpowiedzi z listą pasujących kont:
{
"accounts": [
{
"name": "accounts/54321",
"accountId": "54321",
"accountName": "Aggregated Account X",
"adultContent": false,
"languageCode": "en",
"timeZone": {
"id": "America/New_York"
}
}
]
}
Znajdowanie kont na podstawie stanu zatwierdzenia relacji z usługą
Możesz filtrować konta na podstawie stanu relacji z dostawcą usług. Możesz na przykład znaleźć wszystkie konta, na których nie zaakceptowano prośby o połączenie konta (handshakeState = "PENDING")
od konkretnego dostawcyPROVIDER_ID
.
Aby na przykład znaleźć konta, w których identyfikator dostawcy to 123
, typ usługi to ACCOUNT_MANAGEMENT
, a stan to PENDING
, użyj 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)
Żądanie zakończone powodzeniem zwraca kod stanu 200 i treść odpowiedzi z listą pasujących kont:
{
"accounts": [
{
"name": "accounts/98765",
"accountId": "98765",
"accountName": "Managed Account Y",
"adultContent": false,
"languageCode": "es",
"timeZone": {
"id": "Europe/Madrid"
}
}
]
}
Filtrowanie kont za pomocą bibliotek klienta
Poniższe przykłady pokazują, jak za pomocą bibliotek klienta filtrować konta na podstawie połączonych kryteriów, takich jak nazwa konta i relacja z dostawcą. W tych przykładach użyto metody accounts.list
. Więcej informacji znajdziesz w accounts.list
dokumentacji referencyjnej.
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>'