Gestire le relazioni tra gli account

Puoi utilizzare l'API Accounts per gestire le relazioni tra il tuo account Merchant Center e altri fornitori di servizi. Una relazione è una connessione formale che consente a un provider di offrire servizi specifici alla tua attività. Un servizio definisce le autorizzazioni e le funzionalità concesse al fornitore, ad esempio la gestione dei prodotti o delle campagne. Ad esempio, il collegamento dell'account Merchant Center a un account Google Ads consente a quest'ultimo di utilizzare i tuoi dati di prodotto per pubblicare campagne pubblicitarie.

Una relazione è composta dai seguenti attributi:

• L'account Merchant Center che riceve il servizio
• Il fornitore di servizi
• Il servizio o l'insieme di servizi forniti all'account Merchant Center

Alias

I fornitori di servizi possono associare un alias agli account che gestiscono (questo è l'equivalente del campo seller_id presente nella risorsa account dell'API Content per Shopping). L'alias può essere assegnato utilizzando il campo facoltativo account_id_alias all'interno della risorsa AccountRelationship e funge da identificatore personalizzato. L'alias deve essere composto da 1-50 caratteri scelti tra lettere ASCII, cifre decimali, trattini, trattini bassi, punti o tilde ([A-Za-z0-9_~.-]{1,50}).

La struttura dell'URL per accedere a un account utilizzando il relativo alias è GET /accounts/v1/accounts/{provider}~{account_id_alias}.

Servizi

Nell'API Accounts, gli account possono ricevere i seguenti servizi. Puoi aggiungere molti di questi servizi durante la creazione dell'account.

• Aggregazione degli account: questo servizio collega un account avanzato a un altro account, concedendo all'account avanzato l'accesso completo e senza restrizioni. Viene in genere utilizzato da marketplace, rivenditori multimarca o rivenditori internazionali che necessitano di un controllo centralizzato sugli account nidificati. Se sei una piattaforma di e-commerce o un partner di canale, ti consigliamo di utilizzare accountManagement. Quando crei un account utilizzando l'aggregazione degli account, il externalAccountId deve essere omesso.

• Gestione delle campagne: questo servizio modella il collegamento tra un account Merchant Center e un account Google Ads, consentendo all'account Google Ads di accedere ai dati dell'account e di prodotto necessari per pubblicare campagne pubblicitarie. Il fornitore di servizi in questo caso è GOOGLE_ADS e externalAccountId è l'ID dell'account Google Ads. Questo servizio può essere proposto anche a un account esistente.

Nota: per i rivenditori/ marketplace che utilizzano rete commerce media tramite gli account Google Ads:

• Questo servizio consente la creazione di filtri dei prodotti specifici per i partner quando vengono eseguite campagne della rete commerce media.
• Al momento, devi utilizzare la versione alpha della sub-API Accounts.
• L'utilizzo di questa funzionalità richiede l'inserimento in una lista consentita specifica di GMC.

Per ulteriori dettagli, contatta il team di gestione dell'account Google Ads.

• Shopping comparativo: rappresenta il rapporto con un Servizio di shopping comparativo (CSS) che gestisce l'account Merchant Center.

• Gestione delle schede locali: rappresenta il rapporto con un responsabile del negozio per la gestione dell'inventario e delle schede locali utilizzando un profilo dell'attività su Google.

• Gestione dell'account: questo servizio consente al fornitore di eseguire azioni amministrative sull'account Merchant Center, ad esempio configurare le impostazioni dell'account, gestire gli utenti o aggiornare le informazioni sull'attività. L'attività può anche limitare l'accesso concesso. Se utilizzato durante la creazione dell'account, questo servizio crea un account collegato al fornitore, che è l'approccio consigliato per le piattaforme di e-commerce e i partner di canale. Può anche essere proposto a un account esistente.

• Gestione dei prodotti: questo servizio consente ai provider di gestire i prodotti e le funzionalità correlate, come origini dati e regole. Se aggiunto durante la creazione dell'account, in genere viene utilizzato in combinazione con accountManagement o accountAggregation. Questo servizio può essere proposto anche a un account esistente.

Stretta di mano

Per stabilire un servizio, sia l'account che fornisce il servizio sia l'account che lo riceve devono autorizzare la connessione. Questo processo di autorizzazione è chiamato handshake.

L'handshake è un processo in due passaggi:

1. Una parte propone un link di servizio.
2. L'altra parte approva o rifiuta la proposta.

Una volta accettata una proposta, il servizio viene approvato e considerato completamente stabilito. Qualsiasi diritto di accesso conferito al fornitore di servizi viene ora concesso agli utenti qualificati (vedi diritti di accesso di seguito).

