راهنمای جامع آن‌بوردینگ API گوگل ادز

این راهنما جزئیات فرآیند کامل و جامع برای ورود به سیستم، احراز هویت و اولین تماس شما با API گوگل ادز را شرح می‌دهد.

۱. پیش‌نیازها و سلسله مراتب حساب‌ها

قبل از تعامل با API گوگل ادز، باید سلسله مراتب حساب کاربری را درک کنید و ساختار صحیح حساب کاربری سطح بالا را در جای خود داشته باشید.

  • حساب مدیر (MCC): حساب مدیر تبلیغات گوگل (که قبلاً مرکز مشتریان من نام داشت) یک حساب اصلی است که برای مشاهده و مدیریت چندین حساب کاربری استفاده می‌شود. برای درخواست توکن توسعه‌دهنده API تبلیغات گوگل، باید یک حساب مدیر داشته باشید.
  • حساب کاربری مشتری: حساب استانداردی که کمپین‌ها، گروه‌های تبلیغاتی و تبلیغات در آن ایجاد شده و صورتحساب پیکربندی می‌شود.

مورد اقدام: اگر حساب کاربری مدیریت ندارید، یکی را در حساب‌های مدیریت تبلیغات گوگل ایجاد کنید.

۲. یک توکن توسعه‌دهنده دریافت کنید

توکن توسعه‌دهنده، اپلیکیشن شما را به طور منحصر به فرد به API گوگل ادز معرفی می‌کند و سطح دسترسی به حجم تماس شما را کنترل می‌کند.

مراحل درخواست

  1. وارد حساب کاربری مدیر تبلیغات گوگل خود شوید.
  2. به ابزارها و تنظیمات > تنظیمات > مرکز API (یا مدیر > مرکز API ) بروید.
  3. فرم اطلاعات توسعه‌دهنده را پر کنید و با شرایط خدمات API موافقت کنید.
  4. درخواست خود را ارسال کنید.

سطوح دسترسی

  • در انتظار تأیید: توکن‌های تازه ایجاد شده بلافاصله وضعیت "در انتظار" دریافت می‌کنند. می‌توانید از یک توکن در انتظار برای اتصال فوری به حساب‌های آزمایشی استفاده کنید، اما در مورد حساب‌های عملیاتی کار نخواهد کرد.
  • دسترسی پایه: پس از تأیید، امکان انجام حداکثر ۱۵۰۰۰ عملیات API در روز را فراهم می‌کند.
  • دسترسی استاندارد: عملیات API روزانه نامحدود برای برنامه‌هایی که حداقل عملکرد مورد نیاز (RMF) را برآورده می‌کنند.

۳. حساب‌های آزمایشی راه‌اندازی کنید

توسعه و آزمایش در حساب‌های کاربری عملیاتی، خطر هزینه‌های تبلیغاتی و تغییرات ناخواسته در کمپین را به همراه دارد. اکیداً توصیه می‌شود که تمام توسعه‌های فعال را در حساب‌های کاربری آزمایشی انجام دهید.

نحوه ایجاد حساب کاربری مدیر آزمون

  1. به صفحه ایجاد حساب کاربری مدیریت تست گوگل ادز بروید.
  2. با یک حساب گوگل که از قبل به حساب مدیریت تبلیغات گوگل (Google Ads Manager Account) شما مرتبط نیست ، وارد شوید.
  3. یک نام حساب توصیفی وارد کنید (مثلاً MyCompany Test MCC ).
  4. کاربرد اصلی را مدیریت حساب‌های دیگران انتخاب کنید.
  5. کشور، منطقه زمانی و واحد پول خود را انتخاب کنید. روی ذخیره و ادامه کلیک کنید.

نحوه ایجاد حساب کاربری آزمایشی برای کلاینت

پس از ایجاد حساب مدیریت تست، باید حداقل یک حساب کاربری فرزند برای اجرای کمپین‌های تست ایجاد کنید.

  1. وارد حساب کاربری مدیر آزمون تازه ایجاد شده خود شوید.
  2. از منوی ناوبری سمت چپ، روی حساب‌ها (Accounts) کلیک کنید، سپس تنظیمات حساب فرعی (یا عملکرد (Performance )) را انتخاب کنید.
  3. روی دکمه آبی + (به‌علاوه) کلیک کنید و گزینه ایجاد حساب کاربری جدید را انتخاب کنید.
  4. حساب گوگل ادز را انتخاب کنید.
  5. یک نام حساب وارد کنید (مثلاً، Test Client Account A ).
  6. منطقه زمانی و واحد پول را انتخاب کنید، سپس روی ذخیره و ادامه کلیک کنید.
  7. شناسه مشتری ده رقمی (مثلاً 1234567890 بدون خط تیره) این حساب مشتری جدید را یادداشت کنید.

