Hướng dẫn này giải thích cách quản lý lựa chọn ưu tiên về thông báo qua email của tài khoản Merchant Center đối với các email không bắt buộc bằng cách sử dụng Merchant API.
Lựa chọn ưu tiên về email dành riêng cho từng tài khoản Merchant Center mà bạn có quyền truy cập. Nếu quản lý nhiều tài khoản, bạn có thể thiết lập các lựa chọn ưu tiên khác nhau cho từng tài khoản. Merchant API cho phép bạn truy xuất và cập nhật chế độ cài đặt hiện tại. Để biết thêm thông tin về cách quản lý lựa chọn ưu tiên về email thông qua giao diện Merchant Center, hãy xem bài viết Thay đổi lựa chọn ưu tiên về email trong Merchant Center.
Merchant API chỉ hỗ trợ quản lý lựa chọn ưu tiên cho email "Tin tức và mẹo".
Những điểm cần cân nhắc đặc biệt
- Chỉ người dùng đã xác thực: Bạn chỉ có thể lấy hoặc cập nhật lựa chọn ưu tiên về email cho tài khoản người dùng đã được xác thực cho lệnh gọi API. Bạn phải chỉ định địa chỉ email của người dùng này trong đường dẫn yêu cầu (ví dụ:
user@email.com) hoặc sử dụng bí danhme. - Tài khoản nâng cao: Nếu bạn là người dùng tài khoản nâng cao, thì lựa chọn ưu tiên về email của bạn sẽ được đặt ở cấp tài khoản nâng cao và áp dụng cho chính tài khoản nâng cao đó cũng như tất cả tài khoản phụ của tài khoản nâng cao. Khi sử dụng API, người dùng tài khoản nâng cao nên chỉ định mã tài khoản nâng cao để quản lý các lựa chọn ưu tiên của họ.
- Tài khoản dịch vụ: Tài khoản dịch vụ không nhận được thông báo ngay cả khi bạn đặt lựa chọn ưu tiên về email cho các tài khoản đó.
- Trạng thái
UNCONFIRMED: Chỉ máy chủ mới có thể đặt trạng thái chọn tham giaUNCONFIRMEDcho một tuỳ chọn email. Bạn không thể đặt tuỳ chọn thànhUNCONFIRMEDbằng API. Nếu cố gắng đặt lựa chọn ưu tiên này, bạn sẽ gặp lỗi. Trạng tháiUNCONFIRMEDcho biết email xác nhận đã được gửi đến một người dùng đã chọn sử dụng, nhưng họ chưa nhấp vào đường liên kết xác nhận.
Kiểm tra lựa chọn ưu tiên về email trên Merchant Center
Để xem chế độ cài đặt thông báo qua email hiện tại cho một tài khoản Merchant Center cụ thể, hãy sử dụng phương thức GetEmailPreferences. Bạn cần cung cấp mã tài khoản Merchant Center và sử dụng địa chỉ email của người dùng hoặc sử dụng bí danh me để cho biết người dùng đã được xác thực.
Yêu cầu này truy xuất tài nguyên EmailPreferences. Tài nguyên này cho biết trạng thái chọn sử dụng của bạn đối với các danh mục thông báo hiện có, chẳng hạn như news_and_tips.
GET https://merchantapi.googleapis.com/accounts/v1beta/accounts/{ACCOUNT_ID}/users/{EMAIL_ADDRESS}/emailPreferences
Yêu cầu thành công sẽ trả về tài nguyên EmailPreferences cho biết các chế độ cài đặt hiện tại của bạn.
Câu trả lời mẫu:
{
"name": "accounts/{ACCOUNT_ID}/users/{EMAIL_ADDRESS}/emailPreferences",
"news_and_tips": "OPTED_IN"
}
Mẫu mã này cho biết cách truy xuất lựa chọn ưu tiên về email cho tài khoản 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);
}
}
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();
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)
cURL
curl --location \
'https://merchantapi.googleapis.com/accounts/v1beta/accounts/{ACCOUNT_ID}/users/{EMAIL_ADDRESS}/emailPreferences' \
--header 'Authorization: Bearer <API_TOKEN>'
Thay đổi lựa chọn ưu tiên về email trên Merchant Center
Để thay đổi lựa chọn ưu tiên về thông báo qua email, chẳng hạn như chọn nhận hoặc không nhận email "Tin tức và mẹo", hãy sử dụng phương thức UpdateEmailPreferences.
Trong yêu cầu, bạn sẽ cung cấp mã tài khoản Merchant Center và sử dụng địa chỉ email của mình (hoặc bí danh me) cho email của người dùng. Nội dung yêu cầu phải chứa đối tượng EmailPreferences với opt_in_state đã chọn cho trường news_and_tips. Bạn cũng phải chỉ định news_and_tips trong tham số truy vấn update_mask để cho biết bạn đang thay đổi lựa chọn ưu tiên nào.
Thao tác này sẽ cập nhật lựa chọn ưu tiên về email cho người dùng đã xác thực cho tài khoản Merchant Center đã chỉ định. Ví dụ: việc đặt news_and_tips thành OPTED_OUT sẽ khiến bạn không nhận được email "Mẹo và tin tức" cho tài khoản đó.
PATCH https://merchantapi.googleapis.com/accounts/v1beta/accounts/{ACCOUNT_ID}/users/{EMAIL_ADDRESS}/emailPreferences?update_mask=news_and_tips
Trọng tải yêu cầu mẫu (để chọn không nhận "Tin tức và mẹo"):
{
"name": "accounts/{ACCOUNT_ID}/users/{EMAIL_ADDRESS}/emailPreferences",
"news_and_tips": "OPTED_OUT"
}
Yêu cầu thành công sẽ trả về tài nguyên EmailPreferences đã cập nhật.
Câu trả lời mẫu:
{
"name": "accounts/{ACCOUNT_ID}/users/{EMAIL_ADDRESS}/emailPreferences",
"news_and_tips": "OPTED_OUT"
}
Mẫu mã này cho biết cách cập nhật lựa chọn ưu tiên về email cho tài khoản Merchant Center, ví dụ: chọn nhận email "Tin tức và mẹo".
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);
}
}
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();
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)
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"
}'