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

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

این راهنمای شروع سریع به شما کمک می‌کند اولین تماس میانای برنامه‌سازی کاربردی خود را با «میانای برنامه‌سازی کاربردی Google Ads» برقرار کنید.

مفاهیم کلیدی

پروژه Google Cloud: پروژه Google Cloud مبنای ایجاد، فعال‌سازی، و استفاده از همه سرویس‌های Google، ازجمله مدیریت کردن میاناهای برنامه‌سازی کاربردی و اطلاعات کاربری میانای برنامه‌سازی کاربردی OAuth 2.0 را تشکیل می‌دهد. می‌توانید آن را در کنسول Google Cloud ایجاد کنید.
سطح دسترسی API: سطح دسترسی API پروژه Google Cloud شما تعداد تماس‌های API که می‌توانید در روز برقرار کنید و محیط‌هایی که می‌توانید تماس‌های API برقرار کنید را کنترل می‌کند. سطح دسترسی به میانای برنامه‌سازی کاربردی پروژه شما در صفحه نمای کلی 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 بروید. این صفحه سطح دسترسی API فعلی شما را نمایش می‌دهد. اگر سطح دسترسی میانای برنامه‌سازی کاربردی فعلی شما آزمایشی است، بخش ارتقا دادن سطح دسترسی را ازهم باز کنید. دستورالعمل‌ها را برای درخواست سطح دسترسی کاوشگر دنبال کنید.

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

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

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

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

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

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

با شناسایی حساب Google Ads که برای آن فراخوانی‌های API انجام می‌دهید شروع کنید. نوع حسابی که می‌توانید برای آن فراخوانی میانای برنامه‌سازی کاربردی انجام دهید به سطح دسترسی میانای برنامه‌سازی کاربردی پروژه Google Cloud شما بستگی دارد. برای اطلاع از سطح دسترسی API خود، صفحه نمای کلی Google Ads 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 خود وارد شوید.
به سرپرست > دسترسی و امنیت پیمایش کنید.
روی دکمه در زیر زبانه کاربران کلیک کنید.
نشانی ایمیل حساب سرویس را در چارگوش ورودی ایمیل تایپ کنید. سطح دسترسی مناسب حساب را انتخاب کنید و روی دکمه افزودن حساب کلیک کنید. توجه داشته باشید که سطح دسترسی «ایمیل» برای حساب‌های سرویس پشتیبانی نمی‌شود.
به حساب سرویس دسترسی اعطا شده است.
[اختیاری] درطول راه‌اندازی اولیه نمی‌توانید دسترسی سرپرست به حساب سرویس اعطا کنید. اگر تماس‌های API شما به دسترسی سرپرست نیاز دارد، می‌توانید دسترسی را به روش زیر ارتقا دهید.
1. روی کلید کرکره‌ای کنار سطح دسترسی حساب سرویس در ستون سطح دسترسی کلیک کنید.
2. سرپرست را از فهرست کرکره‌ای انتخاب کنید.

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

بسته به اینکه چگونه می‌خواهید تماس‌های API برقرار کنید، می‌توانید انتخاب کنید که کتابخانه کارخواه یا کارخواه 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.0.0</version>
</dependency>

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

implementation 'com.google.api-ads:google-ads:48.0.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.5.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.2.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==34.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.0.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 5.28 یا بالاتر و مدیر بسته 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
```

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

فایل پیکربندی نمونه googleads.properties را از مخزن GitHub در دایرکتوری اصلی خود (~/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

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