روابط حساب را مدیریت کنید

شما می‌توانید از API حساب‌ها برای مدیریت روابط بین حساب مرکز فروشندگان خود و سایر ارائه‌دهندگان خدمات استفاده کنید. یک رابطه، یک اتصال رسمی است که یک ارائه‌دهنده را قادر می‌سازد خدمات خاصی را به کسب‌وکار شما ارائه دهد. یک سرویس، مجوزها و قابلیت‌های اعطا شده به ارائه‌دهنده، مانند مدیریت محصول یا مدیریت کمپین را تعریف می‌کند. به عنوان مثال، پیوند دادن حساب مرکز فروشندگان خود به یک حساب Google Ads به حساب Ads اجازه می‌دهد تا از داده‌های محصول شما برای اجرای کمپین‌های تبلیغاتی استفاده کند.

یک رابطه از ویژگی‌های زیر تشکیل شده است:

• حساب مرکز بازرگانان که سرویس را دریافت می‌کند
• ارائه دهنده خدمات
• سرویس یا مجموعه‌ای از سرویس‌ها که به حساب مرکز فروشندگان ارائه می‌شود

نام مستعار

ارائه دهندگان خدمات می‌توانند یک نام مستعار را به حساب‌هایی که به آنها خدمات می‌دهند، مرتبط کنند (این معادل فیلد seller_id است که در منبع حساب در Content API for Shopping وجود داشت). این نام مستعار را می‌توان با استفاده از فیلد اختیاری account_id_alias در منبع AccountRelationship اختصاص داد و به عنوان یک شناسه سفارشی عمل کرد. نام مستعار باید شامل ۱ تا ۵۰ کاراکتر باشد که از حروف ASCII، ارقام اعشاری، خط فاصله، زیرخط، نقطه یا تیلدها انتخاب می‌شوند ( [A-Za-z0-9_~.-]{1,50} ).

ساختار URL برای دسترسی به یک حساب کاربری با استفاده از نام مستعار آن به صورت GET /accounts/v1/accounts/{provider}~{account_id_alias} است.

خدمات

در API حساب‌ها، حساب‌ها می‌توانند سرویس‌های زیر را دریافت کنند. می‌توانید بسیاری از این سرویس‌ها را هنگام ایجاد حساب اضافه کنید.

• تجمیع حساب‌ها : این سرویس یک حساب پیشرفته را به یک حساب دیگر متصل می‌کند و به حساب پیشرفته دسترسی کامل و بدون محدودیت می‌دهد. این سرویس معمولاً توسط فروشگاه‌های آنلاین، خرده‌فروشان چند برندی یا خرده‌فروشان بین‌المللی که به کنترل متمرکز بر حساب‌های تو در تو نیاز دارند، استفاده می‌شود. اگر شما یک پلتفرم تجارت الکترونیک یا شریک کانال هستید، توصیه می‌کنیم به جای آن accountManagement استفاده کنید. هنگام ایجاد حساب با استفاده از تجمیع حساب‌ها، باید externalAccountId حذف شود.

• مدیریت کمپین : این سرویس، ارتباط بین یک حساب مرکز فروش و یک حساب گوگل ادز را مدل‌سازی می‌کند و به حساب ادز دسترسی به داده‌های محصول و حساب مورد نیاز برای اجرای کمپین‌های تبلیغاتی را می‌دهد. ارائه‌دهنده خدمات در این مورد GOOGLE_ADS است و externalAccountId شناسه حساب گوگل ادز است. این سرویس همچنین می‌تواند به یک حساب موجود پیشنهاد شود.

توجه: برای خرده‌فروشان/بازارهایی که از طریق حساب‌های گوگل ادز از شبکه رسانه‌ای تجارت استفاده می‌کنند:

• این سرویس امکان ایجاد فیلترهای محصول خاص شریک را هنگام اجرای کمپین‌های شبکه رسانه‌ای تجارت فراهم می‌کند.
• در حال حاضر، شما باید از نسخه آلفای زیر-API حساب‌ها استفاده کنید.
• استفاده از این ویژگی نیاز به فهرست مجاز خاص GMC دارد.

برای اطلاعات بیشتر با تیم مدیریت حساب گوگل ادز خود تماس بگیرید.

