คู่มือการเริ่มต้นใช้งาน Google Ads API

คู่มือนี้จะอธิบายรายละเอียดกระบวนการเริ่มต้นใช้งาน การตรวจสอบสิทธิ์ และการเรียก Google Ads API ครั้งแรกแบบครบวงจร

1. ข้อกำหนดเบื้องต้นและลำดับชั้นบัญชี

ก่อนที่จะโต้ตอบกับ Google Ads API คุณต้องทำความเข้าใจลำดับชั้นบัญชีและมีโครงสร้างบัญชีระดับบนสุดที่ถูกต้อง

• บัญชีดูแลจัดการ (MCC): บัญชีดูแลจัดการ Google Ads (เดิมคือศูนย์ลูกค้าของฉัน) เป็นบัญชีหลักที่ใช้ดูและจัดการบัญชีลูกค้าหลายบัญชี คุณต้องมีบัญชีดูแลจัดการเพื่อสมัครรับโทเค็นของนักพัฒนา Google Ads API
• บัญชีลูกค้า: บัญชีมาตรฐานที่สร้างแคมเปญ กลุ่มโฆษณา และโฆษณา รวมถึงกำหนดค่าการเรียกเก็บเงิน

สิ่งที่ต้องทำ: หากไม่มีบัญชีดูแลจัดการ ให้สร้างบัญชีที่ บัญชีดูแลจัดการ Google Ads

2. รับโทเค็นของนักพัฒนา

โทเค็นของนักพัฒนาจะระบุแอปพลิเคชันของคุณต่อ Google Ads API ได้อย่างไม่ซ้ำกัน และควบคุมระดับการเข้าถึงปริมาณการเรียกของคุณ

ขั้นตอนการสมัคร

1. ลงชื่อเข้าใช้บัญชีดูแลจัดการ Google Ads
2. ไปที่เครื่องมือและการตั้งค่า > การตั้งค่า > ศูนย์ API (หรือผู้ดูแลระบบ > ศูนย์ API)
3. กรอกแบบฟอร์มรายละเอียดนักพัฒนาและยอมรับข้อกำหนดในการให้บริการของ API
4. ส่งใบสมัคร

ระดับการเข้าถึง

• รอการอนุมัติ: โทเค็นที่สร้างใหม่จะได้รับสถานะ "รอดำเนินการ" ทันที คุณสามารถใช้โทเค็นที่รอดำเนินการเพื่อเชื่อมต่อกับบัญชีทดสอบ ได้ทันที แต่จะใช้กับบัญชีที่ใช้งานจริงไม่ได้
• สิทธิ์เข้าถึงระดับพื้นฐาน: อนุญาตการดำเนินการ API สูงสุด 15,000 รายการต่อวันเมื่อได้รับอนุมัติ
• สิทธิ์เข้าถึงระดับมาตรฐาน: การดำเนินการ API รายวันไม่จำกัดสำหรับแอปพลิเคชันที่เป็นไปตามฟังก์ชันขั้นต่ำที่จำเป็น (RMF)

3. ตั้งค่าบัญชีทดสอบ

การพัฒนาและทดสอบกับบัญชีที่ใช้งานจริงอาจทำให้เกิดค่าโฆษณาที่ไม่ต้องการและการแก้ไขแคมเปญ เราขอแนะนำอย่างยิ่งให้ทำการพัฒนาที่ใช้งานอยู่ทั้งหมดกับบัญชีทดสอบ

สร้างบัญชีดูแลจัดการทดสอบ

1. ไปที่หน้าสำหรับสร้างบัญชีดูแลจัดการทดสอบ Google Ads
2. ลงชื่อเข้าใช้ด้วยบัญชี Google ที่ยังไม่ได้ ลิงก์กับบัญชีดูแลจัดการ Google Ads ที่ใช้งานจริง
3. ป้อนชื่อบัญชีที่สื่อความหมาย (เช่น MyCompany Test MCC)
4. เลือกการใช้งานหลักเป็นจัดการบัญชีของผู้อื่น
5. เลือกประเทศสำหรับการเรียกเก็บเงิน เขตเวลา และสกุลเงิน คลิกบันทึกและดำเนินการต่อ

สร้างบัญชีลูกค้าทดสอบ

เมื่อสร้างบัญชีดูแลจัดการทดสอบแล้ว คุณต้องสร้างบัญชีลูกค้าลูกอย่างน้อย 1 บัญชีเพื่อเรียกใช้แคมเปญทดสอบ

