‫Google برای ترجمه محتوا به زبان ترجیحی شما از فناوری هوشواره استفاده می‌کند. ترجمه‌های هوشواره‌ای ممکن است اشتباه داشته باشند.

راه‌اندازی سریع

این راهنمای راه‌اندازی سریع به شما کمک می‌کند اولین فراخوانی میانای برنامه‌سازی کاربردی را به Google Ads API انجام دهید.

مفاهیم کلیدی

پروژه Google Cloud: پروژه Google Cloud مبنای ایجاد، فعال‌سازی، و استفاده از همه سرویس‌های Google، ازجمله مدیریت میاناهای برنامه‌سازی کاربردی و اطلاعات کاربری میانای برنامه‌سازی کاربردی OAuth 2.0 را تشکیل می‌دهد. می‌توانید ازطریق کنسول Google Cloud پروژه ایجاد کنید.
سطح دسترسی به میانای برنامه‌سازی کاربردی: سطح دسترسی به میانای برنامه‌سازی کاربردی در پروژه Google Cloud شما تعداد فراخوانی‌های میانای برنامه‌سازی کاربردی را که می‌توانید در روز انجام دهید و محیط‌هایی را که می‌توانید در آن‌ها فراخوانی میانای برنامه‌سازی کاربردی انجام دهید کنترل می‌کند. سطح دسترسی به میانای برنامه‌سازی کاربردی پروژه شما در صفحه نمای کلی Google Ads API پروژه شما فهرست شده است.
حساب مدیر Google Ads: از حساب مدیر Google Ads برای مدیریت حساب‌های Google Ads دیگر استفاده می‌شود که می‌تواند مجموعه‌ای از حساب‌های مشتری Google Ads یا حساب‌های مدیر Google Ads دیگر باشد.
حساب مشتری Google Ads: حساب Google Ads که برای اجرای آگهی‌هایی که می‌خواهید با فراخوانی‌های API هدف‌یابی کنید استفاده می‌شود.
شناسه مشتری کارخواه: شماره ۱۰ رقمی که حساب کارخواه Google Ads را شناسایی می‌کند. اگر این شناسه را از میانای کاربری Google Ads کپی کرده‌اید، حتماً خط تیره‌ها را بردارید.
OAuth 2.0: OAuth 2.0 یک پروتکل استاندارد صنعتی برای مجوزدهی است که توسط همه Google APIها استفاده می‌شود. برای تولید اطلاعات اعتباری OAuth 2.0 جهت برقراری تماس‌های API، به حساب سرویس و کلید نیاز دارید.
حساب خدمات: نوع خاصی از «حساب Google» که به‌جای کاربر فردی به برنامه شما تعلق دارد. از آن برای اصالت‌سنجی کردن برنامه شما در Google Ads API استفاده می‌شود. برای دریافت حساب سرویس، به پروژه Google Cloud نیاز دارید.
کلید حساب سرویس: فایل اطلاعات اعتباری برنامه JSON که حاوی کلید خصوصی برای حساب سرویس شما است. از این فایل برای تولید اعتبارنامه‌های OAuth 2.0 جهت اصالت‌سنجی حساب سرویس هنگام برقراری تماس Google Ads API استفاده می‌شود. برای دریافت کلید حساب سرویس، به حساب سرویس نیاز دارید.

پیش‌نیازها

برای برقراری تماس Google Ads API، باید مراحل زیر را تکمیل کنید.

پیکربندی پروژه Cloud برای دسترسی به Google Ads API

پروژه Google Cloud برای مدیریت میاناهای برنامه‌سازی کاربردی Google و اطلاعات کاربری میانای برنامه‌سازی کاربردی OAuth 2.0 استفاده می‌شود. با بازدید از کنسول Google Cloud می‌توانید پروژه‌های Google Cloud موجودتان را پیدا کنید یا پروژه جدیدی ایجاد کنید.

با فعال کردن Google Ads API در پروژه‌تان شروع کنید:

فعال کردن Google Ads API

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

وقتی درخواستتان را تکمیل کردید، Google به‌طور خودکار درخواستتان را بازبینی می‌کند و در بیشتر موارد آن را به «کاوشگر» ارتقا می‌دهد. اگر دسترسی «کاوشگر» به شما اعطا نشده است، نگران نباشید؛ این راهنما دستورالعمل‌های مناسب را هنگام پیکربندی حساب مشتری Google Ads ارائه خواهد داد.

