Kontobeziehungen verwalten

Mit der Accounts API können Sie die Beziehungen zwischen Ihrem Merchant Center-Konto und anderen Dienstleistern verwalten. Eine Beziehung ist eine formelle Verbindung, die es einem Anbieter ermöglicht, Ihrem Unternehmen bestimmte Dienste anzubieten. Ein Dienst definiert die Berechtigungen und Funktionen, die dem Anbieter gewährt werden, z. B. Produktverwaltung oder Kampagnenverwaltung. Wenn Sie beispielsweise Ihr Merchant Center-Konto mit einem Google Ads-Konto verknüpfen, können Ihre Produktdaten im Google Ads-Konto für Werbekampagnen verwendet werden.

Eine Beziehung besteht aus den folgenden Attributen:

• Das Merchant Center-Konto, das den Dienst erhält
• Der Dienstleister
• Der Dienst oder die Dienste, die für das Merchant Center-Konto bereitgestellt werden

Alias

Dienstleister können Konten, die sie betreuen, einen Alias zuweisen. Dies entspricht dem Feld seller_id, das in der Ressource account in der Content API for Shopping vorhanden war. Der Alias kann mit dem optionalen Feld account_id_alias in der Ressource AccountRelationship zugewiesen werden und dient als benutzerdefinierte Kennung. Der Alias muss aus 1 bis 50 Zeichen bestehen, die aus ASCII-Buchstaben, Dezimalziffern, Bindestrichen, Unterstrichen, Punkten oder Tilden ([A-Za-z0-9_~.-]{1,50}) ausgewählt werden.

Die URL-Struktur für den Zugriff auf ein Konto über seinen Alias lautet GET /accounts/v1/accounts/{provider}~{account_id_alias}.

Dienste

In der Accounts API können Konten die folgenden Dienste erhalten. Viele dieser Dienste können Sie während der Kontoerstellung hinzufügen.

• Kontozusammenführung: Dieser Dienst (accountAggregation) verknüpft ein erweitertes Mehrfachkundenkonto mit einem Unterkonto. Dadurch erhält das erweiterte Konto uneingeschränkten Zugriff und das Unterkonto wird in der Merchant Center-Benutzeroberfläche sichtbar. In der Merchant Center-Benutzeroberfläche werden Konten automatisch in erweiterte Konten mit accountAggregation für Shop-Builder (E-Commerce-Plattformen), Channelpartner, Marktplätze, Mehrmarkenhändler und internationale Einzelhändler umgewandelt, wenn neue Unterkonten erstellt werden. Wenn Sie eine Agentur sind, verwenden Sie stattdessen accountManagement. Wenn Sie ein Konto mit Kontoaggregation erstellen, muss die externalAccountId weggelassen werden.

• Kampagnenverwaltung: Dieser Dienst modelliert die Verknüpfung zwischen einem Merchant Center-Konto und einem Google Ads-Konto. Dadurch erhält das Google Ads-Konto Zugriff auf Produkt- und Kontodaten, die für die Durchführung von Werbekampagnen erforderlich sind. Der Dienstanbieter ist in diesem Fall GOOGLE_ADS und externalAccountId ist die ID des Google Ads-Kontos. Dieser Dienst kann auch für ein bestehendes Konto vorgeschlagen werden.

Hinweis: Für Einzelhändler/Marktplätze, die das Commerce Media Network über Google Ads-Konten verwenden:

• Mit diesem Dienst können Sie partnerspezifische Produktfilter für Commerce-Media-Netzwerk-Kampagnen erstellen.
• Derzeit müssen Sie die Alpha-Version der Accounts Sub-API verwenden.
• Für die Nutzung dieser Funktion ist ein spezieller GMC-Eintrag auf der Zulassungsliste erforderlich.

Weitere Informationen erhalten Sie von Ihrem Google Ads-Account-Management-Team.

• Preisvergleich: Dies stellt die Beziehung zu einem Preisvergleichsportal (Comparison Shopping Service, CSS) dar, das das Merchant Center-Konto betreibt.

• Verwaltung lokaler Einträge: Dies ist die Beziehung zu einem Filialleiter, der das lokale Inventar und die Einträge über ein Google Unternehmensprofil verwaltet.

