アカウントの関係を管理する

Accounts API を使用すると、Merchant Center アカウントと他のサービス プロバイダとの関係を管理できます。関係は、プロバイダが特定のサービスをビジネスに提供できるようにする正式な接続です。サービスは、プロダクト管理やキャンペーン管理など、プロバイダに付与される権限と機能を定義します。たとえば、Merchant Center アカウントを Google 広告アカウントにリンクすると、広告アカウントで商品データを使用して広告キャンペーンを実施できるようになります。

リレーションシップは次の属性で構成されます。

  • サービスを受ける Merchant Center アカウント
  • サービス提供者
  • Merchant Center アカウントに提供されるサービスまたはサービスのセット

エイリアス

サービス プロバイダは、サービスを提供するアカウントにエイリアスを関連付けることができます(これは、Content API for Shopping の account リソースに存在していた seller_id フィールドと同等です)。エイリアスは、AccountRelationship リソース内のオプションの account_id_alias フィールドを使用して割り当てることができ、カスタム識別子として機能します。エイリアスは、ASCII 文字、10 進数、ハイフン、アンダースコア、ピリオド、チルダ([A-Za-z0-9_~.-]{1,50})から選択した 1 ~ 50 文字で構成する必要があります。

エイリアスを使用してアカウントにアクセスするための URL 構造は GET /accounts/v1/accounts/{provider}~{account_id_alias} です。

サービス

Accounts API では、アカウントは次のサービスを利用できます。これらのサービスの多くは、アカウントの作成時に追加できます。

  • アカウントの集約: このサービスは、アドバンス アカウントを別のアカウントにリンクし、アドバンス アカウントに完全な無制限のアクセス権を付与します。通常は、ネストされたアカウントを一元的に管理する必要があるショッピング モール、マルチブランドの小売業者、国際的な小売業者が使用します。e コマース プラットフォームまたはチャネル パートナーの場合は、代わりに accountManagement を使用することをおすすめします。アカウント統合を使用してアカウントを作成する場合は、externalAccountId を省略する必要があります。

  • キャンペーン管理: このサービスは、Merchant Center アカウントと Google 広告アカウントのリンクをモデル化し、広告キャンペーンの実施に必要な商品データとアカウント データへのアクセス権を Google 広告アカウントに付与します。この場合のサービス プロバイダは GOOGLE_ADS で、externalAccountId は Google 広告アカウントの ID です。このサービスは既存のアカウントにも提案できます。

  • ショッピング比較: Merchant Center アカウントを運営するショッピング比較サービス(CSS)との関係を表します。

  • ローカル リスティングの管理: Google ビジネス プロフィールを使用してローカル在庫とリスティングを管理する店舗管理者との関係を表します。

  • アカウント管理: このサービスにより、プロバイダは Merchant Center アカウントで管理アクション(アカウント設定の構成、ユーザーの管理、ビジネス情報の更新など)を実行できます。ビジネスは、付与されたアクセスを制限することもできます。アカウントの作成時に使用すると、このサービスはプロバイダにリンクされたアカウントを作成します。これは、e コマース プラットフォームやチャネル パートナーにおすすめの方法です。既存のアカウントに提案することもできます。

  • プロダクトの管理: このサービスを使用すると、プロバイダはプロダクトと、データソースやルールなどの関連機能を管理できます。アカウントの作成時に追加される場合は、通常 accountManagement または accountAggregation と組み合わせて使用されます。このサービスは既存のアカウントにも提案できます。

握手

サービスを確立するには、サービスを提供するアカウントとサービスを受け取るアカウントの両方が接続を承認する必要があります。この認証プロセスはハンドシェイクと呼ばれます。

ハンドシェイクは 2 段階のプロセスです。

  1. 一方の当事者がサービスリンクを提案します。
  2. 相手方が提案を承認または却下します。

プロポーザルが承認されると、サービスは承認され、完全に確立されたと見なされます。サービス提供者に付与されたアクセス権は、認定ユーザーに付与されるようになりました(下記のアクセス権を参照)。