قوانین مهم برای حساب‌های آزمایشی

  • استفاده از توکن توسعه‌دهنده: برای دریافت توکن توسعه‌دهنده از حساب مدیریت تست خود اقدام نکنید . همیشه از توکن توسعه‌دهنده در حال بررسی یا تأیید شده از حساب مدیریت تولید خود استفاده کنید.
  • صورتحساب: حساب‌های آزمایشی تبلیغات واقعی ارائه نمی‌دهند، بنابراین نیازی به وارد کردن اطلاعات صورتحساب واقعی ندارید.

۴. راه‌اندازی پروژه گوگل کلود

تمام درخواست‌های API باید با استفاده از یک پروژه Google Cloud با فعال بودن Google Ads API تأیید اعتبار شوند.

مراحل فعال‌سازی API

  1. به کنسول ابری گوگل بروید.
  2. یک پروژه جدید ایجاد کنید یا یک پروژه موجود را انتخاب کنید.
  3. به APIها و خدمات > کتابخانه بروید.
  4. عبارت Google Ads API را جستجو کنید و روی فعال‌سازی کلیک کنید.

قیمت‌گذاری و یادداشت صورتحساب

  • بدون هزینه API: ایجاد یک پروژه Google Cloud، فعال کردن Google Ads API و تولید اعتبارنامه‌های OAuth 2.0 100٪ رایگان است. گوگل هیچ هزینه‌ای برای فراخوانی یا استفاده از خود Google Ads API دریافت نمی‌کند.
  • سایر منابع ابری: شما فقط در صورتی متحمل هزینه‌های گوگل کلود خواهید شد که به طور فعال از سایر سرویس‌های گوگل کلود قابل پرداخت (مانند Compute Engine، Cloud Run یا BigQuery) فراتر از محدودیت‌های سطح رایگان آنها برای میزبانی برنامه یا ذخیره داده‌های تبلیغاتی خود استفاده کنید.

۵. پیکربندی احراز هویت OAuth 2.0

رابط برنامه‌نویسی کاربردی گوگل ادز از OAuth 2.0 برای احراز هویت و تأیید درخواست‌ها استفاده می‌کند.

مراحل جریان برنامه دسکتاپ یا وب

  1. در پروژه گوگل کلود خود، به APIها و خدمات > صفحه رضایت OAuth بروید و صفحه رضایت را پیکربندی کنید.
  2. به APIها و خدمات > اعتبارنامه‌ها بروید.
  3. روی ایجاد اعتبارنامه‌ها > شناسه کلاینت OAuth کلیک کنید.
  4. نوع برنامه (مثلاً برنامه دسکتاپ یا برنامه وب ) را انتخاب کنید.
  5. روی ایجاد کلیک کنید. Client ID و Client Secret خود را دانلود یا کپی کنید.

یک توکن به‌روزرسانی ایجاد کنید

وقتی شناسه کلاینت و راز کلاینت خود را داشتید، باید یک توکن به‌روزرسانی (Refresh Token) ایجاد کنید. می‌توانید این کار را با استفاده از Google OAuth 2.0 Playground یا یک اسکریپت کتابخانه کلاینت انجام دهید.

روش الف: استفاده از Google OAuth 2.0 Playground (مبتنی بر وب)

  1. به Google OAuth 2.0 Playground بروید.
  2. روی نماد چرخ‌دنده (پیکربندی OAuth 2.0) در گوشه بالا سمت راست کلیک کنید.
  3. کادر « استفاده از اعتبارنامه‌های OAuth خودتان» را علامت بزنید.
  4. Client ID OAuth2 و Client Secret خود را وارد کنید، سپس روی بستن کلیک کنید.
  5. در مرحله ۱ (انتخاب و تأیید APIها) در سمت چپ، محدوده API تبلیغات گوگل را در فیلد «محدوده‌های خودتان را وارد کنید» وارد کنید: https://www.googleapis.com/auth/adwords
  6. روی تأیید APIها کلیک کنید. وقتی از شما خواسته شد، با حساب گوگلی که به حساب مدیریت تبلیغات گوگل شما (یا حساب آزمایشی) دسترسی دارد، وارد شوید.
  7. در صفحه رضایت، روی ادامه کلیک کنید.
  8. در مرحله 2 (کد مجوز تبادل برای توکن‌ها) ، روی دکمه آبی رنگ کد مجوز تبادل برای توکن‌ها کلیک کنید.
  9. Refresh token و Access token شما در پنل پاسخ نمایش داده خواهند شد. Refresh token را کپی و ذخیره کنید.

