حساب‌هایی را که می‌توانید به آن‌ها دسترسی داشته باشید فیلتر کنید

روش accounts.list به شما امکان می‌دهد فهرستی از منابع Account را که کاربر اصالت‌سنجی‌شده می‌تواند به آن‌ها دسترسی داشته باشد بازیابی کنید. می‌توانید از پارامتر پُرسمان filter برای محدود کردن نتایج براساس معیارهای مختلفی مانند موارد زیر استفاده کنید:

  • مشخصات حساب
  • رابطه با حساب‌های دیگر (مانند ارائه‌دهندگان در ساختار حساب پیشرفته)
  • سرویس‌های مرتبط با حساب‌ها

این کار می‌تواند برای مدیریت چندین حساب یا پیدا کردن حساب‌های کسب‌وکار خاصی که شرایط خاصی را برآورده می‌کنند مفید باشد.

می‌توانید از فیلدهای زیر برای فیلتر کردن در سطح account استفاده کنید:

  • access: براساس نوع دسترسی کاربر به account فیلتر می‌کند. این فیلتر مقادیر زیر را می‌پذیرد:
    • ‫DIRECT: فقط حساب‌هایی را برمی‌گرداند که کاربر دسترسی مستقیم به آن‌ها دارد. این‌ها حساب‌هایی هستند که کاربر مستقیماً به آن‌ها اضافه شده است.
    • ‫INDIRECT: فقط حساب‌هایی را برمی‌گرداند که کاربر دسترسی غیرمستقیم به آن‌ها دارد. این‌ها حساب‌هایی هستند که کاربر می‌تواند بدون اینکه واقعاً کاربر آن حساب باشد به آن‌ها دسترسی داشته باشد. برای نمونه، کاربر «حساب چندفروشنده‌ای» دسترسی «غیرمستقیم» به حساب فرعی «حساب چندفروشنده‌ای» خواهد داشت. به‌طور مشابه، کاربران CSS دسترسی غیرمستقیم به حساب‌هایی که با CSS کار می‌کنند خواهند داشت.
    • ALL: همه حساب‌هایی را که کاربر به آن‌ها دسترسی دارد (هم مستقیم و هم غیرمستقیم) برمی‌گرداند. اگر فیلتر مشخص نشده باشد، این رفتار پیش‌فرض است.
  • 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 همه حساب‌هایی را که «فروشگاه» در نامشان وجود دارد و برای بارگذاری مستقیم محصولات پیکربندی نشده‌اند پیدا می‌کند. - قبل‌از 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);
  }
}

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'