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ạo tự động 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á vị trí và đính kèm bộ đó vào khách hàng. Sau đó, nếu bạn cần chọn một nhóm nhỏ thành phần địa điểm 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 địa điểm và đí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á vị trí và đính kèm bộ thành phần đó 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 vào khách hàng bằng cách sử dụng CustomerAssetSetService.

Tạo một bộ thành phần đồng bộ hoá vị trí

  1. Tạo AssetSet mới.
    1. Đặt type thành LOCATION_SYNC.
    2. Đặt location_set thành một 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 của doanh nghiệp nhưng bán sản phẩm 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 một BusinessProfileLocationSet để liên kết Google Ads với một 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 đã chỉ định.

        Mã thông báo phải đáp ứng các yêu cầu sau:

        • Khoá 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 của doanh nghiệp 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ã nhận dạng 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 cách sử dụ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 locationassets và thêm các thành phần đó vào bộ thành phần đồng bộ hoá vị trí mà bạn đã tạo, tương tự như khi bạn thực hiện việc này theo cách thủ công bằng cách sử dụ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 các thành phần này vào nhóm thành phần vị trí tĩnh theo cách thủ công.

Khách hàng chỉ có thể có một bộ thành phần đồng bộ hoá vị trí đang hoạt động (status của ENABLED). Nếu bạn cần tạo một loại nhóm tài sản đồng bộ hoá vị trí khác, trước tiên, hãy xoá nhóm tài sản hiện có.

Đính kèm bộ thành phần đồng bộ hoá vị trí vào một khách hàng

Sử dụng CustomerAssetSetService.MutateCustomerAssetSets để đính kèm bộ thành phần đồng bộ hoá vị trí 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 địa điểm 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 địa điểm. Điều này là do chiến dịch và nhóm quảng cáo kế thừa thành phần vị trí ở cấp khách hàng.

Bộ thành phần nhóm địa điểm chứa một nhóm nhỏ thành phần địa điểm của bộ thành phần đồng bộ hoá địa điểm. Bạn có thể tạo một bộ thành phần nhóm địa điểm động bằng cách tận dụng một số tính năng của Trang doanh nghiệp trên Google (chẳng hạn như lọc theo nhãn) hoặc mã nhận dạng chuỗi cửa hàng và vị trí 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 địa điểm tĩnh.

  1. Tạo một nhóm địa điểm trong bộ thành phần. Bộ thành phần nhóm vị trí 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 đang sử dụng hoặc vào một nhóm quảng cáo, tuỳ thuộc vào 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 địa điểm 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 nhóm vị trí động hoặc tĩnh.

Tạo một nhóm địa điểm trong bộ thành phần

Tạo 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á vị trí đã 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 địa điểm linh động hay tĩnh.

Tập hợp thành phần linh động

Tuỳ thuộc vào trường mà 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 đó, hãy đặ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á vị trí, bạn sẽ không thể tạo bộ thành phần nhóm địa điểm động. Lý do là vì bạn đã thêm vị trí 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 vị trí này.

Nhóm thành phần tĩnh

Đặt type thành STATIC_LOCATION_GROUP. Bạn có thể tạo các nhóm thành phần vị trí tĩnh cho mọi loại nhóm 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 bộ thành phần nhóm vị trí tĩnh, bạn cần thêm 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 biểu tượng CampaignAssetSetService.MutateCampaignAssetSets để đính kèm bộ thành phần nhóm địa điểm vào chiến dịch của bạn.

Hoặc sử dụng AdGroupAssetSetService.MutateAdGroupAssetSets nếu bạn muốn đính kèm bộ thành phần nhóm địa điểm vào một nhóm quảng cáo.

(Không bắt buộc) Thêm thành phần địa điểm vào nhóm thành phần 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á vị trí đã tạo trước đó. Sử dụng bộ lọc để chỉ truy xuất những tài sản bạn muốn.
  2. Thêm các thành phần đó vào tập hợp 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í của Trang doanh nghiệp

Khi bạn sử dụng business_profile_location_set và lọc trên listing_id_filters được truy xuất từ trang web hoặc API Trang doanh nghiệp, bạn có thể cần chuyển đổi các giá trị bằng 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 rằng mã vị trí trong 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 chuyển đổi mã đó bằng cách sử dụng một trong các ví dụ sau:

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 >= 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 >= 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.
  elseif 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 >= 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.
  } elseif ($business_profile_location_id >= 2**63) {
    return -1 * (2**64 - $business_profile_location_id);
  } else {
    return $business_profile_location_id;
  }
}