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

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

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

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

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

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

این کار به یافتن سریع حساب‌های کسب‌وکار خاص کمک می‌کند.

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'