Google sử dụng công nghệ AI để dịch nội dung sang ngôn ngữ bạn ưu tiên. Bản dịch bằng AI có thể có lỗi.

Hướng dẫn bắt đầu sử dụng Google Ads API

Hướng dẫn này trình bày chi tiết quy trình từ đầu đến cuối để bắt đầu, xác thực và thực hiện lệnh gọi đầu tiên đến Google Ads API.

1. Điều kiện tiên quyết và hệ thống phân cấp tài khoản

Trước khi tương tác với Google Ads API, bạn phải hiểu rõ hệ thống phân cấp tài khoản và có cấu trúc tài khoản cấp cao nhất phù hợp.

Tài khoản người quản lý (MCC): Tài khoản người quản lý Google Ads (trước đây là Trung tâm khách hàng) là tài khoản chính được dùng để xem và quản lý nhiều tài khoản khách hàng. Bạn phải có Tài khoản người quản lý để đăng ký mã của nhà phát triển Google Ads API.
Tài khoản khách hàng: Tài khoản chuẩn nơi bạn tạo chiến dịch, nhóm quảng cáo và quảng cáo, đồng thời định cấu hình thông tin thanh toán.

Việc cần làm: Nếu bạn chưa có Tài khoản người quản lý, hãy tạo một tài khoản tại Tài khoản người quản lý Google Ads.

2. Lấy mã của nhà phát triển

Mã của nhà phát triển xác định duy nhất ứng dụng của bạn với Google Ads API và kiểm soát cấp truy cập số lượng lệnh gọi của bạn.

Các bước đăng ký

Đăng nhập vào Tài khoản người quản lý Google Ads.
Chuyển đến Công cụ và cài đặt > Thiết lập > Trung tâm API (hoặc Quản trị > Trung tâm API).
Điền vào biểu mẫu thông tin chi tiết về nhà phát triển và đồng ý với Điều khoản dịch vụ của API.
Gửi đơn đăng ký.

Cấp truy cập

Đang chờ phê duyệt: Các mã thông báo mới tạo sẽ nhận được trạng thái "Đang chờ xử lý" ngay lập tức. Bạn có thể sử dụng mã thông báo đang chờ xử lý để kết nối ngay với Tài khoản thử nghiệm, nhưng mã thông báo này sẽ không hoạt động đối với tài khoản sản xuất.
Quyền truy cập cơ bản: Cho phép tối đa 15.000 thao tác API mỗi ngày sau khi được phê duyệt.
Quyền truy cập tiêu chuẩn: Số lượng thao tác API hằng ngày không giới hạn cho những ứng dụng đáp ứng Chức năng tối thiểu bắt buộc (RMF).

3. Thiết lập tài khoản kiểm thử

Việc phát triển và thử nghiệm trên các tài khoản thực tế có thể dẫn đến mức chi tiêu quảng cáo không mong muốn và các sửa đổi chiến dịch. Bạn nên thực hiện mọi hoạt động phát triển đang diễn ra trên tài khoản thử nghiệm.

Tạo tài khoản người quản lý kiểm thử

Truy cập vào trang tạo Tài khoản người quản lý kiểm thử Google Ads.
Đăng nhập bằng một Tài khoản Google chưa được liên kết với Tài khoản người quản lý Google Ads thực tế của bạn.
Nhập tên tài khoản mô tả (ví dụ: MyCompany Test MCC).
Chọn mục đích sử dụng chính là Quản lý tài khoản của người khác.
Chọn quốc gia thanh toán, múi giờ và đơn vị tiền tệ. Nhấp vào Lưu và tiếp tục.

Tạo tài khoản khách hàng kiểm thử

Sau khi tạo Tài khoản người quản lý thử nghiệm, bạn phải tạo ít nhất một tài khoản khách hàng con để chạy chiến dịch thử nghiệm.

Đăng nhập vào Tài khoản Test Manager mà bạn vừa tạo.
Trong trình đơn điều hướng bên trái, hãy nhấp vào Tài khoản, rồi chọn Cài đặt tài khoản phụ (hoặc Hiệu suất).
Nhấp vào nút + (dấu cộng) màu xanh dương rồi chọn Tạo tài khoản mới.
Chọn tài khoản Google Ads.
Nhập tên tài khoản (ví dụ: Test Client Account A).
Chọn múi giờ và đơn vị tiền tệ, sau đó nhấp vào Lưu và tiếp tục.
Ghi lại Mã khách hàng gồm 10 chữ số (ví dụ: 1234567890 không có dấu gạch ngang) của tài khoản khách hàng mới này.

Các quy tắc quan trọng đối với tài khoản kiểm thử

Sử dụng mã của nhà phát triển: Không đăng ký mã của nhà phát triển từ Tài khoản người quản lý kiểm thử. Luôn sử dụng mã của nhà phát triển đang chờ xử lý hoặc đã được phê duyệt trong Tài khoản người quản lý sản xuất của bạn.
Thanh toán: Tài khoản kiểm thử không phân phát quảng cáo thực tế, vì vậy bạn không cần nhập thông tin thanh toán thực.

