تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

إدارة الإعدادات المفضّلة للإشعارات عبر البريد الإلكتروني لحسابات Merchant Center

يشرح هذا الدليل كيفية إدارة الإعدادات المفضّلة للإشعارات عبر البريد الإلكتروني لحسابك على Merchant Center للرسائل الإلكترونية غير الإلزامية باستخدام Merchant API.

تكون الإعدادات المفضّلة للبريد الإلكتروني خاصة بكل حساب على Merchant Center لديك إذن وصول إليه. إذا كنت تدير حسابات متعددة، يمكنك ضبط إعدادات مفضّلة مختلفة لكل حساب. تتيح لك واجهة برمجة التطبيقات Merchant API استرداد إعداداتك الحالية و تعديلها. لمزيد من المعلومات عن إدارة الإعدادات المفضّلة للبريد الإلكتروني من خلال واجهة Merchant Center، يُرجى الاطّلاع على مقالة تغيير الإعدادات المفضّلة للبريد الإلكتروني في Merchant Center.

لا تتيح Merchant API إدارة الإعدادات المفضّلة للرسائل الإلكترونية "أخبار ونصائح" فقط.

اعتبارات خاصة

المستخدم الذي تمّت مصادقة هويته فقط: يمكنك الحصول على الإعدادات المفضّلة للبريد الإلكتروني أو تعديلها فقط لحساب المستخدم الذي تمّت مصادقة هويته لطلب البيانات من واجهة برمجة التطبيقات. يجب تحديد عنوان البريد الإلكتروني لهذا المستخدم في مسار الطلب (على سبيل المثال، user@email.com) أو استخدام الاسم المعرِّف me.
الحسابات المتقدّمة: إذا كنت تستخدم حسابًا متقدّمًا، يتم ضبط إعدادات البريد الإلكتروني المفضّلة على مستوى الحساب المتقدّم وتنطبق على الحساب المتقدّم نفسه وجميع حساباته الفرعية. عند استخدام واجهة برمجة التطبيقات، على مستخدمي الحسابات المتقدّمة تحديد رقم تعريف الحساب المتقدّم لإدارة إعداداتهم المفضّلة.
حسابات الخدمة: لا تتلقّى حسابات الخدمة إشعارات حتى إذا تم ضبط الإعدادات المفضّلة للبريد الإلكتروني لها.
حالة UNCONFIRMED: لا يمكن سوى للخادم ضبط حالة الموافقة على UNCONFIRMED لإعدادات البريد الإلكتروني المفضّلة. لا يمكنك ضبط الإعداد المفضّل على UNCONFIRMED باستخدام واجهة برمجة التطبيقات. تؤدي محاولة ضبط هذه الإعدادات المفضّلة إلى ظهور خطأ. تشير الحالة UNCONFIRMED إلى أنّه تم إرسال رسالة تأكيد إلكترونية إلى مستخدم وافق على الميزة، ولكنّه لم ينقر بعد على رابط التأكيد.

الاطّلاع على إعدادات البريد الإلكتروني المفضّلة في Merchant Center

للاطّلاع على إعدادات الإشعارات الحالية عبر البريد الإلكتروني لحساب معيّن على Merchant Center، استخدِم الطريقة التالية: GetEmailPreferences. عليك تقديم رقم تعريف حسابك على Merchant Center واستخدام عنوان البريد الإلكتروني للمستخدم أو استخدام الاسم المعرِّف me للإشارة إلى المستخدِم الذي تم مصادقة هويته.

يسترجع هذا الطلب المرجع EmailPreferences الذي يعرض حالة تفعيلك لفئات الإشعارات المتاحة، مثل news_and_tips.

GET https://merchantapi.googleapis.com/accounts/v1beta/accounts/{ACCOUNT_ID}/users/{EMAIL_ADDRESS}/emailPreferences

يعرض الطلب الناجح المرجع EmailPreferences الذي يعرض إعداداتك الحالية.

نموذج الردّ:

{
  "name": "accounts/{ACCOUNT_ID}/users/{EMAIL_ADDRESS}/emailPreferences",
  "news_and_tips": "OPTED_IN"
}

يوضّح نموذج الرمز البرمجي هذا كيفية استرداد الإعدادات المفضّلة للبريد الإلكتروني لحسابك على Merchant Center.

Java