• خرید مقایسه‌ای : این نشان دهنده ارتباط با یک سرویس خرید مقایسه‌ای (CSS) است که حساب مرکز فروشندگان را اداره می‌کند.

• مدیریت فهرست محلی : این نشان دهنده ارتباط با مدیر فروشگاه برای مدیریت موجودی و فهرست‌های محلی با استفاده از نمایه تجاری گوگل است.

• مدیریت حساب : این سرویس به ارائه‌دهنده امکان می‌دهد تا اقدامات مدیریتی را روی حساب مرکز فروشندگان انجام دهد، مانند پیکربندی تنظیمات حساب، مدیریت کاربران یا به‌روزرسانی اطلاعات کسب‌وکار. کسب‌وکار همچنین می‌تواند دسترسی‌های اعطا شده را محدود کند. هنگامی که این سرویس در هنگام ایجاد حساب استفاده می‌شود، یک حساب کاربری مرتبط با ارائه‌دهنده ایجاد می‌کند که رویکرد توصیه‌شده برای پلتفرم‌های تجارت الکترونیک و شرکای کانال است. همچنین می‌توان آن را به یک حساب کاربری موجود پیشنهاد داد.

• مدیریت محصولات : این سرویس به ارائه‌دهندگان اجازه می‌دهد تا محصولات و ویژگی‌های مرتبط مانند منابع داده و قوانین را مدیریت کنند. وقتی در طول ایجاد حساب اضافه می‌شود، معمولاً در ترکیب با accountManagement یا accountAggregation است. این سرویس همچنین می‌تواند برای یک حساب موجود پیشنهاد شود.

دست دادن

برای ایجاد یک سرویس، هم حساب ارائه دهنده سرویس و هم حساب دریافت کننده سرویس باید اتصال را تأیید کنند. این فرآیند تأیید، handshake نامیده می‌شود.

دست دادن یک فرآیند دو مرحله‌ای است:

1. یکی از طرفین پیشنهاد پیوند خدماتی می‌دهد.
2. طرف مقابل پیشنهاد را تأیید یا رد می‌کند.

پس از پذیرش پیشنهاد، سرویس تأیید شده و کاملاً تثبیت شده تلقی می‌شود. اکنون هرگونه حق دسترسی که به ارائه‌دهنده خدمات اعطا شده باشد، به کاربران واجد شرایط اعطا می‌شود (به حقوق دسترسی در زیر مراجعه کنید).

توجه داشته باشید که کاربری که پیشنهادی را ایجاد، رد یا تأیید می‌کند، باید در حسابی که فرآیند را آغاز می‌کند، حق دسترسی ADMIN داشته باشد. بنابراین اگر ارائه‌دهنده خدمات، خدماتی را پیشنهاد می‌دهد، کاربری که پیشنهاد می‌دهد باید در حساب ارائه‌دهنده خدمات، ADMIN باشد و کاربری که پیشنهاد را می‌پذیرد یا رد می‌کند، باید در حساب دریافت‌کننده، ADMIN باشد.

نمونه‌های زیر نحوه پیشنهاد یک سرویس حساب کاربری را نشان می‌دهند:

جاوا

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

پی اچ پی

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

پایتون

