إدارة علاقات الحسابات

يمكنك استخدام واجهة برمجة التطبيقات Accounts API لإدارة العلاقات بين حسابك على Merchant Center ومقدّمي الخدمات الآخرين. العلاقة هي اتصال رسمي يتيح لمزوّد الخدمة تقديم خدمات معيّنة لنشاطك التجاري. تحدّد الخدمة الأذونات والإمكانات الممنوحة لمقدّم الخدمة، مثل إدارة المنتجات أو إدارة الحملات. على سبيل المثال، يتيح ربط حسابك على Merchant Center بحساب على "إعلانات Google" لحساب "إعلانات Google" استخدام بيانات منتجاتك لتشغيل الحملات الإعلانية.

تتألف العلاقة من السمات التالية:

  • حساب Merchant Center الذي يتلقّى الخدمة
  • مقدّم الخدمة
  • الخدمة أو مجموعة الخدمات المقدَّمة إلى حساب Merchant Center

الاسم المستعار

يمكن لمقدّمي الخدمات ربط اسم مستعار بالحسابات التي يقدّمون خدماتهم لها (هذا الاسم هو المكافئ للحقل seller_id الذي كان متوفّرًا في مصدر الحساب في Content API for Shopping). يمكن تعيين الاسم المستعار باستخدام الحقل الاختياري account_id_alias ضمن المورد AccountRelationship، ويُستخدَم كمعرّف مخصّص. يجب أن يتألف الاسم المستعار من حرف واحد إلى 50 حرفًا يتم اختيارها من أحرف ASCII أو الأرقام العشرية أو الواصلات أو الشرطات السفلية أو النقاط أو علامات التلدة ([A-Za-z0-9_~.-]{1,50}).

بنية عنوان URL للوصول إلى حساب باستخدام الاسم المستعار هي GET /accounts/v1/accounts/{provider}~{account_id_alias}.

الخدمات

في Accounts API، يمكن أن تتلقّى الحسابات الخدمات التالية. يمكنك إضافة العديد من هذه الخدمات أثناء إنشاء الحساب.

  • تجميع الحسابات: تربط هذه الخدمة حسابًا بامتيازات متقدّمة بحساب آخر، ما يمنح الحساب بامتيازات متقدّمة إذن الوصول الكامل وغير المقيد. يُستخدم عادةً من قِبل الأسواق أو بائعي التجزئة الذين يبيعون علامات تجارية متعدّدة أو بائعي التجزئة الدوليين الذين يحتاجون إلى تحكّم مركزي في الحسابات المتداخلة. إذا كنت شريكًا في منصة أو قناة للتجارة الإلكترونية، ننصحك باستخدام accountManagement بدلاً من ذلك. عند إنشاء حساب باستخدام ميزة تجميع الحسابات، يجب حذف externalAccountId.

  • إدارة الحملات: تعمل هذه الخدمة على تصميم الرابط بين حساب على Merchant Center وحساب على "إعلانات Google"، ما يمنح حساب "إعلانات Google" إمكانية الوصول إلى بيانات المنتجات والحساب اللازمة لتنفيذ الحملات الإعلانية. مقدّم الخدمة في هذه الحالة هو GOOGLE_ADS، وexternalAccountId هو رقم تعريف حساب "إعلانات Google". يمكن أيضًا اقتراح هذه الخدمة على حساب حالي.

  • مقارنة الأسعار: يمثّل هذا الخيار العلاقة مع خدمة مقارنة أسعار (CSS) تدير حساب Merchant Center.

  • إدارة بيانات المتجر المحلية: تمثّل هذه السمة العلاقة مع مدير متجر لإدارة المخزون المحلي وبيانات المتجر باستخدام "الملف التجاري على Google".

  • إدارة الحساب: تتيح هذه الخدمة لمقدّم الخدمة تنفيذ إجراءات إدارية على حساب Merchant Center، مثل ضبط إعدادات الحساب أو إدارة المستخدمين أو تعديل معلومات النشاط التجاري. يمكن للنشاط التجاري أيضًا تقييد إذن الوصول الممنوح. عند استخدام هذه الخدمة أثناء إنشاء الحساب، يتم إنشاء حساب مرتبط بمقدّم الخدمة، وهو الأسلوب المقترَح لمنصات التجارة الإلكترونية وشركاء القنوات. يمكن أيضًا اقتراحها لحساب حالي.

  • إدارة المنتجات: تتيح هذه الخدمة للموفّرين إدارة المنتجات والميزات ذات الصلة، مثل مصادر البيانات والقواعد. عند إضافتها أثناء إنشاء الحساب، يتم ذلك عادةً مع accountManagement أو accountAggregation. يمكن أيضًا اقتراح هذه الخدمة على حساب حالي.