4. Thiết lập dự án trên Google Cloud

Tất cả các Yêu cầu API đều phải được xác thực bằng một dự án trên đám mây trên Google Cloud đã bật Google Ads API.

Các bước để bật API

Chuyển đến Google Cloud Console.
Tạo dự án mới hoặc chọn dự án hiện có.
Chuyển đến phần API và dịch vụ > Thư viện.
Tìm Google Ads API rồi nhấp vào Bật.

Tính năng đặt giá và thanh toán

Không mất phí API: Bạn có thể tạo dự án trên Google Cloud, bật API Google Ads và tạo thông tin xác thực OAuth 2.0 mà không mất phí. Google không tính bất kỳ khoản phí nào cho việc gọi hoặc sử dụng Google Ads API.
Các tài nguyên khác trên đám mây: Bạn sẽ chỉ phải trả phí Google Cloud nếu chủ động sử dụng các dịch vụ khác của Google Cloud có tính phí (chẳng hạn như Compute Engine, Cloud Run hoặc BigQuery) vượt quá hạn mức của Bậc miễn phí để lưu trữ ứng dụng hoặc lưu trữ dữ liệu quảng cáo.

5. Cấu hình xác thực OAuth 2.0

Google Ads API sử dụng OAuth 2.0 để xác thực và uỷ quyền các yêu cầu.

Các bước cho quy trình ứng dụng trên máy tính

Trong dự án trên Google Cloud, hãy chuyển đến API và Dịch vụ > Màn hình đồng ý OAuth rồi định cấu hình màn hình đồng ý. Thêm địa chỉ email của bạn vào mục Người dùng kiểm thử trong khi ứng dụng ở trạng thái Kiểm thử để tránh lỗi truy cập trong quá trình uỷ quyền.
Chuyển đến phần API và Dịch vụ > Thông tin xác thực.
Nhấp vào Tạo thông tin xác thực > Mã ứng dụng OAuth.
Chọn loại ứng dụng là Ứng dụng dành cho máy tính.
Nhấp vào Tạo, sau đó tải tệp thông tin xác thực OAuth xuống dưới dạng client_secret.json (hoặc sao chép Client ID và Client Secret).

Tạo mã làm mới

Sau khi có Mã ứng dụng khách và Khoá bí mật của ứng dụng khách, bạn phải tạo một Mã làm mới. Bạn có thể thực hiện việc này bằng Google OAuth 2.0 Playground hoặc một tập lệnh thư viện ứng dụng.

Cách A: Sử dụng Google OAuth 2.0 Playground

Truy cập vào Google OAuth 2.0 Playground.
Nhấp vào Biểu tượng bánh răng (cấu hình OAuth 2.0) ở góc trên bên phải.
Chọn hộp Sử dụng thông tin xác thực OAuth của riêng bạn.
Nhập Client ID và Client Secret OAuth2, rồi nhấp vào Đóng.
Trong Bước 1 (Chọn và uỷ quyền API) ở bên trái, hãy nhập phạm vi Google Ads API vào trường "Nhập phạm vi của riêng bạn": https://www.googleapis.com/auth/adwords
Nhấp vào Uỷ quyền cho API. Khi được nhắc, hãy đăng nhập bằng Tài khoản Google có quyền truy cập vào Tài khoản người quản lý Google Ads (hoặc Tài khoản thử nghiệm) của bạn.
Nhấp vào Tiếp tục trên màn hình xin phép.
Trong Bước 2 (Đổi mã uỷ quyền lấy mã thông báo), hãy nhấp vào nút màu xanh dương Đổi mã uỷ quyền lấy mã thông báo.
Refresh token và Access token của bạn sẽ xuất hiện trong bảng điều khiển phản hồi. Sao chép và lưu Refresh token.

Cách B: Sử dụng tập lệnh thư viện ứng dụng (ví dụ về Python)

Thư viện ứng dụng Python chính thức cung cấp một tập lệnh trợ giúp tích hợp sẵn để tạo thông tin xác thực. Ngoài ra, bạn có thể tải client_secret.json xuống từ Google Cloud Console rồi chạy tập lệnh Python độc lập sau:

Cài đặt thư viện OAuth bắt buộc:

pip install google-auth-oauthlib

Tạo một tập lệnh có tên là generate_refresh_token.py trong cùng thư mục với client_secret.json và kích hoạt tập lệnh đó:

from google_auth_oauthlib.flow import InstalledAppFlow

CLIENT_SECRETS_FILE = "client_secret.json"
SCOPES = ["https://www.googleapis.com/auth/adwords"]

