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 fornitore di offrire servizi specifici alla tua attività. Un servizio definisce le autorizzazioni e le funzionalità concesse al provider, ad esempio la gestione dei prodotti o delle campagne. Ad esempio, il collegamento dell'account Merchant Center a un account Google Ads consente all'account inserzionista di utilizzare i 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 nell'API Content for 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 a 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 (accountAggregation) collega un account avanzato multi-cliente a un subaccount, concedendo all'account avanzato l'accesso completo e senza restrizioni e rendendo visibile il subaccount nell'interfaccia utente di Merchant Center. L'interfaccia utente di Merchant Center converte automaticamente gli account in account avanzati con accountAggregation per i creatori di negozi (piattaforme di e-commerce), i partner di canale, i marketplace, i rivenditori multimarca e i rivenditori internazionali durante la creazione di nuovi subaccount. Se sei un'agenzia, utilizza invece accountManagement. Quando crei un account utilizzando l'aggregazione degli account, 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 inserzionista di accedere ai dati dell'account e dei prodotti necessari per pubblicare campagne pubblicitarie. In questo caso, il fornitore di servizi è GOOGLE_ADS e externalAccountId è l'ID dell'account Google Ads. Questo servizio può essere proposto anche a un account esistente.

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

• Questo servizio consente di creare filtri dei prodotti specifici per i partner durante la pubblicazione di campagne di reti 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 la relazione con un Servizio di shopping comparativo (CSS) che gestisce l'account Merchant Center.

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

• Gestione dell'account: questo servizio (accountManagement) consente al provider di eseguire azioni amministrative su un account Merchant Center esterno autonomo, ad esempio la configurazione delle impostazioni dell'account, la gestione degli utenti o l'aggiornamento delle informazioni sull'attività. L'attività può anche limitare l'accesso concesso. Se utilizzato durante la creazione dell'account, questo servizio crea un account autonomo collegato al provider. Può anche essere proposto a un account esistente. Le agenzie che utilizzano questo tipo di servizio possono visualizzare gli account che gestiscono in Merchant Center per le agenzie. I creatori di negozi e i partner di canale possono utilizzare l'API Merchant per estrarre informazioni sui commercianti che gestiscono tramite accountManagement.

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

• Gestione del pagamento UCP (v1alpha, accesso limitato): il servizio ucpCheckoutManagement consente a un fornitore di servizi approvato di gestire le integrazioni, le impostazioni e la partecipazione al programma di pagamento UCP per conto di un commerciante. Questo servizio può essere proposto o approvato solo da un account Merchant Center esistente.

  Nota: l'Acquisto rapido con UCP è una funzionalità alfa con accesso limitato. Scopri di più sui fornitori di servizi e sul checkout UCP in Merchant Center per i fornitori di servizi.

Stretta di mano

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

L'handshake è un processo in due fasi:

1. Una parte propone un collegamento 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).

Importante: la propagazione dei diritti di accesso tra account può richiedere fino a 60 secondi dopo la chiamata di accounts.services.approve. Se le richieste API Merchant successive all'account collegato restituiscono 401 UNAUTHENTICATED, riprova con il backoff esponenziale.

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

I seguenti esempi 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 dell'handshake specifico per il servizio

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

• 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 ADMIN completo all'account in fase di creazione.

• Confronto prezzi: 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). La procedura dettagliata è disponibile nella guida per collegare un Profilo dell'attività su Google.

• Gestione dell'account: per questo servizio, quando utilizzi propose si applica la normale procedura di handshake. 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).

• Gestione del pagamento UCP (v1alpha, accesso limitato): per questo servizio, il commerciante può completare l'handshake tramite la finestra di dialogo di collegamento degli account ospitata da Google nel portale del fornitore di servizi o utilizzando la procedura di handshake standard (propose seguita da approve). Per i dettagli sull'integrazione, consulta la documentazione per i fornitori di servizi di Merchant Center.

Diritti di accesso

Ogni tipo di servizio fornisce un determinato livello di accesso per gli utenti del fornitore di servizi sull'account per cui viene fornito il servizio:

• Aggregazione di 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, i 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 servizi 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 hai 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 dell'account: questo servizio fornisce, per impostazione predefinita, diritti ADMIN completi.

• Gestione dei prodotti: questo servizio fornisce diritti completi per ADMIN. Tieni presente che in futuro questa opzione sarà limitata solo ai diritti di accesso relativi ai prodotti.

• Gestione del pagamento UCP (v1alpha, accesso limitato): questo servizio fornisce diritti ADMIN completi. Tieni presente che in futuro questo accesso sarà limitato solo ai diritti di accesso relativi al pagamento della piattaforma per i clienti unificata.

Come si applicano 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 mostrato come i diversi concetti vengono mappati alla struttura del tuo 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:
   • accountAggregation: utilizzato da piattaforme di e-commerce, partner di canale, marketplace e rivenditori multimarca che creano nuovi subaccount per conto dei commercianti. La UI di Merchant Center configura automaticamente i gestori di negozi e i partner di canale come account avanzati con accountAggregation, consentendo loro di visualizzare e gestire i subaccount nella UI di Merchant Center.
   • accountManagement: utilizzato dalle agenzie che creano o collegano account cliente autonomi di proprietà del commerciante, che possono visualizzare in Merchant Center per le agenzie. Altri tipi di fornitori di servizi utilizzano il metodo accounts.list nell'API Merchant per visualizzare i dati degli account collegati.

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