• Kontoverwaltung: Mit diesem Dienst (accountManagement) kann der Anbieter administrative Aktionen für ein eigenständiges externes Merchant Center-Konto ausführen, z. B. Kontoeinstellungen konfigurieren, Nutzer verwalten oder Unternehmensinformationen aktualisieren. Das Unternehmen kann den gewährten Zugriff auch einschränken. Wenn dieser Dienst bei der Kontoerstellung verwendet wird, wird ein eigenständiges Konto erstellt, das mit dem Anbieter verknüpft ist. Sie kann auch für ein bestehendes Konto vorgeschlagen werden. Agenturen, die diesen Diensttyp verwenden, können die von ihnen verwalteten Konten im Merchant Center für Agenturen sehen. Shop-Builder und Channelpartner können die Merchant API verwenden, um Informationen zu Händlern abzurufen, die sie über accountManagement verwalten.

• Produktverwaltung: Mit diesem Dienst können Anbieter Produkte und zugehörige Funktionen wie Datenquellen und Regeln verwalten. Wenn sie bei der Kontoerstellung hinzugefügt wird, geschieht dies in der Regel in Kombination mit accountManagement oder accountAggregation. Dieser Dienst kann auch für ein bestehendes Konto vorgeschlagen werden.

• UCP-Direktkaufverwaltung (v1alpha, eingeschränkter Zugriff): Mit dem Dienst ucpCheckoutManagement kann ein genehmigter Dienstleister im Namen eines Händlers UCP-Direktkaufintegrationen, ‑Einstellungen und die Programmteilnahme verwalten. Dieser Dienst kann nur einem bestehenden Merchant Center-Konto vorgeschlagen oder von diesem genehmigt werden.

  Hinweis: Der Direktkauf über die UCP ist eine Alpha-Funktion mit eingeschränktem Zugriff. Weitere Informationen zu Dienstleistern und zum UCP-Direktkauf im Merchant Center für Dienstleister.

Handschlag

Zum Einrichten eines Dienstes müssen sowohl das Konto, das den Dienst bereitstellt, als auch das Konto, das den Dienst empfängt, die Verbindung autorisieren. Dieser Autorisierungsprozess wird als Handshake bezeichnet.

Der Handshake ist ein zweistufiger Prozess:

1. Eine Partei schlägt eine Dienstverknüpfung vor.
2. Die andere Partei genehmigt den Vorschlag oder lehnt ihn ab.

Sobald ein Vorschlag angenommen wurde, ist der Dienst genehmigt und gilt als vollständig eingerichtet. Alle Zugriffsrechte, die dem Dienstanbieter gewährt wurden, werden jetzt qualifizierten Nutzern gewährt (siehe Zugriffsrechte unten).

Wichtig: Es kann bis zu 60 Sekunden dauern, bis die kontoübergreifenden Zugriffsrechte nach dem Aufruf von accounts.services.approve übernommen werden. Wenn nachfolgende Merchant API-Anfragen an das verknüpfte Konto 401 UNAUTHENTICATED zurückgeben, versuchen Sie es mit exponentiellem Backoff noch einmal.

Der Nutzer, der ein Angebot erstellt, ablehnt oder genehmigt, muss ADMIN-Zugriffsrechte für das Konto haben, das den Prozess initiiert. Wenn der Dienstanbieter also einen Dienst vorschlägt, muss der Nutzer, der den Vorschlag macht, ein ADMIN im Konto des Dienstanbieters sein. Der Nutzer, der den Vorschlag annimmt oder ablehnt, muss ein ADMIN im Empfängerkonto sein.

Die folgenden Beispiele zeigen, wie Sie einen Kontodienst vorschlagen:

Java

import com.google.api.gax.core.FixedCredentialsProvider;
import com.google.auth.oauth2.GoogleCredentials;
import com.google.shopping.merchant.accounts.v1.AccountName;
import com.google.shopping.merchant.accounts.v1.AccountService;
import com.google.shopping.merchant.accounts.v1.AccountServicesServiceClient;
import com.google.shopping.merchant.accounts.v1.AccountServicesServiceSettings;
import com.google.shopping.merchant.accounts.v1.ProductsManagement;
import com.google.shopping.merchant.accounts.v1.ProposeAccountServiceRequest;
import shopping.merchant.samples.utils.Authenticator;

