Zarządzanie relacjami między kontami

Za pomocą interfejsu Accounts API możesz zarządzać relacjami między kontem Merchant Center a innymi dostawcami usług. Relacja to formalne połączenie, które umożliwia dostawcy oferowanie konkretnych usług Twojej firmie. Usługa określa uprawnienia i możliwości przyznane dostawcy, takie jak zarządzanie produktami lub kampaniami. Na przykład połączenie konta Merchant Center z kontem Google Ads umożliwia kontu Google Ads korzystanie z danych o produktach do prowadzenia kampanii reklamowych.

Relacja składa się z tych atrybutów:

• konto Merchant Center, które korzysta z usługi;
• Dostawca usług
• Usługa lub zestaw usług świadczonych na rzecz konta Merchant Center

Alias

Dostawcy usług mogą powiązać alias z kontami, które obsługują (jest to odpowiednik pola seller_id, które było obecne w zasobie account w Content API for Shopping). Alias można przypisać za pomocą opcjonalnego pola account_id_alias w zasobie AccountRelationship. Służy on jako identyfikator niestandardowy. Alias musi składać się z 1–50 znaków, którymi mogą być litery ASCII, cyfry, łączniki, podkreślenia, kropki lub tyldy ([A-Za-z0-9_~.-]{1,50}).

Struktura adresu URL umożliwiającego dostęp do konta za pomocą aliasu to GET /accounts/v1/accounts/{provider}~{account_id_alias}.

Usługi

W interfejsie Accounts API konta mogą otrzymywać te usługi. Wiele z tych usług możesz dodać podczas tworzenia konta.

• Agregacja kont: ta usługa (accountAggregation) łączy multikonto klientów (konto zaawansowane) z subkontem, co zapewnia kontu zaawansowanemu pełny, nieograniczony dostęp i sprawia, że subkonto jest widoczne w interfejsie Merchant Center. Interfejs Merchant Center automatycznie przekształca konta w konta zaawansowane z accountAggregation dla kreatorów sklepów (platform e-commerce), partnerów kanału, platform handlowych, sprzedawców wielu marek i sprzedawców międzynarodowych podczas tworzenia nowych subkont. Jeśli reprezentujesz agencję, użyj accountManagement. Gdy tworzysz konto za pomocą agregacji kont, musisz pominąć element externalAccountId.

• Zarządzanie kampaniami: ta usługa modeluje połączenie między kontem Merchant Center a kontem Google Ads, dając kontu Google Ads dostęp do danych o produktach i danych na koncie, które są potrzebne do prowadzenia kampanii reklamowych. W tym przypadku dostawcą usług jest GOOGLE_ADS, a externalAccountId to identyfikator konta Google Ads. Tę usługę można też zaproponować istniejącemu kontu.

Uwaga: w przypadku sprzedawców i platform handlowych korzystających z sieci mediów komercyjnych na kontach Google Ads:

• Ta usługa umożliwia tworzenie filtrów produktów dla konkretnych partnerów podczas prowadzenia kampanii w sieciach mediów komercyjnych.
• Obecnie musisz używać wersji alfa podrzędnego interfejsu API Accounts.
• Korzystanie z tej funkcji wymaga umieszczenia na liście dozwolonych w GMC.

Aby uzyskać więcej informacji, skontaktuj się z zespołem zarządzającym kontem Google Ads.

• Porównywanie cen: reprezentuje relację z usługą porównywania cen, która zarządza kontem Merchant Center.

• Zarządzanie wizytówkami lokalnymi: dotyczy relacji z kierownikiem sklepu w zakresie zarządzania lokalnym asortymentem i wizytówkami za pomocą Profilu Firmy w Google.

• Zarządzanie kontem: ta usługa (accountManagement) umożliwia dostawcy wykonywanie działań administracyjnych na samodzielnym zewnętrznym koncie Merchant Center, takich jak konfigurowanie ustawień konta, zarządzanie użytkownikami czy aktualizowanie informacji o firmie. Firma może też ograniczyć przyznany dostęp. Jeśli użyjesz tej usługi podczas tworzenia konta, utworzy ona samodzielne konto połączone z dostawcą. Można ją też zaproponować na istniejącym koncie. Agencje, które korzystają z tego typu usługi, mogą wyświetlać konta, którymi zarządzają, w Merchant Center dla agencji. Kreatory sklepów i partnerzy kanału mogą używać interfejsu Merchant API do pobierania informacji o sprzedawcach, którymi zarządzają za pomocą accountManagement.