روش ب: استفاده از اسکریپت کتابخانه کلاینت (مثال پایتون)

کتابخانه رسمی کلاینت پایتون یک اسکریپت کمکی داخلی برای تولید اعتبارنامه‌ها ارائه می‌دهد. به عنوان یک جایگزین، می‌توانید اسکریپت پایتون مستقل زیر را اجرا کنید:

  1. کتابخانه OAuth مورد نیاز را نصب کنید: 
pip install google-auth-oauthlib
  1. یک اسکریپت با نام generate_refresh_token.py ایجاد کنید و آن را اجرا کنید: 
from google_auth_oauthlib.flow import InstalledAppFlow

# Set your Client ID and Secret
CLIENT_ID = "INSERT_YOUR_CLIENT_ID_HERE"
CLIENT_SECRET = "INSERT_YOUR_CLIENT_SECRET_HERE"
SCOPES = ["https://www.googleapis.com/auth/adwords"]

def main():
    client_config = {
        "installed": {
            "client_id": CLIENT_ID,
            "client_secret": CLIENT_SECRET,
            "auth_uri": "https://accounts.google.com/o/oauth2/auth",
            "token_uri": "https://oauth2.googleapis.com/token",
        }
    }
    
    # Initialize the flow
    flow = InstalledAppFlow.from_client_config(client_config, SCOPES)
    
    # Run the local server flow to prompt the user to log in
    credentials = flow.run_local_server(port=0)
    
    print("\nAuthorization Successful!\n")
    print(f"Refresh Token: {credentials.refresh_token}")

if __name__ == "__main__":
    main()

۶. تنظیمات کتابخانه کلاینت و اعتبارنامه‌ها

گوگل کتابخانه‌های کلاینتی با پشتیبانی رسمی ارائه می‌دهد که احراز هویت، سریال‌سازی و ارتباط با نقاط پایانی gRPC را مدیریت می‌کنند.

زبان‌های پشتیبانی‌شده

  • پایتون: pip install google-ads
  • جاوا: از طریق Maven یا Gradle در دسترس است
  • پی‌اچ‌پی: composer require googleads/google-ads-php
  • دات نت: Install-Package Google.Ads.GoogleAds
  • روبی: gem install google-ads-googleads

فایل پیکربندی ( google-ads.yaml )

یک فایل پیکربندی حاوی اطلاعات احراز هویت خود ایجاد کنید. به طور پیش‌فرض، متد مقداردهی اولیه کتابخانه کلاینت (مثلاً GoogleAdsClient.load_from_storage() ) به طور خودکار google-ads.yaml را در دو مکان جستجو می‌کند:

  1. دایرکتوری کاری فعلی که اسکریپت شما از آن اجرا می‌شود.
  2. دایرکتوری خانگی کاربر شما ( ~ در لینوکس/مک یا %HOMEPATH% در ویندوز).

اگر فایل را در یک مکان دلخواه ذخیره می‌کنید، می‌توانید مسیر را به صراحت به متد مقداردهی اولیه ارسال کنید (مثلاً، 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"

۷. اولین فراخوانی API خود را انجام دهید

برای تأیید تنظیمات اولیه، یک اسکریپت شروع سریع اجرا کنید تا کمپین‌های موجود را از حساب آزمایشی خود دریافت کنید.

مثال اسکریپت پایتون ( 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 '{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)
        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 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)

۸. بهترین شیوه‌ها و منابع

  • ثبت وقایع: ثبت وقایع دقیق را در کتابخانه کلاینت خود فعال کنید تا شناسه‌های درخواست/پاسخ ( request-id ) را ثبت کنید، که هنگام درخواست پشتیبانی از گوگل ضروری هستند.
  • مدیریت خطا: مدیریت خطای قوی برای GoogleAdsException ، به ویژه مدیریت محدودیت‌های نرخ ( RESOURCE_TEMPORARILY_EXHAUSTED ) را پیاده‌سازی کنید.
  • مستندات رسمی: اسناد توسعه‌دهندگان API گوگل ادز
  • کتابخانه‌ها و نمونه‌های کد کلاینت: مخازن تبلیغات گوگل گیت‌هاب