ایجاد حساب سرویس

برای برقراری تماس‌های API، به حساب سرویس و کلید حساب سرویس نیاز دارید. اگر درحال‌حاضر از Google API دیگری استفاده می‌کنید و حساب سرویس OAuth 2.0 و کلید ایجاد کرده‌اید، می‌توانید از این مرحله رد شوید و از اطلاعات کاربری موجود مجدداً استفاده کنید.

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

در کنسول Google Cloud، به «منو» > مدیریت هویت و دسترسی و سرپرست > حساب‌های سرویس بروید.
به «حساب‌های سرویس» بروید
حساب سرویس خود را انتخاب کنید.
روی کلیدها > افزودن کلید > ایجاد کلید جدید کلیک کنید.
JSON را انتخاب کنید، سپس روی ایجاد کلیک کنید.
جفت کلید عمومی/خصوصی جدید شما تولید می‌شود و به‌عنوان فایل جدیدی در دستگاهتان بارگیری می‌شود. فایل JSON بارگیری‌شده را با نام credentials.json در فهرست راهنمای کاری‌تان ذخیره کنید. این فایل تنها نسخه این کلید است. credentials.json را به کنترل نسخه ارسال نکنید (برای مثال، آن را به فایل .gitignore خود اضافه کنید).
روی بستن کلیک کنید.

پیکربندی حساب مشتری Google Ads

با شناسایی حساب Google Ads که در آن فراخوانی‌های میانای برنامه‌سازی کاربردی را انجام می‌دهید شروع کنید. نوع حسابی که می‌توانید برای آن فراخوانی میانای برنامه‌سازی کاربردی انجام دهید به سطح دسترسی به میانای برنامه‌سازی کاربردی پروژه Google Cloud شما بستگی دارد. صفحه نمای کلی Google Ads API خود را بررسی کنید تا سطح دسترسی API خود را پیدا کنید.

سطوح دسترسی کاوشگر، پایه، و استاندارد

می‌توانید با حساب تولید Google Ads خود تماس بگیرید. بااین‌حال، درصورت نیاز می‌توانید با دنبال کردن دستورالعمل‌های برگه دسترسی آزمایشی، حساب آزمایشی Google Ads ایجاد کنید.

دسترسی آزمایشی

از پروژه Google Cloud شما نمی‌توان برای فراخوانی میانای برنامه‌سازی کاربردی به حساب تولید Google Ads استفاده کرد. فقط می‌توانید برای حساب‌های آزمایشی Google Ads فراخوانی میانای برنامه‌سازی کاربردی انجام دهید.

نحوه ایجاد حساب آزمایشی Google Ads

دستورالعمل‌های زیر یک حساب مدیر آزمایشی Google Ads و یک حساب تبلیغ‌کننده آزمایشی Google Ads در زیر آن ایجاد می‌کند.

روی دکمه آبی کلیک کنید تا حساب مدیر آزمایشی Google Ads ایجاد کنید. درصورت درخواست، با «حساب Google» که به حساب مدیر تولید Google Ads شما پیوند داده نشده است به سیستم وارد شوید. اگر حساب ندارید، از دکمه ایجاد حساب در آن صفحه برای ایجاد «حساب Google» جدید استفاده کنید.

ایجاد حساب مدیر آزمایشی Google Ads
وقتی در حساب مدیر آزمایشی Google Ads هستید، حساب مشتری آزمایشی Google Ads ایجاد کنید: روی حساب‌ها > > ایجاد حساب جدید کلیک کنید و فرم را تکمیل کنید. هر حساب Google Ads که از حساب مدیر آزمایشی Google Ads خود ایجاد می‌کنید، به‌طور خودکار حساب آزمایشی Google Ads است.
درصورت تمایل، چند پویش تحت حساب مشتری آزمایشی Google Ads از صفحه Google Ads ایجاد کنید.

برای برقراری تماس API با مشتری Google Ads، باید دسترسی و اجازه‌های مناسب را به حساب سرویس خود برای حساب مشتری Google Ads اعطا کنید. برای انجام این کار، باید دسترسی سرپرست به حساب مشتری داشته باشید.

نحوه اعطای دسترسی حساب سرویس به حساب Google Ads شما

