Как управлять связями между аккаунтами

Accounts API позволяет управлять связями между вашим аккаунтом Merchant Center и другими поставщиками услуг. Связь – это формальное соглашение, которое позволяет поставщику предлагать определенные услуги вашей компании. Сервис определяет разрешения и возможности, предоставляемые поставщику, например управление товарами или кампаниями. Например, если вы свяжете аккаунт Merchant Center с аккаунтом Google Рекламы, то сможете использовать данные о товарах в рекламных кампаниях.

Связь состоит из следующих атрибутов:

• Аккаунт Merchant Center, получающий услугу.
• Поставщик услуг
• Сервис или набор сервисов, предоставляемых аккаунту Merchant Center.

Псевдоним

Поставщики услуг могут связывать псевдоним с аккаунтами, которые они обслуживают (это эквивалент поля seller_id, которое присутствовало в ресурсе account в Content API for Shopping). Псевдоним можно назначить с помощью необязательного поля account_id_alias в ресурсе AccountRelationship. Он служит пользовательским идентификатором. Псевдоним должен состоять из 1–50 символов ASCII, десятичных цифр, дефисов, символов подчеркивания, точек или тильд ([A-Za-z0-9_~.-]{1,50}).

Структура URL для доступа к аккаунту с помощью псевдонима: GET /accounts/v1/accounts/{provider}~{account_id_alias}.

Сервисы

В Accounts API аккаунты могут получать следующие сервисы: Многие из этих сервисов можно добавить во время создания аккаунта.

• Агрегирование аккаунтов. Этот сервис (accountAggregation) связывает расширенный мультиаккаунт с дочерним аккаунтом, предоставляя расширенному аккаунту полный неограниченный доступ и делая дочерний аккаунт видимым в интерфейсе Merchant Center. При создании новых дочерних аккаунтов в интерфейсе Merchant Center аккаунты конструкторов магазинов (платформ электронной торговли), партнеров по каналам продаж, торговых площадок, мультибрендовых и международных розничных продавцов автоматически преобразуются в расширенные аккаунты с accountAggregation. Если вы представляете агентство, используйте accountManagement. При создании аккаунта с помощью агрегирования аккаунтов параметр externalAccountId должен быть опущен.

• Управление кампаниями. Этот сервис моделирует связь между аккаунтом Merchant Center и аккаунтом Google Рекламы, предоставляя аккаунту рекламодателя доступ к данным в аккаунте и данным о товарах, необходимым для проведения рекламных кампаний. В данном случае поставщиком услуг является GOOGLE_ADS, а externalAccountId – это идентификатор аккаунта Google Рекламы. Эту услугу также можно предложить существующему аккаунту.

Примечание. Если вы розничный продавец или торговая площадка и используете сеть коммерческих медиа через аккаунты Google Рекламы, то:

• Этот сервис позволяет создавать фильтры товаров для определенных партнеров при проведении кампаний в сетях коммерческих медиа.
• В настоящее время необходимо использовать альфа-версию Accounts sub-API.
• Чтобы использовать эту функцию, нужно добавить аккаунт GMC в белый список.

За подробной информацией обращайтесь к команде по работе с аккаунтом Google Рекламы.

• Сравнение цен. Связь с сервисом сравнения цен, который управляет аккаунтом Merchant Center.

• Управление местными данными о компании. Отношения с менеджером магазина, который управляет местным ассортиментом и данными о компании с помощью профиля компании в Google.

• Управление аккаунтом. Этот сервис (accountManagement) позволяет поставщику выполнять административные действия в отдельном внешнем аккаунте Merchant Center, например задавать настройки аккаунта, управлять пользователями или обновлять информацию о компании. Компания также может ограничить предоставленный доступ. Если вы используете его при создании аккаунта, будет создан отдельный аккаунт, связанный с поставщиком. Также можно предложить связь с существующим аккаунтом. Агентства, которые используют этот тип сервиса, могут видеть аккаунты, которыми они управляют, в Merchant Center для агентств. Разработчики магазинов и издатели-партнеры могут использовать Merchant API, чтобы получать информацию о продавцах, которыми они управляют через accountManagement.

• Управление товарами. Этот сервис позволяет поставщикам управлять товарами и связанными с ними функциями, такими как источники данных и правила. При создании аккаунта он обычно используется в сочетании с accountManagement или accountAggregation. Эту услугу также можно предложить существующему аккаунту.

• Управление оформлением покупок через UCP (v1alpha, ограниченный доступ). Сервис ucpCheckoutManagement позволяет одобренному поставщику услуг управлять интеграциями, настройками и участием в программе оформления покупок через UCP от имени продавца. Этот сервис можно предложить только существующему аккаунту Merchant Center, и только он может одобрить предложение.

  Примечание. Оформление покупки UCP – это альфа-функция с ограниченным доступом. Подробнее о поставщиках услуг и оформлении покупок на единой платформе читайте в статье Merchant Center для поставщиков услуг.

Рукопожатие

Чтобы установить связь, оба аккаунта должны подтвердить подключение. Этот процесс авторизации называется рукопожатием.

Рукопожатие состоит из двух этапов:

1. Одна сторона предлагает установить связь с сервисом.
2. Другая сторона принимает или отклоняет предложение.

После того как предложение будет принято, сервис считается одобренным и полностью настроенным. Любое право доступа, предоставленное поставщику услуг, теперь предоставляется пользователям, отвечающим требованиям (см. раздел Права доступа ниже).