1. ลงชื่อเข้าใช้บัญชีดูแลจัดการทดสอบ ที่สร้างขึ้นใหม่
2. คลิกบัญชีจากเมนูการนำทางด้านซ้าย แล้วเลือก การตั้งค่าบัญชีย่อย (หรือประสิทธิภาพ)
3. คลิกปุ่ม + (บวก) สีน้ำเงิน แล้วเลือกสร้างบัญชีใหม่
4. เลือกบัญชี Google Ads
5. ป้อนชื่อบัญชี (เช่น Test Client Account A)
6. เลือกเขตเวลาและสกุลเงิน แล้วคลิกบันทึกและดำเนินการต่อ
7. จดรหัสลูกค้า 10 หลัก (เช่น 1234567890 โดยไม่มีขีดกลาง) ของบัญชีลูกค้าใหม่นี้

กฎสำคัญสำหรับบัญชีทดสอบ

• การใช้โทเค็นของนักพัฒนา: อย่า สมัครรับโทเค็นของนักพัฒนาจากบัญชีดูแลจัดการทดสอบ ให้ใช้โทเค็นของนักพัฒนาที่รอดำเนินการหรือได้รับอนุมัติจากบัญชีดูแลจัดการที่ใช้งานจริง เสมอ
• การเรียกเก็บเงิน: บัญชีทดสอบจะไม่แสดงโฆษณาจริง ดังนั้นคุณจึงไม่จำเป็นต้องป้อนข้อมูลสำหรับการเรียกเก็บเงินจริง

4. การตั้งค่าโปรเจ็กต์ Google Cloud

คำขอ API ทั้งหมดต้องได้รับการตรวจสอบสิทธิ์โดยใช้โปรเจ็กต์ Google Cloud ที่เปิดใช้ Google Ads API

ขั้นตอนในการเปิดใช้ API

1. ไปที่ คอนโซล Google Cloud
2. สร้างโปรเจ็กต์ใหม่หรือเลือกโปรเจ็กต์ที่มีอยู่
3. ไปที่API และบริการ > ไลบรารี
4. ค้นหา Google Ads API แล้วคลิกเปิดใช้

การกำหนดราคาและการเรียกเก็บเงิน

• ไม่มีค่าธรรมเนียม API: การสร้างโปรเจ็กต์ที่อยู่ในระบบคลาวด์ของ Google, การเปิดใช้ Google Ads API และการสร้างข้อมูลเข้าสู่ระบบ OAuth 2.0 ไม่มีค่าใช้จ่าย Google จะไม่คิดค่าธรรมเนียมใดๆ สำหรับการเรียกหรือใช้ Google Ads API เอง
• ทรัพยากรระบบคลาวด์อื่นๆ: คุณจะเสียค่าธรรมเนียม Google Cloud ก็ต่อเมื่อใช้บริการ Google Cloud ที่เรียกเก็บเงินอื่นๆ (เช่น Compute Engine, Cloud Run หรือ BigQuery) เกินขีดจำกัดของรุ่นฟรีเพื่อโฮสต์แอปพลิเคชันหรือจัดเก็บข้อมูลโฆษณา

5. การกำหนดค่าการตรวจสอบสิทธิ์ OAuth 2.0

Google Ads API ใช้ OAuth 2.0 เพื่อตรวจสอบสิทธิ์และให้สิทธิ์คำขอ

ขั้นตอนสำหรับโฟลว์แอปพลิเคชันบนเดสก์ท็อป

1. ในโปรเจ็กต์ที่อยู่ในระบบคลาวด์ของ Google ให้ไปที่API และบริการ > หน้าจอขอความยินยอม OAuth แล้วกำหนดค่าหน้าจอขอความยินยอม เพิ่มอีเมลลงในส่วนผู้ใช้ทดสอบ ขณะที่แอปอยู่ในสถานะการทดสอบเพื่อป้องกันข้อผิดพลาดในการเข้าถึงระหว่างการให้สิทธิ์
2. ไปที่API และบริการ > ข้อมูลเข้าสู่ระบบ
3. คลิกสร้างข้อมูลเข้าสู่ระบบ > รหัสไคลเอ็นต์ OAuth
4. เลือกประเภทแอปพลิเคชันเป็นแอปบนเดสก์ท็อป
5. คลิกสร้าง แล้วดาวน์โหลดไฟล์ข้อมูลเข้าสู่ระบบ OAuth เป็น client_secret.json (หรือคัดลอก Client ID และ Client Secret)

สร้างโทเค็นการรีเฟรช

เมื่อมีรหัสไคลเอ็นต์และรหัสลับไคลเอ็นต์แล้ว คุณต้องสร้างโทเค็นเพื่อการรีเฟรช คุณสามารถทำได้โดยใช้ Google OAuth 2.0 Playground หรือสคริปต์ไลบรารีของไคลเอ็นต์

วิธีที่ 1: ใช้ Google OAuth 2.0 Playground