برای شروع، به‌عنوان سرپرست به سیستم حساب Google Ads خود وارد شوید.
به سرپرست > دسترسی و امنیت پیمایش کنید.
روی دکمه در زیر برگه کاربران کلیک کنید.
نشانی ایمیل حساب سرویس را در چارگوش ورودی ایمیل تایپ کنید. سطح دسترسی مناسب به حساب را انتخاب کنید و روی دکمه افزودن حساب کلیک کنید. توجه داشته باشید که سطح دسترسی «ایمیل» برای حساب‌های سرویس پشتیبانی نمی‌شود.
به حساب سرویس دسترسی اعطا می‌شود.
[اختیاری] درطول راه‌اندازی اولیه نمی‌توانید دسترسی سرپرست را به حساب سرویس اعطا کنید. اگر فراخوانی‌های میانای برنامه‌سازی کاربردی شما به دسترسی سرپرست نیاز دارد، می‌توانید دسترسی را به‌صورت زیر ارتقا دهید.
1. روی کلید کرکره‌ای کنار سطح دسترسی حساب سرویس در ستون سطح دسترسی کلیک کنید.
2. سرپرست را از فهرست کرکره‌ای انتخاب کنید.

بارگیری ابزارها و کتابخانه‌های کارخواه

بسته به اینکه چگونه می‌خواهید فراخوانی‌های میانای برنامه‌سازی کاربردی را انجام دهید، می‌توانید کتابخانه کارخواه یا کارخواه HTTP را بارگیری کنید.

استفاده از کتابخانه کارخواه

کتابخانه کارخواه موردنظرتان را بارگیری و نصب کنید.

استفاده از کارخواه HTTP‏ (REST)

curl

curl، ابزار خط فرمان برای انتقال داده ازطریق نشانی وب، را بارگیری و نصب کنید.

میانای خط فرمان Google Cloud

برای نصب gcloud CLI، راهنمای نصب Google Cloud CLI را دنبال کنید.

دستورالعمل‌های بقیه این راهنما برای کار با نسخه زیر از ابزار gcloud تأیید شده‌اند و ممکن است به‌دلیل تفاوت در رفتار برنامه یا گزینه‌های خط فرمان با نسخه‌های قبلی کار نکنند.

:~$ gcloud version
Google Cloud SDK 492.0.0
alpha 2024.09.06
beta 2024.09.06
bq 2.1.8
bundled-python3-unix 3.11.9
core 2024.09.06
enterprise-certificate-proxy 0.3.2
gcloud-crc32c 1.0.0
gsutil 5.30

برقراری تماس API

نکته کلیدی: دستورالعمل‌ها هم به CUSTOMER_ID (شناسه مشتری ۱۰ رقمی حساب مشتری هدف در مسیر نشانی وب درخواست) و هم به تنظیم login_customer_id (یا loginCustomerId / login-customer-id که الزامی است و اگر ازطریق حساب مدیر به حساب مشتری دسترسی پیدا می‌کنید، باید روی شناسه ۱۰ رقمی حساب مدیر تنظیم شود، یا اگر مستقیماً در حساب مشتری اصالت‌سنجی می‌کنید، باید حذف شود) اشاره دارند. شناسه‌های مشتری نباید حاوی خط تیره (خط فاصله) در درخواست‌های API، نشانی‌های وب، یا پیکربندی‌ها باشند (برای مثال، برای جلوگیری از خطای INVALID_CUSTOMER_ID، از 1234567890 به‌جای 123-456-7890 استفاده کنید). برای جزئیات بیشتر، مدل دسترسی Google Ads و ساختار فراخوانی میانای برنامه‌سازی کاربردی را ببینید.

کارخواه موردنظرتان را برای دریافت دستورالعمل‌های مربوط به نحوه برقراری تماس API انتخاب کنید:

جاوا

ساخته‌های کتابخانه کارخواه در مخزن Maven Central منتشر می‌شود.

برای مدیریت نسخه‌های وابستگی و جلوگیری از تداخل، راهنمای فهرست مواد (BOM) Google Ads API را ببینید.

اگر از BOM استفاده نمی‌کنید، کتابخانه کارخواه را مستقیماً بااستفاده از یکی از ابزارهای ساخت زیر به پروژه‌تان اضافه کنید:

Maven: وابستگی زیر را به فایل pom.xml خود اضافه کنید:

<dependency>
  <groupId>com.google.api-ads</groupId>
  <artifactId>google-ads</artifactId>
  <version>48.1.0</version>
