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

روش accounts.list به شما امکان می دهد فهرستی از منابع Account را که کاربر احراز هویت شده می تواند به آنها دسترسی داشته باشد بازیابی کنید. می‌توانید از پارامتر query 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)

یک درخواست موفقیت آمیز یک کد وضعیت 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 همه حساب های دارای "store" را به نام خود پیدا می کند که برای آپلود مستقیم محصولات پیکربندی نشده اند. 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"
      }
    }
  ]
}

حساب‌ها را بر اساس وضعیت تأیید رابطه خدمات پیدا کنید

می‌توانید حساب‌ها را بر اساس وضعیت رابطه خدماتشان با ارائه‌دهنده فیلتر کنید. به عنوان مثال، برای پیدا کردن همه حساب‌هایی که درخواست پیوند حساب (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)

یک درخواست موفق یک کد وضعیت 200 و یک بدنه پاسخگو با لیست حساب های منطبق را برمی گرداند:

{
  "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();

پایتون

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>'