• Zarządzanie produktami: ta usługa umożliwia dostawcom zarządzanie produktami i powiązanymi funkcjami, takimi jak źródła danych i reguły. Jeśli dodajesz go podczas tworzenia konta, zwykle jest on połączony z accountManagement lub accountAggregation. Tę usługę można też zaproponować istniejącemu kontu.

• Zarządzanie procesem płatności UCP (v1alpha, ograniczony dostęp): usługa ucpCheckoutManagement umożliwia zatwierdzonemu dostawcy usług zarządzanie integracjami procesu płatności UCP, ustawieniami i udziałem w programie w imieniu sprzedawcy. Tę usługę można zaproponować lub zatwierdzić tylko na istniejącym koncie Merchant Center.

  Uwaga: proces płatności na platformie UCP to funkcja w wersji alfa z ograniczonym dostępem. Więcej informacji o dostawcach usług i płatnościach w ramach UCP znajdziesz w artykule Merchant Center dla dostawców usług.

Uścisk dłoni

Aby utworzyć usługę, zarówno konto, które ją udostępnia, jak i konto, które ją otrzymuje, muszą autoryzować połączenie. Ten proces autoryzacji nazywa się uzgadnianiem.

Uzgodnienie połączenia to proces dwuetapowy:

1. Jedna ze stron proponuje połączenie usługi.
2. Druga strona zatwierdza lub odrzuca ofertę pakietową.

Po zaakceptowaniu propozycji usługa jest zatwierdzana i uznawana za w pełni skonfigurowaną. Wszelkie prawa dostępu przyznane dostawcy usług są teraz przyznawane kwalifikującym się użytkownikom (patrz prawa dostępu poniżej).

Ważne: po wywołaniu accounts.services.approve uprawnienia dostępu między kontami mogą być rozpowszechniane przez maksymalnie 60 sekund. Jeśli kolejne żądania do interfejsu Merchant API wysyłane do połączonego konta zwracają błąd 401 UNAUTHENTICATED, spróbuj ponownie, stosując wzrastający czas do ponowienia.

Pamiętaj, że użytkownik, który tworzy, odrzuca lub zatwierdza ofertę pakietową, musi mieć uprawnienia dostępu ADMIN do konta, które inicjuje proces. Jeśli więc usługodawca proponuje usługę, użytkownik, który składa propozycję, musi być ADMIN na koncie usługodawcy, a użytkownik, który akceptuje lub odrzuca propozycję, musi być ADMIN na koncie odbiorcy.

Poniższe przykłady pokazują, jak zaproponować usługę konta:

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

Działanie uzgadniania połączenia w poszczególnych usługach

Poniżej znajdziesz opis wymagań dotyczących uzgadniania połączenia w przypadku poszczególnych usług:

• Agregacja kont: tę usługę można skonfigurować tylko podczas tworzenia konta. Dostawca usług powinien mieć konto zaawansowane, a usługa jest automatycznie zatwierdzana, ponieważ użytkownicy konta zaawansowanego mają pełny dostęp do tworzonego konta ADMIN.

• Porównywarka cen: ta usługa jest automatycznie zatwierdzana, gdy zostanie dodana podczas tworzenia konta za pomocą createAndConfigure.

• Zarządzanie kampaniami: chociaż proces ten przebiega w normalny sposób, oferty są tworzone w jednym systemie (np. Google Ads), a zatwierdzane w innym (np. w Merchant Center lub za pomocą interfejsu Merchant API).

• Zarządzanie wizytówkami lokalnymi: w przypadku tej usługi uzgadnianie połączenia jest proponowane w ramach specjalnej metody, a zatwierdzenia są dokonywane w innym systemie (np. w Profilu Firmy w Google). Szczegółowe instrukcje znajdziesz w przewodniku po łączeniu Profilu Firmy w Google.