</dependency>

Gradle: وابستگی زیر را به فایل build.gradle خود اضافه کنید:

implementation 'com.google.api-ads:google-ads:48.1.0'

فایل ads.properties را در دایرکتوری صفحه اصلی (~/ads.properties در Linux و macOS، یا %USERPROFILE%\ads.properties در Windows) با محتوای زیر ایجاد کنید:

api.googleads.serviceAccountSecretsPath=JSON_KEY_FILE_PATH
api.googleads.loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE

پیش‌از اجرای درخواست‌های API، یک نمونه GoogleAdsClient ایجاد کنید. به‌طور پیش‌فرض، fromPropertiesFile() اطلاعات کاربری را از فایل ads.properties واقع در دایرکتوری صفحه اصلی شما بار می‌کند:

GoogleAdsClient googleAdsClient;
try {
  googleAdsClient = GoogleAdsClient.newBuilder().fromPropertiesFile().build();
} catch (IOException e) {
  System.err.printf("Failed to create GoogleAdsClient: %s%n", e);
  throw new RuntimeException("Initialization failed", e);
}

سپس، گزارش پویش را بااستفاده از GoogleAdsService.SearchStream اجرا کنید تا مجموعه‌های بزرگ نتایج را به‌طور مؤثر جاری‌سازی کنید و پویش‌های موجود در حسابتان را بازیابی کنید:

    private void runExample(GoogleAdsClient googleAdsClient, long customerId) {
  try (GoogleAdsServiceClient googleAdsServiceClient =
      googleAdsClient.getLatestVersion().createGoogleAdsServiceClient()) {
    String query = "SELECT campaign.id, campaign.name FROM campaign ORDER BY campaign.id";
    // Constructs the SearchGoogleAdsStreamRequest.
    SearchGoogleAdsStreamRequest request =
        SearchGoogleAdsStreamRequest.newBuilder()
            .setCustomerId(Long.toString(customerId))
            .setQuery(query)
            .build();

    // Creates and issues a search Google Ads stream request that will retrieve all campaigns.
    ServerStream<SearchGoogleAdsStreamResponse> stream =
        googleAdsServiceClient.searchStreamCallable().call(request);

    // Iterates through and prints all of the results in the stream response.
    for (SearchGoogleAdsStreamResponse response : stream) {
      for (GoogleAdsRow googleAdsRow : response.getResultsList()) {
        System.out.printf(
            "Campaign with ID %d and name '%s' was found.%n",
            googleAdsRow.getCampaign().getId(), googleAdsRow.getCampaign().getName());
      }
    }
  }
}GetCampaigns.java

C#‎

بسته‌های کتابخانه کارخواه در مخزن NuGet.org منتشر می‌شوند. با افزودن مرجع بسته NuGet به بسته Google.Ads.GoogleAds شروع کنید:

dotnet add package Google.Ads.GoogleAds --version 27.6.0

برای برقراری تماس‌های API، یک شیء GoogleAdsConfig از تنظیمات پیکربندی خود (مانند appsettings.json، متغیرهای محیطی، یا تنظیمات سفارشی) ایجاد کنید و آن را برای مقداردهی اولیه یک نمونه GoogleAdsClient ارسال کنید:

GoogleAdsConfig config = new GoogleAdsConfig()
{
    OAuth2Mode = OAuth2Flow.SERVICE_ACCOUNT,
    OAuth2SecretsJsonPath = "JSON_KEY_FILE_PATH",
    LoginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"
};
GoogleAdsClient client = new GoogleAdsClient(config);

سپس، گزارش پویش را بااستفاده از روش GoogleAdsService.SearchStream اجرا کنید تا پویش‌های موجود در حسابتان را بازیابی کنید. این راهنما جزئیات گزارش‌دهی را پوشش نمی‌دهد.

    public void Run(GoogleAdsClient client, long customerId)
{
    // Get the GoogleAdsService.
    GoogleAdsServiceClient googleAdsService = client.GetService(
        Services.V26.GoogleAdsService);

    // Create a query that will retrieve all campaigns.
    string query = @"SELECT
                    campaign.id,
                    campaign.name,
                    campaign.network_settings.target_content_network
                FROM campaign
                ORDER BY campaign.id";

    try
    {
        // Issue a search request.
        googleAdsService.SearchStream(customerId.ToString(), query,
            delegate (SearchGoogleAdsStreamResponse resp)
            {
                foreach (GoogleAdsRow googleAdsRow in resp.Results)
                {
                    Console.WriteLine("Campaign with ID {0} and name '{1}' was found.",
                        googleAdsRow.Campaign.Id, googleAdsRow.Campaign.Name);
                }
            }
        );
    }
    catch (GoogleAdsException e)
    {
        Console.WriteLine("Failure:");
        Console.WriteLine($"Message: {e.Message}");
        Console.WriteLine($"Failure: {e.Failure}");
        Console.WriteLine($"Request ID: {e.RequestId}");
        throw;
    }
}GetCampaigns.cs

