accounts.list 方法可讓您擷取已驗證使用者可存取的 Account 資源清單。您可以使用 filter 查詢參數，根據各種條件縮小結果範圍，例如：
- 帳戶屬性
- 與其他帳戶的關係 (例如進階帳戶結構中的供應商)
- 與帳戶相關聯的服務
這有助於管理多個帳戶，或找出符合特定條件的商家帳戶。
您可以使用下列欄位，在 account 層級進行篩選：
access：依使用者對account的存取權類型篩選。這項篩選器接受下列值：DIRECT：只會傳回使用者可直接存取的帳戶。INDIRECT：只會傳回使用者可間接存取的帳戶。ALL：傳回使用者有權存取的所有帳戶 (直接和間接)。如果未指定篩選器，系統會預設採用這項行為。
capabilities：依account資源的capabilities篩選 (請注意，這個欄位本身不適用於資源)。系統僅支援CAN_UPLOAD_PRODUCTS功能。這個欄位支援否定，並使用集合語法。relationship(...)：依帳戶與其他帳戶的關係類型篩選。您可以在一個要求中加入多個relationship(...)篩選器。accountName：依account資源的accountName篩選。
如要進一步瞭解篩選器語法，請參閱「篩選器語法」指南。
範例
下列範例說明如何形成最典型的查詢。下列範例都使用 accounts.list 方法。詳情請參閱 accounts.list 參考說明文件。
尋找特定供應商的子帳戶
accounts.listSubaccounts 方法可直接列出子帳戶。您也可以使用下列各節所述的篩選功能。如果您管理進階帳戶，可以透過篩選 providerId 列出所有子帳戶。將 PROVIDER_ID 替換為進階帳戶的 ID。
舉例來說，如果提供者的 ID 是 123，請使用 relationship(providerId=123)。
這有助於管理帳戶結構。
GET https://merchantapi.googleapis.com/accounts/v1/accounts?filter=relationship(providerId%20%3D%20PROVIDER_ID)
如果要求成功，系統會傳回 200 狀態碼和回應本文，其中包含相符子帳戶的清單：
{
"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..."
}
找出無法上傳產品的帳戶
你可以結合多個篩選條件，進行更精確的搜尋。
篩選器 accountName=*store* AND -capabilities:CAN_UPLOAD_PRODUCTS 會找出名稱中含有「商店」的所有帳戶，這些帳戶未設定直接上傳產品。capabilities 前的 - 會做為否定運算子。這項功能有助於只擷取進階帳戶。
GET https://merchantapi.googleapis.com/accounts/v1/accounts?filter=accountName%20%3D%20%22*store*%22%20AND%20-capabilities%3ACAN_UPLOAD_PRODUCTS
如果要求成功，系統會傳回 200 狀態碼和回應本文，其中包含相符帳戶的清單：
{
"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..."
}
依名稱尋找帳戶
您可以搜尋顯示名稱符合特定模式的帳戶。
舉例來說，accountName=*store* 會找出名稱中含有「store」的所有帳戶。
方便快速找到特定商家帳戶。
GET https://merchantapi.googleapis.com/accounts/v1/accounts?filter=accountName%20%3D%20%22*store*%22
如果要求成功，系統會傳回 200 狀態碼和回應本文，其中包含相符帳戶的清單：
{
"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..."
}
尋找與特定服務的供應商連結的帳戶
您可以找出與供應商有特定服務關係的帳戶。舉例來說，如要找出在帳戶匯總功能中，由供應商 PROVIDER_ID 匯總的所有帳戶，請使用篩選器 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))
如果要求成功，系統會傳回 200 狀態碼和回應本文，其中包含相符帳戶的清單：
{
"accounts": [
{
"name": "accounts/54321",
"accountId": "54321",
"accountName": "Aggregated Account X",
"adultContent": false,
"languageCode": "en",
"timeZone": {
"id": "America/New_York"
}
}
]
}
根據服務關係核准狀態尋找帳戶
您可以根據帳戶與供應商的服務關係狀態篩選帳戶。舉例來說，如要找出尚未接受特定供應商 PROVIDER_ID 帳戶連結要求 (handshakeState = "PENDING") 的所有帳戶。
舉例來說，如要找出供應商 ID 為 123、服務類型為 ACCOUNT_MANAGEMENT 且狀態為 PENDING 的帳戶，請使用 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)
如果要求成功，系統會傳回 200 狀態碼和回應本文，其中包含相符帳戶的清單：
{
"accounts": [
{
"name": "accounts/98765",
"accountId": "98765",
"accountName": "Managed Account Y",
"adultContent": false,
"languageCode": "es",
"timeZone": {
"id": "Europe/Madrid"
}
}
]
}
使用用戶端程式庫篩選帳戶
下列範例示範如何使用用戶端程式庫，根據合併條件 (例如帳戶名稱和與供應商的關係) 篩選帳戶。這些範例使用 accounts.list 方法。詳情請參閱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>'