Tieni presente che l'utente che crea una proposta, la rifiuta o la approva deve disporre dei ADMIN diritti di accesso all'account che avvia la procedura. Pertanto, se il fornitore di servizi propone un servizio, l'utente che effettua la proposta deve essere un ADMIN sull'account del fornitore di servizi e l'utente che accetta o rifiuta la proposta deve essere un ADMIN sull'account ricevente.

Gli esempi seguenti mostrano come proporre un servizio dell'account:

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

Comportamento di handshake specifico per il servizio

Di seguito è riportata una descrizione dei requisiti di handshake specifici per ogni servizio individuale:

• Aggregazione degli account: questo servizio può essere stabilito solo nell'ambito della creazione dell'account. Il fornitore di servizi deve essere un account avanzato e il servizio viene approvato automaticamente poiché gli utenti dell'account avanzato hanno accesso completo ADMIN all'account in fase di creazione.

• Shopping comparativo: questo servizio viene approvato automaticamente quando viene aggiunto durante la creazione dell'account utilizzando createAndConfigure.

• Gestione delle campagne: sebbene segua la normale procedura di handshake, le proposte vengono effettuate in un sistema (ad esempio Google Ads) e le approvazioni vengono eseguite nell'altro sistema (ad esempio in Merchant Center o tramite l'API Merchant).

• Gestione delle schede locali: per questo servizio, l'handshake viene proposto in un metodo dedicato e le approvazioni vengono eseguite nell'altro sistema (ad esempio Profilo dell'attività su Google). I passaggi dettagliati sono riportati nella Guida per collegare un profilo dell'attività su Google.

• Gestione account: per questo servizio, la normale procedura di handshake si applica quando si utilizza propose. Se il servizio viene aggiunto durante la creazione dell'account utilizzando createAndConfigure, viene approvato automaticamente.

• Gestione dei prodotti: per questo servizio, si applica la normale procedura di handshake (proposta da una parte, seguita dall'accettazione dell'altra).

Diritti di accesso

Ogni tipo di servizio fornisce un determinato livello di accesso per gli utenti del fornitore di servizi all'account in assistenza:

• Aggregazione degli account: questo servizio fornisce diritti ADMIN completi.

• Gestione delle campagne: questo servizio fornisce un diritto di accesso limitato, consentendo all'account Google Ads associato di accedere ai prodotti e alle informazioni di base dell'account.

• Shopping comparativo: questo servizio fornisce, per impostazione predefinita, diritti ADMIN completi. Tuttavia, l'attività può limitare l'accesso concesso in Merchant Center.

• Gestione delle schede locali: questo servizio non fornisce alcun diritto di accesso diretto. Consente invece alla scheda di sincronizzare i suoi prodotti con l'account Merchant Center.

Importante: i diritti di accesso descritti per i seguenti tipi di servizio si applicano solo ai fornitori di servizi approvati. Se sei un fornitore di servizi e vuoi utilizzare questa funzionalità, contatta il nostro team di assistenza. Se in precedenza avevi già ricevuto l'approvazione per il metodo accounts.link per la gestione dei prodotti nell'API Content for Shopping, puoi utilizzare questo servizio nell'API Merchant senza ulteriori approvazioni.

• Gestione account: questo servizio fornisce, per impostazione predefinita, diritti ADMIN completi.

• Gestione dei prodotti: questo servizio fornisce diritti ADMIN completi. Tieni presente che in futuro questi diritti di accesso saranno limitati solo a quelli relativi ai prodotti.

Come vengono applicate le relazioni per le piattaforme di terze parti

Se sei una piattaforma di terze parti che gestisce account per conto di altre attività, di seguito viene illustrato come i diversi concetti vengono mappati alla struttura dell'account:

1. Fornitore di servizi: il tuo account avanzato.
2. Account che riceve il servizio: un account Merchant Center che rappresenta l'attività che gestisci.
3. Servizio:
   • accountManagement: questo è il servizio consigliato per le piattaforme di e-commerce e i partner di canale che creano nuovi account per conto dei commercianti. Crea un account di proprietà del commerciante, collegato a te per la gestione. Ciò è in linea con la struttura preferita di Merchant Center per questo caso d'uso.
   • accountAggregation: questo servizio collega il tuo account avanzato a un altro account. Sebbene sia supportato, non è consigliato per le piattaforme di e-commerce e i partner di canale.

Per informazioni dettagliate su come configurare un account avanzato e collegarlo a nuovi account Merchant Center, consulta Crea account.