PHP

بسته‌های کتابخانه کارخواه در مخزن Packagist منتشر می‌شوند. مطمئن شوید که نسخه PHP سازگار و Composer را نصب کرده‌اید، سپس به دایرکتوری ریشه پروژه‌تان بروید و فرمان زیر را اجرا کنید تا کتابخانه و وابستگی‌های آن در دایرکتوری vendor/ پروژه‌تان نصب شود:

composer require googleads/google-ads-php:35.3.0

نسخه‌ای از فایل google_ads_php.ini را از مخزن GitHub تهیه کنید، آن را در دایرکتوری خانه یا دایرکتوری ریشه پروژه‌تان ذخیره کنید، و آن را اصلاح کنید تا اطلاعات اعتباری‌تان را دربرگیرد:

[GOOGLE_ADS]
loginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"

[OAUTH2]
jsonKeyFilePath = "JSON_KEY_FILE_PATH"
scopes = "https://www.googleapis.com/auth/adwords"

بااستفاده از فایل پیکربندی google_ads_php.ini، نمونه GoogleAdsClient ایجاد کنید:

use Google\Ads\GoogleAds\Lib\OAuth2TokenBuilder;
use Google\Ads\GoogleAds\Lib\V26\GoogleAdsClientBuilder;

$oauth2Credential = (new OAuth2TokenBuilder())
    ->fromFile('/path/to/google_ads_php.ini')
    ->build();

$googleAdsClient = (new GoogleAdsClientBuilder())
    ->fromFile('/path/to/google_ads_php.ini')
    ->withOAuth2Credential($oauth2Credential)
    ->build();

سپس، گزارش پویش را بااستفاده از روش GoogleAdsService.SearchStream اجرا کنید تا پویش‌های موجود در حسابتان را بازیابی کنید:

    public static function runExample(GoogleAdsClient $googleAdsClient, int $customerId)
{
    $googleAdsServiceClient = $googleAdsClient->getGoogleAdsServiceClient();
    // Creates a query that retrieves all campaigns.
    $query = 'SELECT campaign.id, campaign.name FROM campaign ORDER BY campaign.id';
    // Issues a search stream request.
    /** @var GoogleAdsServerStreamDecorator $stream */
    $stream = $googleAdsServiceClient->searchStream(
        SearchGoogleAdsStreamRequest::build($customerId, $query)
    );

    // Iterates over all rows in all messages and prints the requested field values for
    // the campaign in each row.
    foreach ($stream->iterateAllElements() as $googleAdsRow) {
        /** @var GoogleAdsRow $googleAdsRow */
        printf(
            "Campaign with ID %d and name '%s' was found.%s",
            $googleAdsRow->getCampaign()->getId(),
            $googleAdsRow->getCampaign()->getName(),
            PHP_EOL
        );
    }
}GetCampaigns.php

Python

کتابخانه کارخواه Google Ads API برای Python در PyPI توزیع شده است. مطمئن شوید که نسخه پشتیبانی‌شده Python را نصب کرده‌اید، سپس کتابخانه را بااستفاده از pip نصب کنید:

python -m pip install google-ads==35.0.0

برای اصالت‌سنجی کردن فراخوانی‌های میانای برنامه‌سازی کاربردی، فایل google-ads.yaml را پیکربندی کنید:

نسخه‌ای از فایل نمونه google-ads.yaml را از مخزن GitHub بارگیری کنید.
فایل را در دایرکتوری صفحه اصلی (~/google-ads.yaml) یا مسیر سفارشی ذخیره کنید.
google-ads.yaml را باز کنید و آن را به‌روز کنید تا اطلاعات اعتباری‌تان را اضافه کنید:
```
login_customer_id: INSERT_LOGIN_CUSTOMER_ID_HERE
json_key_file_path: JSON_KEY_FILE_PATH
```
ثبت گزارش را قبل‌از مقداردهی اولیه کارخواه پیکربندی کنید تا کتابخانه هرگونه هشدار مقداردهی اولیه یا پیکربندی را ضبط کند. مثال زیر ثبت‌کننده کتابخانه را برای برونداد گزارش‌های INFO به برونداد استاندارد (stdout) پیکربندی می‌کند:

import logging
import sys

logger = logging.getLogger("google.ads.googleads.client")
logger.setLevel(logging.INFO)
logger.addHandler(logging.StreamHandler(sys.stdout))

با فراخوانی روش GoogleAdsClient.load_from_storage و ارسال مسیر به فایل google-ads.yaml، یک نمونه GoogleAdsClient ایجاد کنید:

from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_storage("path/to/google-ads.yaml")

اگر آرگومان مسیر را حذف کنید، load_from_storage() به‌طور پیش‌فرض فایل پیکربندی را در فهرست راهنمای خانه شما (~/google-ads.yaml) جستجو می‌کند.

سپس، گزارش پویش را بااستفاده از روش GoogleAdsService.SearchStream اجرا کنید تا پویش‌های موجود در حسابتان را بازیابی کنید:

    def main(client: GoogleAdsClient, customer_id: str) -> None:
    ga_service: GoogleAdsServiceClient = client.get_service("GoogleAdsService")

    query: str = """
        SELECT
          campaign.id,
          campaign.name
        FROM campaign
        ORDER BY campaign.id"""

    # Issues a search request using streaming.
    stream: Iterator[SearchGoogleAdsStreamResponse] = ga_service.search_stream(
        customer_id=customer_id, query=query
    )

    for batch in stream:
        rows: List[GoogleAdsRow] = batch.results
        for row in rows:
            print(
                f"Campaign with ID {row.campaign.id} and name "
                f'"{row.campaign.name}" was found.'
            )get_campaigns.py

Ruby

Ruby gems برای کتابخانه کارخواه در RubyGems منتشر شده است. مطمئن شوید که نسخه Ruby پشتیبانی‌شده‌ای نصب کرده‌اید و از Bundler برای نصب کتابخانه استفاده کنید:

gem را به Gemfile برنامه‌تان اضافه کنید:
```
gem 'google-ads-googleads', '~> 46.1.0'
```
با اجرای دستور زیر، gem را نصب کنید:
```
bundle install
```

برای پیکربندی اطلاعات اعتباری:

فایل نمونه google_ads_config.rb را از مخزن GitHub کپی کنید.
فایل را در دایرکتوری ریشه پروژه یا دایرکتوری صفحه اصلی (~) ذخیره کنید.
google_ads_config.rb را باز کنید و مقادیر جای‌بان را با اطلاعات کاربری Google Ads API خود جایگزین کنید:
```
Google::Ads::GoogleAds::Config.new do |c|
  c.login_customer_id = 'INSERT_LOGIN_CUSTOMER_ID_HERE'
  c.keyfile = 'JSON_KEY_FILE_PATH'
end
```
با ارسال مسیر به فایل پیکربندی (google_ads_config.rb)، نمونه GoogleAdsClient ایجاد کنید:

client = Google::Ads::GoogleAds::GoogleAdsClient.new(
  'path/to/google_ads_config.rb'
)

سپس، گزارش پویش را بااستفاده از روش GoogleAdsService.SearchStream اجرا کنید تا پویش‌های موجود در حسابتان را بازیابی کنید:

    def get_campaigns(customer_id)
  # GoogleAdsClient will read a config file from
  # ENV['HOME']/google_ads_config.rb when called without parameters
  client = Google::Ads::GoogleAds::GoogleAdsClient.new

  responses = client.service.google_ads.search_stream(
    customer_id: customer_id,
    query: 'SELECT campaign.id, campaign.name FROM campaign ORDER BY campaign.id',
  )

  responses.each do |response|
    response.results.each do |row|
      puts "Campaign with ID #{row.campaign.id} and name '#{row.campaign.name}' was found."
    end
  end
endget_campaigns.rb

پرل

کتابخانه کارخواه Perl در CPAN توزیع می‌شود و به Perl نسخه ۵.۲۸ یا بالاتر و مدیر بسته cpan یا cpanm نیاز دارد.