• Zarządzanie kontem: w przypadku tej usługi podczas korzystania z propose obowiązuje standardowy proces uzgadniania. Jeśli usługa zostanie dodana podczas tworzenia konta za pomocą createAndConfigure, zostanie automatycznie zatwierdzona.

• Zarządzanie usługami: w przypadku tej usługi obowiązuje standardowy proces uzgadniania (proponowany przez jedną stronę, a następnie akceptowany przez drugą).

• Zarządzanie procesem płatności na platformie UCP (v1alpha, ograniczony dostęp): w przypadku tej usługi sprzedawca może dokończyć uzgadnianie połączenia za pomocą hostowanego przez Google okna łączenia kont w portalu dostawcy usługi lub za pomocą standardowego procesu uzgadniania połączenia (propose, a następnie approve). Szczegółowe informacje o integracji znajdziesz w dokumentacji dostawców usług Merchant Center.

Prawa dostępu

Każdy typ usługi zapewnia użytkownikom dostawcy usług określony poziom dostępu do konta, na którym jest świadczona usługa:

• Agregacja kont: ta usługa zapewnia pełne uprawnienia ADMIN.

• Zarządzanie kampanią: ta usługa zapewnia prawo z ograniczonym dostępem, umożliwiając powiązanemu kontu reklamowemu dostęp do produktów i podstawowych informacji o koncie.

• Porównywanie cen: ta usługa domyślnie zapewnia pełne uprawnienia ADMIN. Firma może jednak ograniczyć dostęp przyznany w Merchant Center.

• Zarządzanie wizytówkami lokalnymi: ta usługa nie zapewnia bezpośredniego prawa dostępu. Zamiast tego umożliwia synchronizację produktów z kontem Merchant Center.

Ważne: uprawnienia dostępu opisane w przypadku tych typów usług dotyczą tylko zatwierdzonych dostawców usług. Jeśli jesteś dostawcą usług i chcesz skorzystać z tej funkcji, skontaktuj się z naszym zespołem pomocy. Jeśli masz już zatwierdzoną metodę accounts.link do zarządzania produktami w Content API for Shopping, możesz korzystać z tej usługi w Merchant API bez konieczności uzyskiwania dodatkowych zatwierdzeń.

• Zarządzanie kontem: ta usługa domyślnie zapewnia pełne uprawnienia ADMIN.

• Zarządzanie produktami: ta usługa zapewnia pełne uprawnienia ADMIN. Pamiętaj, że w przyszłości będzie to ograniczone tylko do uprawnień dostępu związanych z produktem.

• Zarządzanie płatnościami UCP (v1alpha, ograniczony dostęp): ta usługa zapewnia pełne uprawnienia ADMIN. Pamiętaj, że w przyszłości będzie to ograniczone tylko do praw dostępu związanych z płatnościami UCP.

Jak relacje są stosowane na platformach innych firm

Jeśli reprezentujesz platformę zewnętrzną, która zarządza kontami w imieniu innych firm, poniżej znajdziesz informacje o tym, jak różne pojęcia są mapowane na strukturę konta:

1. Dostawca usługi: Twoje konto zaawansowane.
2. Konto, które korzysta z usługi: konto Merchant Center, które reprezentuje firmę, którą zarządzasz.
3. Usługa:
   • accountAggregation: używany przez kreatory sklepów (platformy e-commerce), partnerów kanału, platformy handlowe i sprzedawców wielu marek, którzy tworzą nowe subkonta w imieniu sprzedawców. Interfejs Merchant Center automatycznie konfiguruje kreatory sklepów i partnerów kanału jako konta zaawansowane z accountAggregation, umożliwiając im wyświetlanie subkont i zarządzanie nimi w interfejsie Merchant Center.
   • accountManagement: używane przez agencje, które tworzą samodzielne konta klientów należące do sprzedawcy lub łączą się z nimi. Mogą je wyświetlać w Merchant Center dla agencji. Inne typy dostawców usług używają metody accounts.list w interfejsie Merchant API, aby wyświetlać informacje o połączonym koncie.

Szczegółowe informacje o konfigurowaniu konta zaawansowanego i łączeniu go z nowymi kontami Merchant Center znajdziesz w artykule Tworzenie kont.