/** This class demonstrates how to propose a service to an existing Merchant Center account. */
public class ProposeServiceSample {

  public static void proposeService(long accountId, long providerId, String externalAccountId)
      throws Exception {

    // Obtains OAuth token based on the user's configuration.
    // The user that authenticates should have access to the account.
    GoogleCredentials credential = new Authenticator().authenticate();

    // Creates service settings using the credentials retrieved above.
    AccountServicesServiceSettings accountServicesServiceSettings =
        AccountServicesServiceSettings.newBuilder()
            .setCredentialsProvider(FixedCredentialsProvider.create(credential))
            .build();

    // Calls the API and catches and prints any network failures/errors.
    try (AccountServicesServiceClient accountServicesServiceClient =
        AccountServicesServiceClient.create(accountServicesServiceSettings)) {

      // The service to be proposed.
      // This sample shows how to propose product management.
      // For more information about the different services, see:
      // https://developers.google.com/merchant/api/guides/accounts/services
      AccountService accountService =
          AccountService.newBuilder()
              .setProductsManagement(ProductsManagement.newBuilder().build())
              .setExternalAccountId(externalAccountId)
              .build();

      String accountName =
          AccountName.newBuilder().setAccount(String.valueOf(accountId)).build().toString();

      ProposeAccountServiceRequest request =
          ProposeAccountServiceRequest.newBuilder()
              .setParent(accountName)
              .setProvider("accounts/" + providerId)
              .setAccountService(accountService)
              .build();

      System.out.println("Sending Propose Service request:");
      AccountService response = accountServicesServiceClient.proposeAccountService(request);

      System.out.println("Proposed Service below");
      System.out.println(response);
    } catch (Exception e) {
      System.out.println(e);
    }
  }

  public static void main(String[] args) throws Exception {
    // The ID of the account to propose the service to.
    long accountId = 123L;
    // This is the provider ID of the e-commerce platform.
    long providerId = 456L;
    // An external ID that uniquely identifies the account service.
    String externalAccountId = "ext-acc-id-123";
    proposeService(accountId, providerId, externalAccountId);
  }
}
ProposeServiceSample.java

PHP

require_once __DIR__ . '/../../../../vendor/autoload.php';
require_once __DIR__ . '/../../../Authentication/Authentication.php';
require_once __DIR__ . '/../../../Authentication/Config.php';

use Google\ApiCore\ApiException;
use Google\Shopping\Merchant\Accounts\V1\AccountAggregation;
use Google\Shopping\Merchant\Accounts\V1\AccountService;
use Google\Shopping\Merchant\Accounts\V1\Client\AccountServicesServiceClient;
use Google\Shopping\Merchant\Accounts\V1\ProposeAccountServiceRequest;

/**
 * This class demonstrates how to propose an account service.
 */
class ProposeAccountServiceSample
{
    /**
     * A helper function to create the account name string.
     *
     * @param string $accountId The ID of the account.
     *
     * @return string The account name has the format: `accounts/{account_id}`
     */
    private static function toAccountName(string $accountId): string
    {
        return sprintf('accounts/%s', $accountId);
    }

    /**
     * Proposes a new account service.
     *
     * @param array $config The configuration data used for authentication and
     *     getting the account ID.
     * @param string $providerId The ID of the provider account.
     */
    public static function proposeAccountService(
        array $config,
        string $providerId
    ): void {
        // Gets the OAuth credentials to make the request.
        $credentials = Authentication::useServiceAccountOrTokenFile();

        // Creates options containing credentials for the client to use.
        $options = ['credentials' => $credentials];

        // Creates a client.
        $accountServicesServiceClient = new AccountServicesServiceClient($options);

        // Calls the API and catches and prints any network failures/errors.
        try {
            $accountAggregation = new AccountAggregation();
            $accountService = (new AccountService())
                ->setAccountAggregation($accountAggregation);

            $request = (new ProposeAccountServiceRequest())
                ->setParent(self::toAccountName($config['accountId']))
                ->setProvider(self::toAccountName($providerId))
                ->setAccountService($accountService);

            print "Sending Propose AccountService request\n";
            $response = $accountServicesServiceClient->proposeAccountService($request);
            print "Proposed AccountService below\n";
            print $response->serializeToJsonString(true) . PHP_EOL;
        } catch (ApiException $e) {
            printf("An error has occurred: %s%s", $e->getMessage(), PHP_EOL);
        }
    }