import com.google.api.gax.core.FixedCredentialsProvider;
import com.google.auth.oauth2.GoogleCredentials;
import com.google.shopping.merchant.accounts.v1beta.EmailPreferences;
import com.google.shopping.merchant.accounts.v1beta.EmailPreferencesName;
import com.google.shopping.merchant.accounts.v1beta.EmailPreferencesServiceClient;
import com.google.shopping.merchant.accounts.v1beta.EmailPreferencesServiceSettings;
import com.google.shopping.merchant.accounts.v1beta.GetEmailPreferencesRequest;
import shopping.merchant.samples.utils.Authenticator;
import shopping.merchant.samples.utils.Config;

/** This class demonstrates how to get the email preferences of a Merchant Center account. */
public class GetEmailPreferencesSample {

  public static void getEmailPreferences(Config config, String email) throws Exception {

    // Obtains OAuth token based on the user's configuration.
    GoogleCredentials credential = new Authenticator().authenticate();

    // Creates service settings using the credentials retrieved above.
    EmailPreferencesServiceSettings emailPreferencesServiceSettings =
        EmailPreferencesServiceSettings.newBuilder()
            .setCredentialsProvider(FixedCredentialsProvider.create(credential))
            .build();

    // Creates EmailPreferences name to identify the EmailPreferences.
    String name =
        EmailPreferencesName.newBuilder()
            .setAccount(config.getAccountId().toString())
            .setEmail(email)
            .build()
            .toString();

    // Calls the API and catches and prints any network failures/errors.
    try (EmailPreferencesServiceClient emailPreferencesServiceClient =
        EmailPreferencesServiceClient.create(emailPreferencesServiceSettings)) {

      // The name has the format: accounts/{account}/users/{user}/emailPreferences
      GetEmailPreferencesRequest request =
          GetEmailPreferencesRequest.newBuilder().setName(name).build();

      System.out.println("Sending get EmailPreferences request:");
      EmailPreferences response = emailPreferencesServiceClient.getEmailPreferences(request);

      System.out.println("Retrieved EmailPreferences below");
      System.out.println(response);
    } catch (Exception e) {
      System.out.println(e);
    }
  }

  public static void main(String[] args) throws Exception {
    Config config = Config.load();
    // The email address of this user. If you want to get the user information
    // Of the user making the Content API request, you can also use "me" instead
    // Of an email address.
    String email = "testUser@gmail.com";
    // String email = "me";

    getEmailPreferences(config, email);
  }
}GetEmailPreferencesSample.java

PHP

use Google\ApiCore\ApiException;
use Google\Shopping\Merchant\Accounts\V1beta\Client\EmailPreferencesServiceClient;
use Google\Shopping\Merchant\Accounts\V1beta\GetEmailPreferencesRequest;

/**
 * This class demonstrates how to get the email preferences of a Merchant Center account.
 */
class GetEmailPreferences
{
    /**
     * Gets the email preferences of a Merchant Center account.
     *
     * @param array $config
     *      The configuration data used for authentication and getting the acccount ID.
     * @param string $email The email address of this user. If you want to get the user information
     *      of the user making the Merchant API request, you can also use "me" instead
     *      of an email address.
     *
     * @return void
     */
    public static function getEmailPreferencesSample($config, $email): void
    {
        // Gets the OAuth credentials to make the request.
        $credentials = Authentication::useServiceAccountOrTokenFile();

        // Creates options config containing credentials for the client to use.
        $options = ['credentials' => $credentials];

        // Creates a client.
        $emailPreferencesServiceClient = new EmailPreferencesServiceClient($options);

        // Creates EmailPreferences name to identify the EmailPreferences.
        // The name has the format: accounts/{account}/users/{user}/emailPreferences
        $name = "accounts/" . $config['accountId'] . "/users/" . $email . "/emailPreferences";

        // Calls the API and catches and prints any network failures/errors.
        try {
            $request = (new GetEmailPreferencesRequest())
                ->setName($name);

            print "Sending get EmailPreferences request:\n";
            $response = $emailPreferencesServiceClient->getEmailPreferences($request);

            print "Retrieved EmailPreferences below\n";
            print_r($response);
        } catch (ApiException $e) {
            print $e->getMessage();
        }
    }