Важно! Права доступа между аккаунтами могут распространяться до 60 секунд после вызова accounts.services.approve. Если последующие запросы Merchant API к связанному аккаунту возвращают ошибку 401 UNAUTHENTICATED, повторите попытку с экспоненциальной выдержкой.

Обратите внимание, что у пользователя, который создает, отклоняет или одобряет предложение, должны быть ADMIN права доступа к аккаунту, инициирующему процесс. Например, если предложение поступает от поставщика услуг, то пользователь, который его отправляет, должен быть ADMIN в аккаунте поставщика услуг, а пользователь, который принимает или отклоняет предложение, должен быть ADMIN в аккаунте получателя.

Ниже приведены примеры того, как предложить услугу для аккаунта.

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

Особенности рукопожатия в разных сервисах

Ниже приведены требования к рукопожатию для каждого сервиса.

• Агрегирование аккаунтов. Эту услугу можно настроить только при создании аккаунта. Поставщик услуг должен быть расширенным аккаунтом, а сервис автоматически одобряется, поскольку у пользователей расширенного аккаунта есть полный доступ ADMIN к создаваемому аккаунту.

• Сравнение цен. Этот сервис автоматически одобряется при добавлении во время создания аккаунта с помощью createAndConfigure.

• Управление кампаниями. В этом случае используется стандартный процесс рукопожатия, но предложения создаются в одной системе (например, в Google Рекламе), а подтверждаются в другой (например, в Merchant Center или через Merchant API).

• Управление местными данными. Для этого сервиса рукопожатие предлагается специальным методом, а одобрение выполняется в другой системе (например, в профиле компании в Google). Подробные инструкции вы найдете в руководстве по связыванию профиля компании в Google.

• Управление аккаунтом. Для этого сервиса при использовании propose применяется обычный процесс рукопожатия. Если сервис добавляется во время создания аккаунта с помощью createAndConfigure, он одобряется автоматически.

• Управление товарами. Для этого сервиса применяется стандартный процесс подтверждения (одна сторона предлагает, другая принимает).

• Управление оформлением покупок на платформе UCP (v1alpha, ограниченный доступ). Продавец может выполнить рукопожатие через диалоговое окно связывания аккаунтов, размещенное в Google, на портале поставщика услуг или с помощью стандартного процесса рукопожатия (propose, а затем approve). Подробные сведения об интеграции можно найти в документации для поставщиков услуг Merchant Center.

Права доступа

Каждый тип сервиса предоставляет пользователям поставщика услуг определенный уровень доступа к обслуживаемому аккаунту:

• Агрегирование аккаунтов. Этот сервис предоставляет полные права ADMIN.

• Управление кампаниями. Этот сервис предоставляет ограниченный доступ, позволяя связанному аккаунту Google Рекламы получать доступ к продуктам и базовой информации об аккаунте.

• Сравнение цен. По умолчанию этот сервис предоставляет полные права на ADMIN. Однако компания может ограничить доступ, предоставленный в Merchant Center.

• Управление данными о компании. Этот сервис не предоставляет права прямого доступа. Вместо этого он позволяет синхронизировать товары в объявлении с аккаунтом Merchant Center.

Важно! Права доступа, описанные для перечисленных ниже типов сервисов, применяются только к одобренным поставщикам услуг. Если вы поставщик услуг и хотите воспользоваться этой возможностью, обратитесь в службу поддержки. Если вы уже получили разрешение на использование метода accounts.link для управления товарами в Content API for Shopping, вы можете использовать этот сервис в Merchant API без дополнительных разрешений.

• Управление аккаунтом. По умолчанию этот сервис предоставляет полные права ADMIN.

• Управление товарами. Этот сервис предоставляет полные права на ADMIN. Обратите внимание, что в будущем это будет ограничено только правами доступа, связанными с продуктом.

• Управление оформлением заказов через UCP (v1alpha, ограниченный доступ). Этот сервис предоставляет полные права ADMIN. Обратите внимание, что в будущем доступ будет ограничен только правами, связанными с оплатой в UCP.

Как связи применяются к сторонним платформам

Если вы представляете стороннюю платформу, которая управляет аккаунтами от имени других компаний, то структура вашего аккаунта будет выглядеть следующим образом:

1. Поставщик услуг. Ваш расширенный аккаунт.
2. Аккаунт, получающий услугу. Аккаунт Merchant Center, который представляет компанию, которой вы управляете.
3. Сервис.
   • accountAggregation – используется конструкторами интернет-магазинов (платформами электронной торговли), издателями-партнерами, торговыми площадками и мультибрендовыми розничными продавцами, создающими новые дочерние аккаунты от имени продавцов. В интерфейсе Merchant Center конструкторы магазинов и издатели-партнеры автоматически настраиваются как расширенные аккаунты с accountAggregation, что позволяет им просматривать дочерние аккаунты и управлять ими в интерфейсе Merchant Center.
   • accountManagement: используется агентствами, которые создают или связывают отдельные клиентские аккаунты, принадлежащие продавцу. Эти аккаунты можно просматривать в Merchant Center для агентств. Другие типы поставщиков услуг используют метод accounts.list в Merchant API, чтобы просматривать информацию о связанных аккаунтах.

Подробнее о том, как настроить расширенный аккаунт и связать его с новыми аккаунтами Merchant Center, читайте в статье Как создавать аккаунты.