Konten filtern, auf die Sie Zugriff haben

Die accounts.list Methode ermöglicht das Abrufen einer Liste von Account-Ressourcen, auf die der authentifizierte Nutzer zugreifen kann. Mit dem Abfrageparameter filter können Sie die Ergebnisse anhand verschiedener Kriterien eingrenzen, z. B.:

  • Kontoeigenschaften
  • Beziehungen zu anderen Konten (z. B. Anbietern in einer erweiterten Kontostruktur)
  • Mit den Konten verknüpfte Dienste

Dies kann hilfreich sein, wenn Sie mehrere Konten verwalten oder bestimmte Geschäftskonten finden möchten, die bestimmte Bedingungen erfüllen.

Mit den folgenden Feldern können Sie auf account-Ebene filtern:

  • capabilities: Filtert nach den capabilities der account-Ressource. Dieses Feld ist in der Ressource selbst nicht verfügbar. Nur die Funktion CAN_UPLOAD_PRODUCTS wird unterstützt. Dieses Feld unterstützt die Negation und verwendet die Sammlungssyntax.
  • relationship(...): Filtert nach der Art der Beziehung des Kontos zu einem anderen Konto. Sie können mehrere relationship(...)-Filter in eine Anfrage einfügen.
  • accountName: Filtert nach dem accountName der account-Ressource.

Weitere Informationen zur Filtersyntax finden Sie im Filter syntax Leitfaden.

Beispiele

In den folgenden Beispielen wird erläutert, wie Sie die typischsten Abfragen erstellen. In allen folgenden Beispielen wird die Methode accounts.list verwendet. Weitere Informationen finden Sie in der accounts.list Referenzdokumentation.

Unterkonten eines bestimmten Anbieters suchen

Mit der accounts.listSubaccounts Methode können Sie Unterkonten direkt auflisten. Sie können auch die Filterfunktionen verwenden, wie in den folgenden Abschnitten beschrieben. Wenn Sie ein erweitertes Konto verwalten, können Sie alle zugehörigen Unterkonten auflisten, indem Sie nach providerId filtern. Ersetzen Sie PROVIDER_ID durch die ID Ihres erweiterten Kontos.

Verwenden Sie beispielsweise relationship(providerId=123), wenn die ID des Anbieters 123 ist.

Dies ist nützlich, um die Struktur Ihrer Konten zu verwalten.

GET https://merchantapi.googleapis.com/accounts/v1/accounts?filter=relationship(providerId%20%3D%20PROVIDER_ID)

Bei einer erfolgreichen Anfrage wird der Statuscode 200 und ein Antworttext mit der Liste der übereinstimmenden Unterkonten zurückgegeben:

{
  "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..."
}

Konten suchen, in denen keine Produkte hochgeladen werden können

Sie können mehrere Filterbedingungen kombinieren, um genauere Suchanfragen zu erstellen.

Mit dem Filter accountName=*store* AND -capabilities:CAN_UPLOAD_PRODUCTS werden alle Konten mit „store“ im Namen gefunden, die nicht für das direkte Hochladen von Produkten konfiguriert sind. Das Zeichen - vor capabilities fungiert als Negationsoperator. Dies kann nützlich sein, um nur erweiterte Konten abzurufen.

GET https://merchantapi.googleapis.com/accounts/v1/accounts?filter=accountName%20%3D%20%22*store*%22%20AND%20-capabilities%3ACAN_UPLOAD_PRODUCTS

Bei einer erfolgreichen Anfrage wird der Statuscode 200 und ein Antworttext mit der Liste der übereinstimmenden Konten zurückgegeben:

{
  "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..."
}

Konten nach Namen suchen

Sie können nach Konten suchen, deren Anzeigename einem bestimmten Muster entspricht.

Mit accountName=*store* werden beispielsweise alle Konten mit „store“ im Namen gefunden.

So lassen sich bestimmte Geschäftskonten schnell finden.

GET https://merchantapi.googleapis.com/accounts/v1/accounts?filter=accountName%20%3D%20%22*store*%22

Bei einer erfolgreichen Anfrage wird der Statuscode 200 und ein Antworttext mit der Liste der übereinstimmenden Konten zurückgegeben:

{
  "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..."
}

Konten suchen, die für einen bestimmten Dienst mit einem Bereitsteller verknüpft sind

Sie können Konten suchen, die eine bestimmte Dienstbeziehung mit einem Anbieter haben. Wenn Sie beispielsweise alle Konten finden möchten, die unter dem Anbieter PROVIDER_ID für die Kontoaggregation zusammengefasst sind, verwenden Sie den Filter 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))

Bei einer erfolgreichen Anfrage wird der Statuscode 200 und ein Antworttext mit der Liste der übereinstimmenden Konten zurückgegeben:

{
  "accounts": [
    {
      "name": "accounts/54321",
      "accountId": "54321",
      "accountName": "Aggregated Account X",
      "adultContent": false,
      "languageCode": "en",
      "timeZone": {
        "id": "America/New_York"
      }
    }
  ]
}

Konten nach dem Genehmigungsstatus der Dienstbeziehung suchen

Sie können Konten nach dem Status ihrer Dienstbeziehung mit einem Anbieter filtern. So lassen sich beispielsweise alle Konten finden, die eine Verknüpfungsanfrage nicht akzeptiert haben (handshakeState = "PENDING") von einem bestimmten Anbieter PROVIDER_ID.

Wenn Sie beispielsweise Konten finden möchten, bei denen die Anbieter-ID 123 ist, der Diensttyp ACCOUNT_MANAGEMENT und der Status PENDING, verwenden Sie 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)

Bei einer erfolgreichen Anfrage wird der Statuscode 200 und ein Antworttext mit der Liste der übereinstimmenden Konten zurückgegeben:

{
  "accounts": [
    {
      "name": "accounts/98765",
      "accountId": "98765",
      "accountName": "Managed Account Y",
      "adultContent": false,
      "languageCode": "es",
      "timeZone": {
        "id": "Europe/Madrid"
      }
    }
  ]
}

Konten mit Clientbibliotheken filtern

In den folgenden Beispielen wird gezeigt, wie Sie mit Clientbibliotheken Konten anhand kombinierter Kriterien filtern, z. B. nach Kontoname und Beziehung zu einem Anbieter. In diesen Beispielen wird die Methode accounts.list verwendet. Weitere Informationen finden Sie in der Referenzdokumentation.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'