    /**
     * Helper to execute the sample.
     */
    public function callSample(): void
    {
        $config = Config::generateConfig();

        // Update this with the Merchant Center provider ID you want to get the
        // relationship for.
        $providerId = 111;
        self::proposeAccountService($config, $providerId);
    }
}

// Run the script
$sample = new ProposeAccountServiceSample();
$sample->callSample();
ProposeAccountServiceSample.php

Python

"""This class demonstrates how to propose an account service."""

from examples.authentication import configuration
from examples.authentication import generate_user_credentials
from google.shopping.merchant_accounts_v1 import AccountAggregation
from google.shopping.merchant_accounts_v1 import AccountService
from google.shopping.merchant_accounts_v1 import AccountServicesServiceClient
from google.shopping.merchant_accounts_v1 import ProposeAccountServiceRequest

_ACCOUNT = configuration.Configuration().read_merchant_info()
_PARENT = f"accounts/{_ACCOUNT}"


def propose_account_service(provider_id: int) -> None:
  """Proposes an account service.

  Args:
    provider_id: The Merchant Center ID of the provider.
  """
  # Gets OAuth Credentials.
  credentials = generate_user_credentials.main()

  # Creates a client.
  client = AccountServicesServiceClient(credentials=credentials)

  # Creates the provider resource name from the provider ID.
  provider = f"accounts/{provider_id}"

  # Creates an AccountService object.
  # For this request, only `account_aggregation` is needed.
  account_service = AccountService()
  account_service.account_aggregation = AccountAggregation()

  # Creates the request.
  request = ProposeAccountServiceRequest(
      parent=_PARENT,
      provider=provider,
      account_service=account_service,
  )

  # Makes the request and catches and prints any error messages.
  try:
    print("Sending Propose AccountService request")
    response = client.propose_account_service(request=request)
    print("Proposed AccountService below")
    print(response)
  except RuntimeError as e:
    print(e)


if __name__ == "__main__":
  # Update this with the Merchant Center provider ID you want to get the
  # relationship for.
  provider_id_ = 111
  propose_account_service(provider_id_)
propose_account_service_sample.py

Dienstspezifisches Handshake-Verhalten

Im Folgenden werden die spezifischen Handshake-Anforderungen für die einzelnen Dienste beschrieben:

• Kontoaggregation: Dieser Dienst kann nur im Rahmen der Kontoerstellung eingerichtet werden. Der Dienstleister muss ein erweitertes Konto haben. Der Dienst wird automatisch genehmigt, da Nutzer des erweiterten Kontos vollen ADMIN-Zugriff auf das erstellte Konto haben.

• Preisvergleichsportal: Dieser Dienst wird automatisch genehmigt, wenn er bei der Kontoerstellung mit createAndConfigure hinzugefügt wird.

• Kampagnenverwaltung: Hierbei wird der normale Handshake-Prozess befolgt. Angebote werden in einem System (z. B. Google Ads) erstellt und Genehmigungen werden im anderen System (z. B. im Merchant Center oder über die Merchant API) erteilt.

• Verwaltung lokaler Einträge: Für diesen Dienst wird der Handshake in einer speziellen Methode vorgeschlagen und die Genehmigungen erfolgen im anderen System (z. B. Google Unternehmensprofil). Eine detaillierte Anleitung finden Sie im Leitfaden zum Verknüpfen eines Google Unternehmensprofils.

• Kontoverwaltung: Für diesen Dienst gilt der reguläre Handshake-Prozess, wenn propose verwendet wird. Wenn der Dienst während der Kontoerstellung mit createAndConfigure hinzugefügt wird, wird er automatisch genehmigt.

