فلترة الحسابات التي يمكنك الوصول إليها

تتيح لك طريقة 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 بمعرّف حسابك بامتيازات متقدّمة.

على سبيل المثال، استخدِم relationship(providerId=123) إذا كان رقم تعريف مقدّم الخدمة هو 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* إلى العثور على جميع الحسابات التي تتضمّن كلمة "متجر" في اسمها.

يساعد ذلك في العثور بسرعة على حسابات أنشطة تجارية معيّنة.

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 المستندات المرجعية.

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