    /**
     * Helper to execute the sample.
     *
     * @return void
     */
    public function callSample(): void
    {
        $config = Config::generateConfig();
        // The email address of this user. If you want to get the user information
        // Of the user making the Merchant API request, you can also use "me" instead
        // Of an email address.
        // $email = "testUser@gmail.com";
        $email = "me";

        self::getEmailPreferencesSample($config, $email);
    }
}

// Run the script
$sample = new GetEmailPreferences();
$sample->callSample();GetEmailPreferencesSample.php

Python

from examples.authentication import configuration
from examples.authentication import generate_user_credentials
from google.shopping.merchant_accounts_v1beta import EmailPreferencesServiceClient
from google.shopping.merchant_accounts_v1beta import GetEmailPreferencesRequest

_ACCOUNT = configuration.Configuration().read_merchant_info()


def get_email_preferences(email_address):
  """Gets the email preferences of a Merchant Center account."""

  # Gets OAuth Credentials.
  credentials = generate_user_credentials.main()

  # Creates a client.
  client = EmailPreferencesServiceClient(credentials=credentials)

  # Creates EmailPreferences name to identify the EmailPreferences.
  name = (
      "accounts/" + _ACCOUNT + "/users/" + email_address + "/emailPreferences"
  )

  # Creates the request.
  request = GetEmailPreferencesRequest(name=name)

  # Makes the request and catches and prints any error messages.
  try:
    response = client.get_email_preferences(request=request)
    print("Retrieved EmailPreferences below")
    print(response)
  except RuntimeError as e:
    print(e)


if __name__ == "__main__":
  # The email address of this user. If you want to get the user information
  # Of the user making the Content API request, you can also use "me" instead
  # Of an email address.
  # email = "testUser@gmail.com"
  email = "me"

  get_email_preferences(email)
get_email_preferences_sample.py

cURL

curl --location \
'https://merchantapi.googleapis.com/accounts/v1beta/accounts/{ACCOUNT_ID}/users/{EMAIL_ADDRESS}/emailPreferences' \
--header 'Authorization: Bearer <API_TOKEN>'

تغيير إعدادات البريد الإلكتروني المفضّلة في Merchant Center

لتغيير الإعدادات المفضّلة للإشعارات عبر البريد الإلكتروني، مثل تفعيل رسائل "أخبار ونصائح" الإلكترونية أو إيقافها، استخدِم الخطوات التالية: UpdateEmailPreferences.

في طلبك، عليك تقديم معرّف حساب Merchant Center واستخدام عنوان بريدك الإلكتروني (أو الاسم المعرِّف me) لعنوان بريد المستخدم الإلكتروني. يجب أن يحتوي نص الطلب على العنصر EmailPreferences مع القيمة opt_in_state المحدّدة للحقل news_and_tips. يجب تحديد news_and_tips أيضًا في مَعلمة طلب البحث update_mask للإشارة إلى الإعداد المفضّل الذي يتم تغييره.

يؤدي هذا الإجراء إلى تعديل الإعدادات المفضّلة للبريد الإلكتروني للمستخدم الذي تمّت مصادقة هويته في حساب Merchant Center المحدّد. على سبيل المثال، يؤدي ضبط الإعداد news_and_tips على OPTED_OUT إلى إيقاف تلقّي الرسائل الإلكترونية "الأخبار والنصائح" لهذا الحساب.

PATCH https://merchantapi.googleapis.com/accounts/v1beta/accounts/{ACCOUNT_ID}/users/{EMAIL_ADDRESS}/emailPreferences?update_mask=news_and_tips

نموذج الحمولة للطلب (إيقاف ميزة "أخبار ونصائح"):

{
  "name": "accounts/{ACCOUNT_ID}/users/{EMAIL_ADDRESS}/emailPreferences",
  "news_and_tips": "OPTED_OUT"
}

يعرض الطلب الناجح مورد EmailPreferences المعدَّل.

نموذج الردّ:

{
  "name": "accounts/{ACCOUNT_ID}/users/{EMAIL_ADDRESS}/emailPreferences",
  "news_and_tips": "OPTED_OUT"
}

يوضّح نموذج الرمز البرمجي هذا كيفية تعديل الإعدادات المفضّلة للبريد الإلكتروني في حسابك على Merchant Center، على سبيل المثال لتفعيل رسائل "الأخبار والنصائح" الإلكترونية.

Java