مصافحة

لإنشاء خدمة، يجب أن يمنح كل من الحساب الذي يقدّم الخدمة والحساب الذي يتلقّى الخدمة الإذن بالربط. تُعرف عملية التفويض هذه باسم المصافحة.

تتألف المصافحة من خطوتَين:

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

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 الكاملة.

  • إدارة الحملات: تقدّم هذه الخدمة إذن وصول محدودًا، ما يتيح لحساب "إعلانات Google" المرتبط الوصول إلى المنتجات ومعلومات الحساب الأساسية.

  • مقارنة الأسعار: توفّر هذه الخدمة تلقائيًا حقوق ADMIN الكاملة. ومع ذلك، يمكن للنشاط التجاري تقييد إذن الوصول الممنوح في Merchant Center.

  • إدارة البطاقات المحلية: لا تمنح هذه الخدمة أي حق وصول مباشر. بدلاً من ذلك، يتيح هذا الخيار للمنتجات في البيانات المزامنة مع حساب Merchant Center.

ملاحظة مهمة: تنطبق حقوق الوصول الموضّحة لأنواع الخدمات التالية على مقدّمي الخدمات المعتمَدين فقط. يُرجى التواصل مع فريق الدعم إذا كنت مقدّم خدمة وتريد الاستفادة من هذه الإمكانية. إذا سبق أن تمت الموافقة على استخدامك الطريقة accounts.link لإدارة المنتجات في Content API for Shopping، يمكنك استخدام هذه الخدمة في Merchant API بدون الحاجة إلى موافقات إضافية.

  • إدارة الحساب: تمنح هذه الخدمة تلقائيًا حقوق ADMIN كاملة.

  • إدارة المنتجات: تمنحك هذه الخدمة حقوق ADMIN كاملة. يُرجى العِلم أنّ هذا الإذن سيقتصر في المستقبل على حقوق الوصول المرتبطة بالمنتجات فقط.

كيفية تطبيق العلاقات على المنصات التابعة لجهات خارجية

إذا كنت منصة تابعة لجهة خارجية تدير حسابات نيابةً عن مؤسسات أخرى، يوضّح ما يلي كيفية ربط المفاهيم المختلفة ببنية حسابك:

  1. مقدّم الخدمة: الحساب المتقدّم
  2. الحساب الذي يتلقّى الخدمة: هو حساب على Merchant Center يمثّل النشاط التجاري الذي تديره.
  3. الخدمة:
    • ‫accountManagement: هذه هي الخدمة المقترَحة لمنصات التجارة الإلكترونية وشركاء القنوات الذين ينشئون حسابات جديدة نيابةً عن التجّار. ويتم إنشاء حساب يملكه التاجر ويكون مرتبطًا بك لإدارته. يتوافق ذلك مع بنية Merchant Center المفضّلة لحالة الاستخدام هذه.
    • accountAggregation: تربط هذه الخدمة حسابك بامتيازات متقدّمة بحساب آخر. على الرغم من أنّ هذه الميزة متاحة، لا ننصح بها لمنصات التجارة الإلكترونية وشركاء القنوات.

للحصول على تفاصيل حول كيفية إعداد حساب متقدّم والربط بحسابات Merchant Center جديدة، يُرجى الاطّلاع على إنشاء حسابات.

السابق
Create accounts
التالي
Control access to your account