Không giống như các thành phần khác, thành phần địa điểm được Google Ads API tự động tạo sau khi bạn tạo một bộ thành phần. Trước tiên, hãy tạo một bộ thành phần đồng bộ hoá địa điểm và đính kèm bộ đó vào khách hàng. Sau đó, nếu bạn cần chọn một số thành phần vị trí trong bộ thành phần cho một chiến dịch hoặc nhóm quảng cáo, hãy tạo một bộ thành phần nhóm vị trí rồi đính kèm bộ thành phần đó vào chiến dịch hoặc nhóm quảng cáo.
Tạo một bộ thành phần đồng bộ hoá địa điểm và đính kèm bộ đó vào khách hàng
- Tạo một bộ thành phần đồng bộ hoá vị trí.
- Đính kèm đối tượng đó vào một khách hàng bằng cách sử dụng
CustomerAssetSetService.
Tạo một bộ thành phần đồng bộ hoá địa điểm
- Tạo
AssetSetmới.- Đặt
typethànhLOCATION_SYNC. - Đặt
location_setthànhLocationSetmới.
- Đặt
Trong
LocationSetmới,- Đặt
location_ownership_typedựa trên trường hợp sử dụng của bạn:- Đặt thành
BUSINESS_OWNERnếu bạn sở hữu địa điểm doanh nghiệp. - Đặt thành
AFFILIATEnếu bạn không sở hữu địa điểm kinh doanh nhưng bán sản phẩm của mình tại đó.
- Đặt thành
Đặt trường
sourceoneof dựa trên trường hợp sử dụng của bạn:Đặt
business_profile_location_setnếu bạn muốn đồng bộ hoá với các vị trí trong tài khoản Trang doanh nghiệp trên Google.Khi tạo
BusinessProfileLocationSetđể liên kết Google Ads với tài khoản Trang doanh nghiệp trên Google, bạn phải cung cấp mã truy cập OAuth 2.0 trong trườnghttp_authorization_token. Mã thông báo này đóng vai trò là bằng chứng cho thấy bạn đang cho phép Google Ads truy cập vào dữ liệu vị trí từ Trang doanh nghiệp trên Google được chỉ định.Mã thông báo phải đáp ứng các yêu cầu sau:
- Mã thông báo này phải được tạo cho Tài khoản Google (tài khoản người dùng hoặc tài khoản dịch vụ) có địa chỉ email được cung cấp trong trường
email_addresscủaBusinessProfileLocationSet. - Tài khoản này phải có đủ quyền để đọc các địa điểm kinh doanh trong Trang doanh nghiệp trên Google.
- Bạn phải lấy mã thông báo OAuth 2.0 bằng phạm vi
https://www.googleapis.com/auth/business.manage.
Để biết hướng dẫn chi tiết về cách tạo mã truy cập OAuth 2.0, hãy tham khảo bài viết Sử dụng OAuth 2.0 để truy cập vào các API của Google.
- Mã thông báo này phải được tạo cho Tài khoản Google (tài khoản người dùng hoặc tài khoản dịch vụ) có địa chỉ email được cung cấp trong trường
Đặt
chain_location_setnếu bạn muốn đồng bộ hoá với các vị trí trong mã chuỗi được chỉ định.Đặt
maps_location_setnếu bạn muốn thêm vị trí theo cách thủ công bằng Mã địa điểm.
- Đặt
Sau khi bạn hoàn tất các bước này, Google Ads API sẽ tạo thành phần địa điểm và thêm các thành phần đó vào bộ thành phần đồng bộ hoá địa điểm đã tạo cho bạn, tương tự như khi bạn thực hiện theo cách thủ công bằng AssetSetAssetService. Bạn không cần phải
thao tác với các thành phần này, trừ phi bạn muốn thêm chúng vào một bộ thành phần
nhóm địa điểm tĩnh theo cách thủ công.
Mỗi khách hàng chỉ có thể có một bộ thành phần đồng bộ hoá địa điểm đang hoạt động có status được đặt thành ENABLED. Nếu bạn cần tạo một loại bộ thành phần đồng bộ hoá địa điểm khác, hãy xoá bộ thành phần hiện có trước.
Đính kèm bộ thành phần đồng bộ hoá vị trí cho một khách hàng
Sử dụng CustomerAssetSetService.MutateCustomerAssetSets để đính kèm bộ thành phần đồng bộ hoá địa điểm đã đặt trong phần trước vào khách hàng của bạn.
(Không bắt buộc) Tạo một bộ thành phần nhóm vị trí và đính kèm bộ đó vào một chiến dịch hoặc nhóm quảng cáo
Bạn chỉ cần có một bộ thành phần nhóm vị trí nếu cần chọn một nhóm nhỏ thành phần vị trí. Điều này là do chiến dịch và nhóm quảng cáo kế thừa thành phần địa điểm từ cấp khách hàng.
Bộ thành phần nhóm vị trí chứa một nhóm nhỏ các thành phần vị trí của bộ thành phần đồng bộ hoá địa điểm. Bạn có thể linh động tạo một bộ thành phần nhóm vị trí bằng cách tận dụng một số tính năng của Trang doanh nghiệp trên Google (như lọc theo nhãn) hoặc mã chuỗi cửa hàng và địa điểm của chuỗi cửa hàng. Ngoài ra, bạn có thể tạo một bộ thành phần nhóm vị trí theo cách tĩnh.
- Tạo một bộ thành phần nhóm vị trí. Tập hợp thành phần nhóm địa điểm có thể là động hoặc tĩnh.
- Đính kèm bộ thành phần vào một chiến dịch hoặc nhóm quảng cáo, tuỳ theo nhu cầu của bạn.
- (Không bắt buộc) Thêm các thành phần đã tạo trước đó vào bộ thành phần nhóm vị trí tĩnh mới tạo.
Đối với một khách hàng nhất định, bạn có thể tạo nhiều bộ thành phần nhóm vị trí động hoặc tĩnh.
Tạo một nhóm thành phần nhóm địa điểm
Tạo một AssetSet mới và đặt location_group_parent_asset_set_id thành mã nhận dạng của bộ thành phần đồng bộ hoá địa điểm đã tạo trước đó.
Sau đó, hãy đặt một số trường dựa trên việc bạn muốn tạo một bộ thành phần nhóm vị trí động hay tĩnh.
Bộ thành phần linh động
Tuỳ thuộc vào trường bạn đặt trong LocationSet, hãy đặt các trường dựa trên quy tắc sau:
| Nếu bạn đặt trường sau | Sau đó, đặt type thành | Và đặt trường này làm trường asset_set_source oneof |
|---|---|---|
business_profile_location_set |
BUSINESS_PROFILE_DYNAMIC_LOCATION_GROUP |
business_profile_location_group |
chain_location_set |
CHAIN_DYNAMIC_LOCATION_GROUP |
chain_location_group |
Nếu đặt maps_location_set khi tạo bộ thành phần đồng bộ hoá địa điểm, bạn sẽ không thể tạo bộ thành phần nhóm địa điểm linh động. Điều này là do bạn đã thêm địa điểm theo cách thủ công bằng Mã địa điểm
và không có tính năng lọc nào mà bạn có thể sử dụng cho loại địa điểm này.
Bộ thành phần tĩnh
Đặt type thành STATIC_LOCATION_GROUP.
Bạn có thể tạo bộ thành phần nhóm vị trí tĩnh cho mọi loại bộ thành phần đồng bộ hoá vị trí, bất kể bạn đặt trường nào (business_profile_location_set, chain_location_set hoặc maps_location_set) trong LocationSet.
Đối với các bộ thành phần nhóm vị trí tĩnh, bạn cần thêm các thành phần vị trí đã tạo vào bộ thành phần nhóm vị trí theo cách thủ công.
Đính kèm bộ thành phần vào một chiến dịch hoặc nhóm quảng cáo
Sử dụng CampaignAssetSetService.MutateCampaignAssetSets để đính kèm bộ thành phần nhóm vị trí vào chiến dịch của bạn.
Ngoài ra, hãy sử dụng AdGroupAssetSetService.MutateAdGroupAssetSets nếu bạn muốn đính kèm bộ thành phần nhóm vị trí vào một nhóm quảng cáo.
(Không bắt buộc) Thêm thành phần vị trí vào bộ thành phần nhóm vị trí tĩnh
Bạn chỉ phải thực hiện bước này nếu trước đó đã tạo một bộ thành phần nhóm vị trí tĩnh.
- Sử dụng báo cáo
asset_set_assetđể tìm nạp tên tài nguyên của các thành phần được tạo tự động cho bộ thành phần đồng bộ hoá địa điểm đã tạo trước đó. Sử dụng tính năng lọc để chỉ truy xuất những thành phần bạn muốn. - Thêm các địa điểm đó vào bộ thành phần nhóm vị trí tĩnh bằng cách sử dụng
AssetSetAssetService.MutateAssetSetAssets.
Quản lý mã vị trí trên Trang doanh nghiệp
Khi bạn sử dụng business_profile_location_set và lọc theo listing_id_filters được truy xuất từ trang web hoặc API của Trang doanh nghiệp, bạn có thể cần phải chuyển đổi các giá trị số này từ loại uint64 sang int64. Nếu mã của bạn tạo ra lỗi thời gian chạy cho biết mã vị trí trên Trang doanh nghiệp nằm ngoài phạm vi khi thêm mã đó vào trường lặp lại listing_id_filters[], thì có thể bạn cần phải chuyển đổi mã đó bằng cách sử dụng bất kỳ ví dụ nào sau đây:
Java
/**
* Converts the business profile location ID to the format expected by the
* DynamicBusinessProfileLocationGroupFilter.listing_id_filters[] repeated field.
* The business profile location ID is an unsigned 64-bit integer, while the
* listing_id_filters[] field expects signed 64-bit integers. This means that
* for business profile location IDs that are out of range, we must perform the
* two's complement to convert it into a signed int.
*
* @param businessProfileLocationId The ID of a Business Profile location ID.
* @return a Business Profile location ID as a signed 64-bit integer (long).
*/
public static long convertBusinessProfileLocationId(String businessProfileLocationId) {
return Long.parseUnsignedLong(businessProfileLocationId);
}
C#
/// <summary>
/// Converts the business profile location ID to the format expected by the
/// DynamicBusinessProfileLocationGroupFilter.listing_id_filters[] repeated field.
/// The business profile location ID is an unsigned 64-bit integer, while the
/// listing_id_filters[] field expects signed 64-bit integers. This means that
/// for business profile location IDs that are out of range, we must perform the
/// two's complement to convert it into a signed int.
/// </summary>
/// <param name="businessProfileLocationId">The ID of a Business Profile location.</param>
/// <returns>The converted business location ID in signed 64 bit.</returns>
public long ConvertBusinessProfileLocationId(ulong businessProfileLocationId)
{
return unchecked((long)businessProfileLocationId);
}
PHP
/**
* Converts a business profile location ID to a signed 64 bit integer.
*
* Converts the business profile location ID to the format expected by the
* DynamicBusinessProfileLocationGroupFilter.listing_id_filters[] repeated field.
* The business profile location ID is an unsigned 64-bit integer, while the
* listing_id_filters[] field expects signed 64-bit integers. This means that
* for business profile location IDs that are out of range, we must perform the
* two's complement to convert it into a signed int.
*
* @param string $businessProfileLocationId the ID of a Business Profile location
* @return int the converted business location ID in signed 64 bit
*/
public static function convertBusinessProfileLocationId(string $businessProfileLocationId): int
{
$unsignedMax = '18446744073709551615'; // 2^64 - 1
$signedMax = '9223372036854775807'; // 2^63 - 1
// Check if the business profile location ID is within 64 bit range.
// If not, throw an error.
if (bccomp($businessProfileLocationId, '0') < 0 || bccomp($businessProfileLocationId, $unsignedMax) > 0) {
throw new InvalidArgumentException(
'The given business profile location id is outside of the range for a 64 bit integer.'
);
}
// Check if the business profile location ID is in signed 64 bit range.
// If it's not, convert it to its two's complement.
if (bccomp($businessProfileLocationId, $signedMax) > 0) {
// Two's complement: ID - 2^64
return (int) bcsub($businessProfileLocationId, '18446744073709551616');
}
return (int) $businessProfileLocationId;
}
Python
import ctypes
def convert_business_profile_location_id(business_profile_location_id):
"""Converts a business profile location ID to a signed 64 bit integer.
Converts the business profile location ID to the format expected by the
DynamicBusinessProfileLocationGroupFilter.listing_id_filters[] repeated field.
The business profile location ID is an unsigned 64-bit integer, while the
listing_id_filters[] field expects signed 64-bit integers. This means that
for business profile location IDs that are out of range, we must perform the
two's complement to convert it into a signed int.
Args:
business_profile_location_id: the ID of a Business Profile location ID.
Returns:
a Business Profile location ID as a signed 64 bit integer.
"""
# Check if the business profile location ID is within 64 bit range.
# If not, throw an error.
if business_profile_location_id < 0 or business_profile_location_id >= 2 ** 64:
raise ValueError(
"The given business profile location id is outside of the range for a 64 bit integer."
)
# Check if the business profile location ID is in signed 64 bit range.
# If it's not, convert it to its two's complement.
elif business_profile_location_id >= 2 ** 63:
return ctypes.c_int64(business_profile_location_id).value
else:
return business_profile_location_id
Ruby
# Converts the business profile location ID to the format expected by the
# DynamicBusinessProfileLocationGroupFilter.listing_id_filters[] repeated field.
# The business profile location ID is an unsigned 64-bit integer, while the
# listing_id_filters[] field expects signed 64-bit integers. This means that
# for business profile location IDs that are out of range, we must perform the
# two's complement to convert it into a signed int.
# Since Ruby supports arbitrary precision numbers, we have to calculate it
# manually.
LONG_MAX = 2 ** 63
ULONG_MAX = LONG_MAX * 2
def convert_business_profile_location_id(business_profile_location_id)
# Check if the business profile location ID is within 64 bit range.
# If not, throw an error.
if business_profile_location_id < 0 || business_profile_location_id >= 2 ** 64
raise "The given business profile location id is outside of the range for a 64 bit integer."
# Check if the business profile location ID is in signed 64 bit range.
# If it's not, convert it to its two's complement.
elsif business_profile_location_id >= 2**63
-1 * (ULONG_MAX - business_profile_location_id)
else
business_profile_location_id
end
end
Perl
use bigint;
# Converts the business profile location ID to the format expected by the
# DynamicBusinessProfileLocationGroupFilter.listing_id_filters[] repeated field.
# The business profile location ID is an unsigned 64-bit integer, while the
# listing_id_filters[] field expects signed 64-bit integers. This means that
# for business profile location IDs that are out of range, we must perform the
# two's complement to convert it into a signed int.
sub convert_business_profile_location_id {
my ($business_profile_location_id) = @_;
# Check if the business profile location ID is within 64 bit range.
# If not, throw an error.
if ($business_profile_location_id < 0 || $business_profile_location_id >= 2**64) {
die "The given business profile location id is outside of the range for a 64 bit integer";
# Check if the business profile location ID is in signed 64 bit range.
# If it's not, convert it to its two's complement.
} elsif ($business_profile_location_id >= 2**63) {
return -1 * (2**64 - $business_profile_location_id);
} else {
return $business_profile_location_id;
}
}