import com.google.api.gax.core.FixedCredentialsProvider;
import com.google.auth.oauth2.GoogleCredentials;
import com.google.protobuf.FieldMask;
import com.google.shopping.merchant.accounts.v1beta.EmailPreferences;
import com.google.shopping.merchant.accounts.v1beta.EmailPreferences.OptInState;
import com.google.shopping.merchant.accounts.v1beta.EmailPreferencesName;
import com.google.shopping.merchant.accounts.v1beta.EmailPreferencesServiceClient;
import com.google.shopping.merchant.accounts.v1beta.EmailPreferencesServiceSettings;
import com.google.shopping.merchant.accounts.v1beta.UpdateEmailPreferencesRequest;
import shopping.merchant.samples.utils.Authenticator;
import shopping.merchant.samples.utils.Config;

/**
 * This class demonstrates how to update a EmailPreferences to OPT_IN to News and Tips. This service
 * only permits retrieving and updating email preferences for the authenticated user.
 */
public class UpdateEmailPreferencesSample {

  public static void updateEmailPreferences(Config config, String email) throws Exception {

    GoogleCredentials credential = new Authenticator().authenticate();

    EmailPreferencesServiceSettings emailPreferencesServiceSettings =
        EmailPreferencesServiceSettings.newBuilder()
            .setCredentialsProvider(FixedCredentialsProvider.create(credential))
            .build();

    // Creates EmailPreferences name to identify EmailPreferences.
    String name =
        EmailPreferencesName.newBuilder()
            .setAccount(config.getAccountId().toString())
            .setEmail(email)
            .build()
            .toString();

    // Create a EmailPreferences with the updated fields.
    EmailPreferences emailPreferences =
        EmailPreferences.newBuilder().setName(name).setNewsAndTips(OptInState.OPTED_IN).build();

    FieldMask fieldMask = FieldMask.newBuilder().addPaths("news_and_tips").build();

    try (EmailPreferencesServiceClient emailPreferencesServiceClient =
        EmailPreferencesServiceClient.create(emailPreferencesServiceSettings)) {

      UpdateEmailPreferencesRequest request =
          UpdateEmailPreferencesRequest.newBuilder()
              .setEmailPreferences(emailPreferences)
              .setUpdateMask(fieldMask)
              .build();

      System.out.println("Sending Update EmailPreferences request");
      EmailPreferences response = emailPreferencesServiceClient.updateEmailPreferences(request);
      System.out.println("Updated EmailPreferences Name below");
      System.out.println(response.getName());
    } catch (Exception e) {
      System.out.println(e);
    }
  }

  public static void main(String[] args) throws Exception {
    Config config = Config.load();
    // The email address of this user. If you want to get the user information
    // Of the user making the Content API request, you can also use "me" instead
    // Of an email address.
    // String email = "testUser@gmail.com";
    String email = "me";

    updateEmailPreferences(config, email);
  }
}UpdateEmailPreferencesSample.java

PHP

use Google\ApiCore\ApiException;
use Google\Protobuf\FieldMask;
use Google\Shopping\Merchant\Accounts\V1beta\Client\EmailPreferencesServiceClient;
use Google\Shopping\Merchant\Accounts\V1beta\EmailPreferences;
use Google\Shopping\Merchant\Accounts\V1beta\EmailPreferences\OptInState;
use Google\Shopping\Merchant\Accounts\V1beta\UpdateEmailPreferencesRequest;

/**
 * This class demonstrates how to update a EmailPreferences to OPT_IN to News and Tips. This service
 * only permits retrieving and updating email preferences for the authenticated user.
 */
class UpdateEmailPreferences
{