• Produktverwaltung: Für diesen Dienst gilt der reguläre Handshake-Prozess (Vorschlag von einer Partei, gefolgt von der Annahme durch die andere).

• UCP-Kaufabwicklung (v1alpha, eingeschränkter Zugriff): Für diesen Dienst kann der Händler den Handshake über das von Google gehostete Dialogfeld zur Kontoverknüpfung im Portal des Dienstanbieters oder über den Standard-Handshake-Prozess (propose gefolgt von approve) abschließen. Weitere Informationen zur Integration finden Sie in der Dokumentation für Merchant Center-Dienstanbieter.

Zugriffsrechte

Jeder Diensttyp bietet Nutzern des Dienstleisters eine bestimmte Zugriffsebene für das Konto, für das der Dienst erbracht wird:

• Kontoaggregation: Dieser Dienst bietet vollständige ADMIN-Rechte.

• Kampagnenverwaltung: Dieser Dienst bietet ein eingeschränktes Zugriffsrecht, mit dem das verknüpfte Google Ads-Konto auf Produkte und grundlegende Kontoinformationen zugreifen kann.

• Preisvergleich: Dieser Dienst bietet standardmäßig volle ADMIN-Rechte. Das Unternehmen kann den im Merchant Center gewährten Zugriff jedoch einschränken.

• Verwaltung lokaler Einträge: Dieser Dienst bietet kein direktes Zugriffsrecht. Stattdessen wird dadurch ermöglicht, dass die Produkte des Eintrags mit dem Merchant Center-Konto synchronisiert werden.

Wichtig: Die für die folgenden Diensttypen beschriebenen Zugriffsrechte gelten nur für genehmigte Dienstleister. Wenn Sie ein Dienstleister sind und diese Funktion nutzen möchten, wenden Sie sich an unser Supportteam. Wenn Sie bereits die Genehmigung für die Methode accounts.link zur Produktverwaltung in der Content API for Shopping erhalten haben, können Sie diesen Dienst in der Merchant API ohne weitere Genehmigungen verwenden.

• Kontoverwaltung: Dieser Dienst bietet standardmäßig vollständige ADMIN-Rechte.

• Produktverwaltung: Dieser Dienst bietet vollständige ADMIN-Rechte. In Zukunft wird dies auf produktbezogene Zugriffsrechte beschränkt sein.

• UCP-Direktkaufverwaltung (v1alpha, eingeschränkter Zugriff): Dieser Dienst bietet vollständige ADMIN-Rechte. In Zukunft wird dies auf Zugriffsrechte im Zusammenhang mit der UCP-Kaufabwicklung beschränkt sein.

Beziehungen für Drittanbieterplattformen

Wenn Sie eine Drittanbieterplattform sind, die Konten im Namen anderer Unternehmen verwaltet, sehen Sie im Folgenden, wie die verschiedenen Konzepte Ihrer Kontostruktur zugeordnet werden:

1. Dienstleister: Ihr erweitertes Konto.
2. Konto, das den Dienst erhält: Ein Merchant Center-Konto, das das von Ihnen verwaltete Unternehmen repräsentiert.
3. Dienst:
   • accountAggregation: Wird von Store Buildern (E-Commerce-Plattformen), Channelpartnern, Marktplätzen und Mehrmarkenhändlern verwendet, die im Namen von Händlern neue Unterkonten erstellen. In der Merchant Center-Benutzeroberfläche werden Store Builder und Channelpartner automatisch als erweiterte Konten mit accountAggregation konfiguriert. So können sie Unterkonten in der Merchant Center-Benutzeroberfläche aufrufen und verwalten.
   • accountManagement: Wird von Agenturen verwendet, die eigenständige Kundenkonten des Händlers erstellen oder mit diesen verknüpfen. Diese Konten können sie im Merchant Center für Agenturen einsehen. Andere Arten von Dienstleistern verwenden die Methode accounts.list in der Merchant API, um Informationen zu verknüpften Konten aufzurufen.

Weitere Informationen zum Einrichten eines erweiterten Kontos und zum Verknüpfen mit neuen Merchant Center-Konten finden Sie unter Konten erstellen.