def main():
    flow = InstalledAppFlow.from_client_secrets_file(
        CLIENT_SECRETS_FILE, SCOPES
    )
    credentials = flow.run_local_server(port=0)
    
    print("\nAuthorization Successful!\n")
    print(f"Refresh Token: {credentials.refresh_token}")

if __name__ == "__main__":
    main()

6. Thiết lập thông tin đăng nhập và thư viện ứng dụng

Google cung cấp các thư viện ứng dụng được hỗ trợ chính thức để xử lý việc xác thực, chuyển đổi tuần tự và giao tiếp với các điểm cuối gRPC.

Ngôn ngữ được hỗ trợ

Python: pip install google-ads
Java: Có sẵn thông qua Maven hoặc Gradle
PHP: composer require googleads/google-ads-php
.NET: Install-Package Google.Ads.GoogleAds
Ruby: gem install google-ads-googleads
Perl: cpanm Google::Ads::GoogleAds::Client

Tệp cấu hình (`google-ads.yaml`)

Tạo một tệp cấu hình chứa thông tin đăng nhập của bạn. Theo mặc định, phương thức khởi tạo của thư viện ứng dụng (ví dụ: GoogleAdsClient.load_from_storage()) sẽ tự động tìm kiếm google-ads.yaml ở 2 vị trí:

Thư mục làm việc hiện tại mà tập lệnh của bạn đang chạy.
Thư mục chính của người dùng (~ trên Linux/macOS hoặc %HOMEPATH% trên Windows).

Nếu lưu trữ tệp ở một vị trí tuỳ chỉnh, bạn có thể truyền đường dẫn một cách rõ ràng đến phương thức khởi tạo (ví dụ: load_from_storage("path/to/google-ads.yaml")).

developer_token: "INSERT_YOUR_DEVELOPER_TOKEN_HERE"
client_id: "INSERT_YOUR_OAUTH2_CLIENT_ID_HERE"
client_secret: "INSERT_YOUR_OAUTH2_CLIENT_SECRET_HERE"
refresh_token: "INSERT_YOUR_OAUTH2_REFRESH_TOKEN_HERE"
login_customer_id: "INSERT_YOUR_MANAGER_ACCOUNT_ID_HERE"

7. Thực hiện lệnh gọi API đầu tiên

Để xác minh chế độ thiết lập quy trình tham gia, hãy chạy một tập lệnh khởi động nhanh để tìm nạp các chiến dịch hiện có từ tài khoản thử nghiệm của bạn.

Ví dụ về tập lệnh Python (`quickstart.py`)

import sys
from google.ads.googleads.client import GoogleAdsClient
from google.ads.googleads.errors import GoogleAdsException

def main(client, customer_id):
    ga_service = client.get_service("GoogleAdsService")
    query = """
        SELECT
          campaign.id,
          campaign.name
        FROM campaign
        ORDER BY campaign.id
    """
    
    # Issues a search request
    stream = ga_service.search_stream(customer_id=customer_id, query=query)
    for batch in stream:
        for row in batch.results:
            print(
                f"Campaign with ID {row.campaign.id} and name "
                f"'{row.campaign.name}' was found."
            )

if __name__ == "__main__":
    # Initialize client from google-ads.yaml
    # By default, load_from_storage() searches for 'google-ads.yaml' in the
    # current working directory or the user's home directory (~). You can
    # also pass an explicit path: load_from_storage("path/to/google-ads.yaml")
    try:
        googleads_client = GoogleAdsClient.load_from_storage()
        # Replace with your test client account ID (without hyphens) from
        # Section 3, NOT your manager account ID (which belongs in
        # google-ads.yaml).
        test_customer_id = "1234567890" 
        main(googleads_client, test_customer_id)
    except GoogleAdsException as ex:
        print(
            f"Request failed with status {ex.error.code().name} and "
            f"includes the following errors:"
        )
        for error in ex.failure.errors:
            print(f"\tError with message '{error.message}'.")
            if error.location:
                for field_path_element in error.location.field_path_elements:
                    print(f"\t\tOn field: {field_path_element.field_name}")
        sys.exit(1)

8. Các phương pháp hay nhất và tài nguyên

Ghi nhật ký: Bật tính năng ghi nhật ký chi tiết trong thư viện ứng dụng để ghi lại mã yêu cầu và mã phản hồi (request-id). Đây là những thông tin cần thiết khi bạn yêu cầu Google hỗ trợ.
Xử lý lỗi: Triển khai biện pháp xử lý lỗi hữu ích cho GoogleAdsException, đặc biệt là quản lý hạn mức (RESOURCE_TEMPORARILY_EXHAUSTED).
Tài liệu chính thức: Tài liệu dành cho nhà phát triển Google Ads API
Thư viện ứng dụng và mẫu mã: Kho lưu trữ Google Ads trên GitHub

Giới thiệu

Tiếp

Bắt đầu nhanh

Hướng dẫn bắt đầu sử dụng Google Ads API Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.