    /**
     * Updates email preferences to OPT_IN to News and Tips.
     *
     * @param array $config
     *      The configuration data used for authentication and getting the acccount ID.
     * @param string $email The email address of this user. If you want to get the user information
     *      of the user making the Merchant API request, you can also use "me" instead
     *      of an email address.
     *
     * @return void
     */
    public static function updateEmailPreferencesSample($config, $email): void
    {
        // Gets the OAuth credentials to make the request.
        $credentials = Authentication::useServiceAccountOrTokenFile();

        // Creates options config containing credentials for the client to use.
        $options = ['credentials' => $credentials];

        // Creates a client.
        $emailPreferencesServiceClient = new EmailPreferencesServiceClient($options);

        // Creates EmailPreferences name to identify the EmailPreferences.
        // The name has the format: accounts/{account}/users/{user}/emailPreferences
        $name = "accounts/" . $config['accountId'] . "/users/" . $email . "/emailPreferences";

        // Create a EmailPreferences with the updated fields.
        $emailPreferences = (new EmailPreferences())
            ->setName($name)
            ->setNewsAndTips(OptInState::OPTED_OUT);

        $fieldMask = (new FieldMask())
            ->setPaths(['news_and_tips']);

        try {
            $request = (new UpdateEmailPreferencesRequest())
                ->setEmailPreferences($emailPreferences)
                ->setUpdateMask($fieldMask);

            print "Sending Update EmailPreferences request\n";
            $response = $emailPreferencesServiceClient->updateEmailPreferences($request);
            print "Updated EmailPreferences Name below\n";
            print $response->getName() . "\n";
        } catch (ApiException $e) {
            print $e->getMessage();
        }
    }

    /**
     * Helper to execute the sample.
     *
     * @return void
     */
    public function callSample(): void
    {
        $config = Config::generateConfig();
        // The email address of this user. If you want to get the user information
        // Of the user making the Merchant API request, you can also use "me" instead
        // Of an email address.
        // $email = "testUser@gmail.com";
        $email = "me";

        self::updateEmailPreferencesSample($config, $email);
    }
}

// Run the script
$sample = new UpdateEmailPreferences();
$sample->callSample();UpdateEmailPreferencesSample.php

Python

from examples.authentication import configuration
from examples.authentication import generate_user_credentials
from google.protobuf import field_mask_pb2
from google.shopping.merchant_accounts_v1beta import EmailPreferences
from google.shopping.merchant_accounts_v1beta import EmailPreferencesServiceClient
from google.shopping.merchant_accounts_v1beta import UpdateEmailPreferencesRequest


FieldMask = field_mask_pb2.FieldMask
_ACCOUNT = configuration.Configuration().read_merchant_info()


def update_email_preferences(email_address):
  """Updates a EmailPreferences to OPT_IN to News and Tips."""

  # Gets OAuth Credentials.
  credentials = generate_user_credentials.main()

  # Creates a client.
  client = EmailPreferencesServiceClient(credentials=credentials)

  # Creates EmailPreferences name to identify EmailPreferences.
  name = (
      "accounts/" + _ACCOUNT + "/users/" + email_address + "/emailPreferences"
  )

  # Create a EmailPreferences with the updated fields.
  email_preferences = EmailPreferences(
      name=name, news_and_tips=EmailPreferences.OptInState.OPTED_IN
  )

  # Create field mask
  field_mask = FieldMask(paths=["news_and_tips"])

  # Creates the request.
  request = UpdateEmailPreferencesRequest(
      email_preferences=email_preferences, update_mask=field_mask
  )

  # Makes the request and catches and prints any error messages.
  try:
    response = client.update_email_preferences(request=request)
    print("Updated EmailPreferences Name below")
    print(response.name)
  except RuntimeError as e:
    print(e)


if __name__ == "__main__":
  # The email address of this user. If you want to get the user information
  # of the user making the Content API request, you can also use "me" instead
  # of an email address.
  # email = "testUser@gmail.com"
  email = "me"

  update_email_preferences(email)
update_email_preferences_sample.py

cURL

curl --location --request PATCH \
'https://merchantapi.googleapis.com/accounts/v1beta/accounts/{ACCOUNT_ID}/users/{EMAIL_ADDRESS}/emailPreferences?update_mask=news_and_tips' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API_TOKEN>' \
--data '{
  "name": "accounts/{ACCOUNT_ID}/users/{EMAIL_ADDRESS}/emailPreferences",
  "news_and_tips": "OPTED_IN"
}'

Enable automatic improvements

Create and update regions

إدارة الإعدادات المفضّلة للإشعارات عبر البريد الإلكتروني لحسابات Merchant Center تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

اعتبارات خاصة

الاطّلاع على إعدادات البريد الإلكتروني المفضّلة في Merchant Center

Java

PHP

Python

cURL

تغيير إعدادات البريد الإلكتروني المفضّلة في Merchant Center

Java

PHP

Python

cURL

إدارة الإعدادات المفضّلة للإشعارات عبر البريد الإلكتروني لحسابات Merchant Center