Kontobeziehungen verwalten

Mit der Accounts API können Sie die Beziehungen zwischen Ihrem Merchant Center-Konto und anderen Dienstanbietern 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. Produktmanagement oder Kampagnenmanagement. Wenn Sie beispielsweise Ihr Merchant Center-Konto mit einem Google Ads-Konto verknüpfen, können Sie Ihre Produktdaten im Google Ads-Konto für Werbekampagnen verwenden.

Eine Beziehung besteht aus den folgenden Attributen:

• Das Merchant Center-Konto, für das der Dienst bereitgestellt wird
• Der Dienstanbieter
• Der Dienst oder die Dienste, die für das Merchant Center-Konto bereitgestellt werden

Alias

Dienstanbieter können einem Konto, das sie verwalten, einen Alias zuweisen. Das entspricht dem Feld seller_id, das in der Ressource account in der Content API for Shopping vorhanden war. Der Alias kann über das optionale 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 bei der Kontoerstellung hinzufügen.

• Kontoaggregation: Bei diesem Dienst wird ein erweitertes Konto mit einem anderen Konto verknüpft, wodurch das erweiterte Konto uneingeschränkten Zugriff erhält. Es wird in der Regel von Marktplätzen, Einzelhändlern mit mehreren Marken oder internationalen Einzelhändlern verwendet, die eine zentrale Kontrolle über untergeordnete Konten benötigen. Wenn Sie eine E-Commerce-Plattform oder ein Channel-Partner sind, empfehlen wir stattdessen die Verwendung von accountManagement. Wenn Sie ein Konto erstellen und dabei die Kontoaggregation verwenden, muss externalAccountId weggelassen werden.

• Kampagnenverwaltung: Dieser Dienst bildet die Verknüpfung zwischen einem Merchant Center-Konto und einem Google Ads-Konto ab. Das Google Ads-Konto erhält so Zugriff auf Produkt- und Kontodaten, die für die Ausfü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 produktspezifische Partnerfilter erstellen, wenn Sie Kampagnen für Commerce-Media-Netzwerke ausführen.
• Derzeit müssen Sie die Alpha-Version der Unter-API „Accounts“ verwenden.
• Für die Nutzung dieser Funktion ist eine spezielle Zulassung für das GMC erforderlich.

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

• Preisvergleich: Dies steht für die Beziehung zu einem Preisvergleichsportal, das das Merchant Center-Konto betreibt.

• Verwaltung lokaler Einträge: Dies bezieht sich auf die Beziehung zu einem Filialleiter für die Verwaltung des lokalen Inventars und der Einträge über ein Unternehmensprofil bei Google.

• Kontoverwaltung: Mit diesem Dienst kann der Anbieter administrative Aktionen im Merchant Center-Konto ausführen, z. B. Kontoeinstellungen konfigurieren, Nutzer verwalten oder Informationen zum Unternehmen aktualisieren. Das Unternehmen kann den gewährten Zugriff auch einschränken. Wenn dieser Dienst bei der Kontoerstellung verwendet wird, wird ein Konto erstellt, das mit dem Anbieter verknüpft ist. Dies ist der empfohlene Ansatz für E-Commerce-Plattformen und Channel-Partner. Es kann auch einem bestehenden Konto vorgeschlagen werden.

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

Handschlag

Um einen Dienst einzurichten, 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 einen Dienstlink vor.
2. Die andere Partei genehmigt oder lehnt den Vorschlag 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 nun qualifizierten Nutzern gewährt (siehe Zugriffsrechte unten).

Der Nutzer, der einen Vorschlag erstellt, ablehnt oder genehmigt, muss ADMIN-Zugriffsrechte für das Konto haben, mit dem der Prozess initiiert wird. 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 empfangenden Konto sein.

Die folgenden Beispiele zeigen, wie Sie einen Kontoservice 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 finden Sie eine Beschreibung der spezifischen Handshake-Anforderungen für die einzelnen Dienste:

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

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

• Kampagnenverwaltung: Hier wird zwar der normale Handshake-Prozess durchlaufen, Vorschläge werden aber in einem System (z. B. Google Ads) erstellt und Genehmigungen 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 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 bei Verwendung von propose. 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).

Zugriffsrechte

Jeder Diensttyp bietet einen bestimmten Zugriff für Nutzer des Dienstanbieters auf das Konto, das gewartet wird:

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

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

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

• Verwaltung lokaler Einträge: Für diesen Dienst gibt es kein direktes Zugriffsrecht. Stattdessen wird die Synchronisierung der Produkte des Eintrags mit dem Merchant Center-Konto ermöglicht.

Wichtig: Die für die folgenden Diensttypen beschriebenen Zugriffsrechte gelten nur für genehmigte Dienstanbieter. Wenn Sie ein Dienstanbieter sind und diese Funktion nutzen möchten, wenden Sie sich an unser Supportteam. Wenn Sie bereits zuvor für die accounts.link-Methode zur Produktverwaltung in der Content API for Shopping genehmigt wurden, 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-Berechtigungen. Hinweis: In Zukunft wird dies auf produktbezogene Zugriffsrechte beschränkt sein.

Beziehungen für Drittanbieterplattformen

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

1. Dienstanbieter: Ihr erweitertes Konto.
2. Konto, das den Dienst erhält: Ein Merchant Center-Konto, das das von Ihnen verwaltete Unternehmen repräsentiert.
3. Dienst:
   • accountManagement: Dies ist der empfohlene Dienst für E-Commerce-Plattformen und Channel-Partner, die neue Konten im Namen von Händlern erstellen. Es wird ein Konto erstellt, das dem Händler gehört und mit Ihnen für die Verwaltung verknüpft ist. Dies entspricht der bevorzugten Merchant Center-Struktur für diesen Anwendungsfall.
   • accountAggregation: Mit diesem Dienst wird Ihr erweitertes Konto mit einem anderen Konto verknüpft. Es wird zwar unterstützt, ist aber nicht für E-Commerce-Plattformen und Channelpartner zu empfehlen.

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