متد accounts.list به شما امکان میدهد لیستی از منابع Account که کاربر احراز هویت شده میتواند به آنها دسترسی داشته باشد را بازیابی کنید. میتوانید از پارامتر query filter برای محدود کردن نتایج بر اساس معیارهای مختلف، مانند موارد زیر، استفاده کنید:
- ویژگیهای حساب
- روابط با سایر حسابها (مانند ارائهدهندگان در یک ساختار حساب پیشرفته)
- سرویسهای مرتبط با حسابها
این میتواند برای مدیریت چندین حساب یا یافتن حسابهای تجاری خاص که شرایط خاصی را برآورده میکنند، مفید باشد.
برای فیلتر کردن در سطح account میتوانید از فیلدهای زیر استفاده کنید:
-
capabilities: بر اساسcapabilitiesمنبعaccountفیلتر میکند (توجه داشته باشید که این فیلد در خود منبع موجود نیست). فقط قابلیتCAN_UPLOAD_PRODUCTSپشتیبانی میشود. این فیلد از نفی پشتیبانی میکند و از سینتکس مجموعه استفاده میکند. -
relationship(...): فیلترها بر اساس نوع رابطهای که حساب با حساب دیگر دارد. میتوانید چندین فیلترrelationship(...)در یک درخواست بگنجانید. -
accountName: فیلترها بر اساسaccountNameمنبعaccount.
برای اطلاعات بیشتر در مورد سینتکس فیلتر، به راهنمای سینتکس فیلتر مراجعه کنید.
مثالها
مثالهای زیر نحوهی ایجاد رایجترین کوئریها را توضیح میدهند. تمام مثالهای زیر از متد accounts.list استفاده میکنند. برای اطلاعات بیشتر، به مستندات مرجع accounts.list مراجعه کنید.
یافتن حسابهای فرعی یک ارائهدهنده خاص
متد accounts.listSubaccounts روشی مستقیم برای فهرست کردن حسابهای فرعی ارائه میدهد. همچنین میتوانید از قابلیتهای فیلترینگ همانطور که در بخشهای بعدی توضیح داده شده است، استفاده کنید. اگر یک حساب پیشرفته را مدیریت میکنید، میتوانید تمام حسابهای فرعی آن را با فیلتر کردن بر اساس providerId فهرست کنید. به جای PROVIDER_ID ، شناسه حساب پیشرفته خود را قرار دهید.
برای مثال، اگر شناسه ارائهدهنده 123 است، از relationship(providerId=123) استفاده کنید.
این برای مدیریت ساختار حسابهای شما مفید است.
GET https://merchantapi.googleapis.com/accounts/v1/accounts?filter=relationship(providerId%20%3D%20PROVIDER_ID)
یک درخواست موفق، کد وضعیت ۲۰۰ و بدنه پاسخی حاوی فهرست زیرحسابهای منطبق را برمیگرداند:
{
"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 تمام حسابهایی که در نامشان "store" وجود دارد و برای آپلود مستقیم محصولات پیکربندی نشدهاند را پیدا میکند. علامت - قبل از capabilities به عنوان یک عملگر نفی عمل میکند. این میتواند برای بازیابی فقط حسابهای پیشرفته مفید باشد.
GET https://merchantapi.googleapis.com/accounts/v1/accounts?filter=accountName%20%3D%20%22*store*%22%20AND%20-capabilities%3ACAN_UPLOAD_PRODUCTS
یک درخواست موفق، کد وضعیت ۲۰۰ و بدنه پاسخی حاوی فهرست حسابهای منطبق را برمیگرداند:
{
"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
یک درخواست موفق، کد وضعیت ۲۰۰ و بدنه پاسخی حاوی فهرست حسابهای منطبق را برمیگرداند:
{
"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))
یک درخواست موفق، کد وضعیت ۲۰۰ و بدنه پاسخی حاوی فهرست حسابهای منطبق را برمیگرداند:
{
"accounts": [
{
"name": "accounts/54321",
"accountId": "54321",
"accountName": "Aggregated Account X",
"adultContent": false,
"languageCode": "en",
"timeZone": {
"id": "America/New_York"
}
}
]
}
یافتن حسابها بر اساس وضعیت تأیید رابطه خدماتی
شما میتوانید حسابها را بر اساس وضعیت ارتباط سرویس آنها با یک ارائهدهنده فیلتر کنید. به عنوان مثال، برای یافتن تمام حسابهایی که درخواست پیوند حساب (handshakeState = "PENDING") را از یک ارائهدهنده خاص PROVIDER_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)
یک درخواست موفق، کد وضعیت ۲۰۰ و بدنه پاسخی حاوی فهرست حسابهای منطبق را برمیگرداند:
{
"accounts": [
{
"name": "accounts/98765",
"accountId": "98765",
"accountName": "Managed Account Y",
"adultContent": false,
"languageCode": "es",
"timeZone": {
"id": "Europe/Madrid"
}
}
]
}
فیلتر کردن حسابها با استفاده از کتابخانههای کلاینت
مثالهای زیر نحوه استفاده از کتابخانههای کلاینت را برای فیلتر کردن حسابها بر اساس معیارهای ترکیبی، مانند نام حساب و ارتباط با یک ارائهدهنده، نشان میدهند. این مثالها از متد accounts.list استفاده میکنند. برای اطلاعات بیشتر، به مستندات مرجع accounts.list مراجعه کنید.
جاوا
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);
}
}
پی اچ پی
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();
پایتون
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()
برنامههااسکریپت
/**
* 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 --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>'