提案を作成、拒否、承認するユーザーには、プロセスを開始するアカウントに対する 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);
  }
}

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();

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_)

サービス固有のハンドシェイクの動作

各サービスの具体的なハンドシェイク要件は次のとおりです。

  • アカウントの集計: このサービスは、アカウントの作成の一環としてのみ確立できます。サービス提供者はアドバンス アカウントであると想定され、アドバンス アカウントのユーザーは作成されるアカウントに対する ADMIN アクセス権を完全に持っているため、サービスは自動的に承認されます。

  • 比較ショッピング: createAndConfigure を使用してアカウントの作成時に追加すると、このサービスは自動的に承認されます。

  • キャンペーン管理: 通常のハンドシェイク プロセスに従いますが、提案は一方のシステム(Google 広告など)で行われ、承認はもう一方のシステム(Merchant Center や Merchant API など)で行われます。

  • ローカル リスティングの管理: このサービスでは、専用の方法でハンドシェイクが提案され、承認は別のシステム(Google ビジネス プロフィールなど)で行われます。詳しい手順については、Google ビジネス プロフィールをリンクするためのガイドをご覧ください。

  • アカウント管理: このサービスでは、propose を使用する場合、通常のハンドシェイク プロセスが適用されます。createAndConfigure を使用してアカウントの作成時にサービスが追加された場合、自動的に承認されます。

  • プロダクト管理: このサービスでは、通常のハンドシェイク プロセス(一方の当事者による提案、他方の当事者による承認)が適用されます。

アクセス権

各サービスタイプは、サービス プロバイダのユーザーに、サービス対象のアカウントに対する特定のレベルのアクセス権を付与します。

  • アカウントの集約: このサービスは完全な ADMIN 権限を提供します。

  • キャンペーン管理: このサービスは、関連付けられた広告アカウントが商品と基本的なアカウント情報にアクセスできるように、制限付きのアクセス権を提供します。

  • 価格比較: このサービスは、デフォルトで完全な ADMIN 権限を提供します。ただし、ビジネスは Merchant Center で付与されたアクセス権を制限できます。

  • ローカル リスティングの管理: このサービスには直接アクセス権はありません。代わりに、リスティングで商品を Merchant Center アカウントと同期できるようになります。

重要: 次のサービス タイプについて説明するアクセス権は、承認済みのサービス プロバイダにのみ適用されます。サービス提供者でこの機能を利用したい場合は、サポートチームにお問い合わせください。Content API for Shopping でのプロダクト管理に accounts.link メソッドがすでに承認されている場合は、Merchant API でこのサービスを承認なしで使用できます。

  • アカウント管理: このサービスは、デフォルトで完全な ADMIN 権限を提供します。

  • プロダクト管理: このサービスは完全な ADMIN 権限を提供します。なお、今後、この機能はプロダクト関連のアクセス権のみに制限される予定です。

サードパーティ プラットフォームでの関係の適用方法

他のビジネスに代わってアカウントを管理するサードパーティ プラットフォームの場合、次の図は、さまざまなコンセプトがアカウント構造にどのようにマッピングされるかを示しています。

  1. サービス提供者: アドバンス アカウント。
  2. サービスを受けるアカウント: 管理しているビジネスを表す Merchant Center アカウント。
  3. サービス:
    • accountManagement: これは、販売者の代わりに新しいアカウントを作成する e コマース プラットフォームやチャネル パートナーにおすすめのサービスです。販売者が所有するアカウントが作成され、管理のためにパートナーにリンクされます。これは、このユースケースに推奨される Merchant Center の構造に沿ったものです。
    • accountAggregation: このサービスは、アドバンス アカウントを別のアカウントにリンクします。サポートはされていますが、e コマース プラットフォームやチャネル パートナーにはおすすめしません。

高度なアカウントを設定して新しい Merchant Center アカウントにリンクする方法について詳しくは、アカウントを作成するをご覧ください。