1. ไปที่ Google OAuth 2.0 Playground
2. คลิกไอคอนรูปเฟือง (การกำหนดค่า OAuth 2.0) ที่มุมขวาบน
3. เลือกช่องใช้ข้อมูลเข้าสู่ระบบ OAuth ของคุณเอง
4. ป้อน Client ID และ Client Secret OAuth2 แล้วคลิกปิด
5. ในขั้นตอนที่ 1 (เลือกและให้สิทธิ์ API) ทางด้านซ้าย ให้ป้อนขอบเขต Google Ads API ในช่อง "ป้อนขอบเขตของคุณเอง" ดังนี้ https://www.googleapis.com/auth/adwords
6. คลิกให้สิทธิ์ API เมื่อได้รับข้อความแจ้ง ให้ลงชื่อเข้าใช้ด้วยบัญชี Google ที่มีสิทธิ์เข้าถึงบัญชีดูแลจัดการ Google Ads (หรือบัญชีทดสอบ)
7. คลิกดำเนินการต่อ ในหน้าจอขอความยินยอม
8. ในขั้นตอนที่ 2 (เปลี่ยนรหัสการให้สิทธิ์เป็นโทเค็น) ให้คลิกปุ่มสีน้ำเงิน เปลี่ยนรหัสการให้สิทธิ์เป็นโทเค็น
9. Refresh token และ Access token ของคุณจะแสดงในแผงการตอบกลับ คัดลอกและบันทึก Refresh token

วิธีที่ 2: ใช้สคริปต์ไลบรารีของไคลเอ็นต์ (ตัวอย่าง Python)

ไลบรารีของไคลเอ็นต์ Python อย่างเป็นทางการมีสคริปต์ตัวช่วยในตัวเพื่อสร้างข้อมูลเข้าสู่ระบบ หรือคุณจะดาวน์โหลด client_secret.json จากคอนโซล Google Cloud แล้วเรียกใช้สคริปต์ Python แบบสแตนด์อโลนต่อไปนี้ก็ได้

1. ติดตั้งไลบรารี OAuth ที่จำเป็น

pip install google-auth-oauthlib

1. สร้างสคริปต์ชื่อ generate_refresh_token.py ในไดเรกทอรีเดียวกับ client_secret.json แล้วดำเนินการ

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. การตั้งค่าไลบรารีของไคลเอ็นต์และข้อมูลเข้าสู่ระบบ

Google มีไลบรารีของไคลเอ็นต์ที่รองรับอย่างเป็นทางการซึ่งจัดการการตรวจสอบสิทธิ์ การซีเรียลไลซ์ และการสื่อสารกับปลายทาง gRPC

ภาษาที่รองรับ

• Python: pip install google-ads
• Java: ใช้งานได้ผ่าน Maven หรือ 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

ไฟล์การกำหนดค่า (google-ads.yaml)

สร้างไฟล์การกำหนดค่าที่มีข้อมูลเข้าสู่ระบบ โดยค่าเริ่มต้น เมธอดการเริ่มต้นของไลบรารีของไคลเอ็นต์ (เช่น GoogleAdsClient.load_from_storage()) จะค้นหา google-ads.yaml ใน 2 ตำแหน่งโดยอัตโนมัติ

1. ไดเรกทอรีที่ใช้งานในปัจจุบัน ซึ่งเรียกใช้สคริปต์
2. ไดเรกทอรีแรก ของผู้ใช้ (~ ใน Linux/macOS หรือ %HOMEPATH% ใน Windows)

หากจัดเก็บไฟล์ไว้ในตำแหน่งที่กำหนดเอง คุณสามารถส่งเส้นทางไปยัง เมธอดการเริ่มต้นอย่างชัดเจน (เช่น 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. เรียก API ครั้งแรก

หากต้องการยืนยันการตั้งค่าการเริ่มต้นใช้งาน ให้เรียกใช้สคริปต์เริ่มต้นอย่างรวดเร็วเพื่อดึงแคมเปญที่มีอยู่ออกจากบัญชีทดสอบ

ตัวอย่างสคริปต์ 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. แนวทางปฏิบัติแนะนำและแหล่งข้อมูล

• การบันทึก: เปิดใช้การบันทึกโดยละเอียดในไลบรารีของไคลเอ็นต์เพื่อบันทึกรหัสคำขอและการตอบกลับ (request-id) ซึ่งจำเป็นเมื่อขอรับการสนับสนุนจาก Google
• การจัดการข้อผิดพลาด: ใช้การจัดการข้อผิดพลาดที่มีประสิทธิภาพสำหรับ GoogleAdsException โดยเฉพาะอย่างยิ่งการจัดการขีดจำกัดอัตรา (RESOURCE_TEMPORARILY_EXHAUSTED)
• เอกสารอย่างเป็นทางการ: เอกสารประกอบสำหรับนักพัฒนาแอป Google Ads API
• ไลบรารีของไคลเอ็นต์และตัวอย่างโค้ด: ที่เก็บ Google Ads ใน GitHub