סינון חשבונות שיש לכם גישה אליהם

ה-method‏ 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)

בקשה שמושלמת בהצלחה מחזירה קוד סטטוס 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.

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