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 fornitore, ad esempio la gestione dei prodotti o la gestione delle campagne. Ad esempio, il collegamento del tuo account Merchant Center a un account Google Ads consente all'account Ads 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 dell'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 di account: questo servizio collega un account avanzato a un altro account, concedendo all'account avanzato l'accesso completo e senza restrizioni. In genere viene 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 di account, devi omettere externalAccountId.

• Gestione delle campagne: questo servizio modella il collegamento tra un account Merchant Center e un account Google Ads, consentendo all'account Ads di accedere ai dati di prodotto e dell'account 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 rivenditori/ marketplace che utilizzano rete commerce media tramite gli account Google Ads:

• Questo servizio consente di creare filtri di prodotto specifici per i partner quando si pubblicano campagne sulla rete commerce media.
• Al momento, devi utilizzare la versione Alpha della sotto-API Accounts.
• L'utilizzo di questa funzionalità richiede l'inserimento in una lista consentita GMC specifica.

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 la relazione con un gestore 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ò essere proposto anche a un account esistente.

• Gestione dei prodotti: questo servizio consente ai fornitori di gestire i prodotti e le funzionalità correlate, come le origini dati e le 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. Questa procedura di autorizzazione è chiamata stretta di mano.

La stretta di mano è una procedura 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 i diritti di accesso di seguito).

Tieni presente che l'utente che crea, rifiuta o approva una proposta deve disporre dei ADMIN diritti di accesso sull'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.

I seguenti esempi mostrano come proporre un servizio per l'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 della stretta di mano specifico per il servizio

Di seguito è riportata una descrizione dei requisiti specifici della stretta di mano per ogni singolo servizio:

• Aggregazione di 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 perché gli utenti dell'account avanzato hanno accesso ADMIN completo 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 stretta di mano, 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, la stretta di mano viene proposta 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, la normale procedura di stretta di mano 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 stretta di mano (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 gestito:

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

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

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

• Gestione delle schede locali: questo servizio non fornisce diritti di accesso diretti. Consente invece alla scheda di sincronizzare i propri 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. Contatta il nostro support team di assistenza se sei un fornitore di servizi e vuoi utilizzare questa funzionalità. 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: per impostazione predefinita, questo servizio fornisce diritti ADMIN completi.

• Gestione dei prodotti: questo servizio fornisce diritti ADMIN completi. Tieni presente che in futuro questo sarà limitato ai diritti di accesso relativi ai prodotti.

Come si applicano le relazioni per le piattaforme di terze parti

Se sei una piattaforma di terze parti che gestisce gli account per conto di altre attività, di seguito viene illustrato come i diversi concetti vengono mappati nella 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. Questo è in linea con la struttura di Merchant Center preferita 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 Creare account.