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

تتيح لك طريقة accounts.list استرداد قائمة بموارد Account التي يمكن للمستخدم الذي تمت مصادقته الوصول إليها. يمكنك استخدام مَعلمة طلب البحث filter لتضييق نطاق النتائج استنادًا إلى معايير مختلفة، مثل ما يلي:

  • خصائص الحساب
  • العلاقات مع الحسابات الأخرى (مثل مقدّمي الخدمات في بنية حساب بامتيازات متقدّمة)
  • الخدمات المرتبطة بالحسابات

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

يمكنك استخدام الحقول التالية للفلترة على مستوى account:

  • ‫access: تتم الفلترة حسب نوع إذن الوصول الذي يملكه المستخدم إلى account. يقبل هذا الفلتر القيم التالية:
    • ‫DIRECT: تعرض هذه المَعلمة الحسابات التي يمكن للمستخدم الوصول إليها مباشرةً فقط. هذه هي الحسابات التي تمت إضافة المستخدم إليها مباشرةً.
    • ‫INDIRECT: تعرض هذه القيمة الحسابات التي يمكن للمستخدم الوصول إليها بشكل غير مباشر فقط. هذه هي الحسابات التي يمكن للمستخدم الوصول إليها بدون أن يكون مستخدمًا فعليًا في الحساب. على سبيل المثال، سيحصل مستخدم حساب متعدّد العملاء على إذن وصول "غير مباشر" إلى حساب فرعي تابع للحساب المتعدّد العملاء. وبالمثل، يحصل مستخدمو خدمة CSS على إذن وصول غير مباشر إلى الحسابات التي تعمل مع الخدمة.
    • 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.

جافا

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'
السابق
Control access to your account
التالي
Filter syntax