Thành phần địa điểm

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

  1. Tạo một bộ thành phần đồng bộ hoá vị trí.
  2. Đí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

  1. Tạo AssetSet mới.
    1. Đặt type thành LOCATION_SYNC.
    2. Đặt location_set thành LocationSet mới.
  2. Trong LocationSet mới,

    1. Đặt location_ownership_type dựa trên trường hợp sử dụng của bạn:
      • Đặt thành BUSINESS_OWNER nếu bạn sở hữu địa điểm doanh nghiệp.
      • Đặt thành AFFILIATE nế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 đó.
    2. Đặt trường source oneof dựa trên trường hợp sử dụng của bạn:

      • Đặt business_profile_location_set nế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ường http_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_address của BusinessProfileLocationSet.
        • 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.

      • Đặt chain_location_set nếu bạn muốn đồng bộ hoá với các vị trí trong mã chuỗi được chỉ định.

      • Đặt maps_location_set nếu bạn muốn thêm vị trí theo cách thủ công bằng Mã địa điểm.

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.

  1. 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.
  2. Đí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.
  3. (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.

  1. 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.
  2. 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;
  }
}