"""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

رفتار دست دادن مختص سرویس

در زیر شرح الزامات خاص handshake برای هر سرویس جداگانه آمده است:

• تجمیع حساب : این سرویس فقط می‌تواند به عنوان بخشی از ایجاد حساب ایجاد شود. انتظار می‌رود ارائه دهنده خدمات یک حساب پیشرفته باشد و این سرویس به طور خودکار تأیید می‌شود زیرا کاربران حساب پیشرفته دسترسی کامل به ADMIN به حساب ایجاد شده دارند.

• خرید مقایسه‌ای : این سرویس هنگام ایجاد حساب با استفاده از createAndConfigure به طور خودکار تأیید می‌شود.

• مدیریت کمپین : اگرچه این فرآیند از روند معمول تبادل اطلاعات پیروی می‌کند، اما پیشنهادها در یک سیستم (مثلاً گوگل ادز) ارائه می‌شوند و تأییدها در سیستم دیگر (مثلاً در مرکز فروشندگان یا از طریق رابط برنامه‌نویسی کاربردی فروشندگان) انجام می‌شود.

• مدیریت فهرست محلی : برای این سرویس، روش handshake (دست دادن) به صورت اختصاصی پیشنهاد شده و تأییدها در سیستم دیگر (مثلاً نمایه تجاری گوگل) انجام می‌شود. مراحل دقیق در راهنمای پیوند نمایه تجاری گوگل آمده است.

• مدیریت حساب : برای این سرویس، فرآیند معمول handshake هنگام استفاده از propose اعمال می‌شود. اگر سرویس هنگام ایجاد حساب با استفاده از createAndConfigure اضافه شود، به طور خودکار تأیید می‌شود.

• مدیریت محصولات : برای این سرویس، فرآیند معمول handshake (پیشنهاد توسط یک طرف و به دنبال آن پذیرش از طرف دیگر) اعمال می‌شود.

حقوق دسترسی

هر نوع سرویس، سطح دسترسی مشخصی را برای کاربران ارائه‌دهنده سرویس، از طریق حسابی که به آن سرویس داده می‌شود، فراهم می‌کند:

• تجمیع حساب‌ها : این سرویس حقوق کامل ADMIN را ارائه می‌دهد.

• مدیریت کمپین : این سرویس یک حق دسترسی محدود ارائه می‌دهد و به حساب تبلیغات مرتبط اجازه می‌دهد به محصولات و اطلاعات اولیه حساب دسترسی داشته باشد.

• خرید مقایسه‌ای : این سرویس به طور پیش‌فرض، حقوق کامل ADMIN را ارائه می‌دهد. با این حال، کسب و کار می‌تواند دسترسی‌های اعطا شده در مرکز فروشندگان را محدود کند.

• مدیریت فهرست محلی : این سرویس هیچ حق دسترسی مستقیمی ارائه نمی‌دهد. در عوض، فهرست را قادر می‌سازد تا محصولات خود را با حساب مرکز فروشندگان همگام‌سازی کند.

مهم : حقوق دسترسی شرح داده شده برای انواع خدمات زیر فقط برای ارائه دهندگان خدمات تأیید شده اعمال می‌شود. اگر شما ارائه دهنده خدمات هستید و می‌خواهید از این قابلیت استفاده کنید، با تیم پشتیبانی ما تماس بگیرید. اگر قبلاً برای روش accounts.link برای مدیریت محصولات در Content API for Shopping تأیید شده‌اید، می‌توانید بدون تأیید بیشتر از این سرویس در Merchant API استفاده کنید.

• مدیریت حساب : این سرویس به طور پیش‌فرض، حقوق کامل ADMIN را ارائه می‌دهد.

• مدیریت محصولات : این سرویس حقوق کامل ADMIN را ارائه می‌دهد. توجه داشته باشید که در آینده، این حقوق فقط به حقوق دسترسی مرتبط با محصول محدود خواهد شد.

نحوه اعمال روابط برای پلتفرم‌های شخص ثالث

اگر شما یک پلتفرم شخص ثالث هستید که حساب‌ها را از طرف سایر کسب‌وکارها مدیریت می‌کند، موارد زیر نشان می‌دهد که چگونه مفاهیم مختلف با ساختار حساب شما مطابقت دارند:

1. ارائه دهنده خدمات : حساب پیشرفته شما.
2. حساب دریافت‌کننده سرویس : یک حساب مرکز تجاری که نشان‌دهنده کسب‌وکاری است که شما مدیریت می‌کنید.
3. خدمات :
   • accountManagement : این سرویس برای پلتفرم‌های تجارت الکترونیک و شرکای کانال که از طرف فروشندگان حساب‌های جدید ایجاد می‌کنند، توصیه می‌شود. این سرویس، حسابی ایجاد می‌کند که متعلق به فروشنده است و برای مدیریت به شما لینک می‌شود. این سرویس با ساختار ترجیحی مرکز فروشندگان برای این مورد استفاده، همسو است.
   • accountAggregation : این سرویس حساب پیشرفته شما را به یک حساب دیگر متصل می‌کند. اگرچه پشتیبانی می‌شود، اما برای پلتفرم‌های تجارت الکترونیک و شرکای کانال توصیه نمی‌شود.

برای جزئیات بیشتر در مورد نحوه راه‌اندازی یک حساب پیشرفته و پیوند به حساب‌های جدید مرکز بازرگانان، به ایجاد حساب‌ها مراجعه کنید.