مخزن google-ads-perl را در دایرکتوری موردنظرتان همسانه‌سازی کنید:
```
git clone https://github.com/googleads/google-ads-perl.git
```
به فهرست راهنمای google-ads-perl بروید و فرمان‌های زیر را اجرا کنید تا وابستگی‌های لازم نصب شود و کتابخانه ساخته شود:
```
cd google-ads-perl
cpan install Module::Build
perl Build.PL
perl Build installdeps
perl Build
perl Build install
```

برای پیکربندی اطلاعات اعتباری:

فایل پیکربندی نمونه را از مخزن GitHub در دایرکتوری خانه (~/googleads.properties) کپی کنید: googleads.properties
```
cp googleads.properties ~/googleads.properties
```
~/googleads.properties را ویرایش کنید تا اطلاعات اعتباری‌تان را اضافه کنید:
```
jsonKeyFilePath=JSON_KEY_FILE_PATH
loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE
```
با ارسال مسیر به فایل googleads.properties پیکربندی‌شده (مانند ~/googleads.properties)، یک نمونه Client ایجاد کنید:

my $api_client = Google::Ads::GoogleAds::Client->new({
  properties_file => "/path/to/googleads.properties"
});

سپس، گزارش پویش را بااستفاده از روش GoogleAdsService.SearchStream اجرا کنید تا پویش‌های موجود در حسابتان را بازیابی کنید:

    sub get_campaigns {
  my ($api_client, $customer_id) = @_;

  # Create a search Google Ads stream request that will retrieve all campaigns.
  my $search_stream_request =
    Google::Ads::GoogleAds::V26::Services::GoogleAdsService::SearchGoogleAdsStreamRequest
    ->new({
      customerId => $customer_id,
      query      =>
        "SELECT campaign.id, campaign.name FROM campaign ORDER BY campaign.id"
    });

  # Get the GoogleAdsService.
  my $google_ads_service = $api_client->GoogleAdsService();

  my $search_stream_handler =
    Google::Ads::GoogleAds::Utils::SearchStreamHandler->new({
      service => $google_ads_service,
      request => $search_stream_request
    });

  # Issue a search request and process the stream response to print the requested
  # field values for the campaign in each row.
  $search_stream_handler->process_contents(
    sub {
      my $google_ads_row = shift;
      printf "Campaign with ID %d and name '%s' was found.\n",
        $google_ads_row->{campaign}{id}, $google_ads_row->{campaign}{name};
    });

  return 1;
}get_campaigns.pl

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

curl

با تنظیم حساب سرویس به‌عنوان اطلاعات اعتباری فعال در gcloud CLI شروع کنید.

gcloud auth login --cred-file=JSON_KEY_FILE_PATH

سپس، کد دسترسی OAuth 2.0 را برای Google Ads API واکشی کنید.

gcloud auth \
  print-access-token \
  --scopes='https://www.googleapis.com/auth/adwords'

فایلی با نام query.json ایجاد کنید که حاوی درخواست «زبان پُرسمان Google Ads» (GAQL) شما باشد:

{
  "query": "SELECT campaign.id, campaign.name, campaign.network_settings.target_content_network FROM campaign ORDER BY campaign.id"
}

بااستفاده از روش GoogleAdsService.SearchStream گزارش پویش را اجرا کنید تا پویش‌های موجود در حسابتان را بازیابی کنید:

curl -i -X POST \
  https://googleads.googleapis.com/v26/customers/CUSTOMER_ID/googleAds:searchStream \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "login-customer-id: LOGIN_CUSTOMER_ID" \
  --data-binary "@query.json"

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

راه‌اندازی سریع با مجموعه‌ها، منظم بمانید ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.

مفاهیم کلیدی

پیش‌نیازها

پیکربندی پروژه Cloud برای دسترسی به Google Ads API

ایجاد حساب سرویس

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

پیکربندی حساب مشتری Google Ads

سطوح دسترسی کاوشگر، پایه، و استاندارد

دسترسی آزمایشی

نحوه ایجاد حساب آزمایشی Google Ads

نحوه اعطای دسترسی حساب سرویس به حساب Google Ads شما

بارگیری ابزارها و کتابخانه‌های کارخواه

استفاده از کتابخانه کارخواه

استفاده از کارخواه HTTP‏ (REST)

برقراری تماس API

جاوا

C#‎

PHP

Python

Ruby

پرل

curl

راه‌اندازی سریع