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

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

جدول زیر کتابخانه‌های رسمی کارخواه و پیوندهای مربوط به راهنماهای راه‌اندازی، مخازن منبع، بسته‌ها، و نمونه کدهای آن‌ها را فهرست می‌کند:

کتابخانه مشتری راهنماهای راه‌اندازی و استفاده منبع توزیع نمونه‌های کد
جاوا استفاده پایه، پیکربندی، اصالت‌سنجی، ورود به سیستم، ماسک‌های فیلد، نام‌های منبع google-ads-java Maven،‏ tar.gz،‏ zip مشاهده در GitHub
.NET استفاده پایه، پیکربندی، اصالت‌سنجی، ثبت کردن، ماسک‌های فیلد، نام‌های منبع google-ads-dotnet NuGet، tar.gz، zip مشاهده در GitHub
PHP استفاده پایه، پیکربندی، اصالت‌سنجی، ثبت کردن، ماسک‌های فیلد، نام‌های منبع google-ads-php Composer،‏ tar.gz،‏ zip مشاهده در GitHub
Python Installation, Configuration, Authentication, Logging, Field masks, Resource names google-ads-python PyPI، tar.gz، zip مشاهده در GitHub
یاقوت سرخ استفاده پایه، پیکربندی، اصالت‌سنجی، ورود به سیستم، ماسک‌های فیلد، نام‌های منبع google-ads-ruby RubyGems،‏ tar.gz،‏ zip مشاهده در GitHub
Perl استفاده پایه، پیکربندی، اصالت‌سنجی، ورود به سیستم، ماسک‌های فیلد، نام‌های منبع google-ads-perl CPAN، tar.gz، zip مشاهده در GitHub

کتابخانه‌های انجمن

ما از چندین کتابخانه که توسط انجمن متن‌باز نگهداری می‌شوند مطلع هستیم. ما این فهرست را حفظ می‌کنیم تا به توسعه‌دهندگان علاقه‌مند کمک کنیم آن‌ها را پیدا کنند. ما این کتابخانه‌ها را آزمایش نمی‌کنیم، در آن‌ها مشارکت نمی‌کنیم، یا از آن‌ها نگهداری نمی‌کنیم؛ با مسئولیت خودتان از آن‌ها استفاده کنید. هر سؤالی که ممکن است داشته باشید باید به مالکان پروژه‌های متن‌باز ارجاع داده شود.

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

نسخه‌های پشتیبانی‌شده میانای برنامه‌سازی کاربردی

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

حداقل نسخه فهرست‌شده کتابخانه کارخواه برای نسخه اصلی Google Ads API (مانند v26) کافی است. برای دیدن نسخه کتابخانه مشتری موردنیاز برای نسخه‌های جزئی، به «گزارش تغییرات» پیوندشده مراجعه کنید.

جاوا

گزارش تغییرات

کتابخانه کارخواه برای جاوا
v26 Min: 48.0.0
Max: -
v25 Min: 44.0.0
Max: -
v24 Min: 43.0.0
Max: -
v23 Min: 42.0.0
Max: -

C#‎

گزارش تغییرات

کتابخانه کارخواه برای NET.
v26 Min: 27.5.0
Max: -
v25 Min: 26.1.0
Max: -
v24 Min: 25.3.0
Max: -
v23 Min: 25.1.0
Max: -

PHP

گزارش تغییرات

کتابخانه مشتری برای PHP
v26 Min: 35.2.0
Max: -
v25 Min: 33.6.0
Max: -
v24 Min: 33.3.0
Max: -
v23 Min: 32.2.0
Max: -

Python

گزارش تغییرات

کتابخانه کارخواه برای Python
v26 Min: 34.0.0
Max: -
v25 Min: 31.2.0
Max: -
v24 Min: 30.1.0
Max: -
v23 Min: 29.2.0
Max: -

Ruby

گزارش تغییرات

کتابخانه کارخواه برای Ruby
v26 Min: 46.0.0
Max: -
v25 Min: 43.0.0
Max: -
v24 Min: 40.0.0
Max: -
v23 Min: 38.0.0
Max: -

پرل

گزارش تغییرات

کتابخانه مشتری برای Perl
v26 Min: 36.0.0
Max: -
v25 Min: 33.0.0
Max: -
v24 Min: 32.0.0
Max: -
v23 Min: 31.0.0
Max: -

پیکربندی

هر کتابخانه کارخواه Google Ads API تنظیمات پیکربندی و روش‌های بارگیری متفاوتی ارائه می‌دهد که می‌توانید از آن‌ها برای سفارشی‌سازی رفتار آن استفاده کنید.

در اینجا متغیرهای محیطی استانداردی که می‌توانید برای پیکربندی کتابخانه‌های کارخواه استفاده کنید آورده شده است:

  • کتابخانه مشتری
    • ‫GOOGLE_ADS_CONFIGURATION_FILE_PATH: مسیر فایل پیکربندی (هنگام بار کردن از فایل پیکربندی بدون شناسه مسیر صریح در Java (fromPropertiesFile())،‏ Perl (Client->new())،‏ PHP (fromFile())،‏ Python (load_from_storage()، و همچنین بررسی‌شده توسط load_from_env())، و Ruby (GoogleAdsClient.new) به‌طور خودکار خوانده می‌شود؛ در .NET، این متغیر را به‌طور صریح بااستفاده از config.TryLoadFromEnvironmentFilePath بار کنید یا فایل‌های پیکربندی را بااستفاده از LoadFromSettingsJson،‏ LoadFromConfigurationSection، یا LoadFromConfigurationRoot بار کنید).
  • OAuth2
    • حالت برنامه
      • ‫GOOGLE_ADS_CLIENT_ID: این مقدار را روی شناسه کارخواه OAuth2 خودتان تنظیم کنید.
      • GOOGLE_ADS_CLIENT_SECRET: این مقدار را روی رمز کارخواه OAuth2 خود تنظیم کنید.
      • GOOGLE_ADS_REFRESH_TOKEN: اگر می‌خواهید از کدهای OAuth2 مجدداً استفاده کنید، این مقدار را روی کد بازآوری OAuth2 ازپیش تولیدشده تنظیم کنید. این تنظیم اختیاری است.
    • حالت حساب سرویس
      • GOOGLE_ADS_JSON_KEY_FILE_PATH: این مقدار را روی مسیر فایل کلید JSON مربوط به OAuth2 تنظیم کنید (در .NET، همچنین GOOGLE_ADS_OAUTH2_MODE را روی SERVICE_ACCOUNT تنظیم کنید، زیرا OAuth2Mode به‌طور پیش‌فرض روی APPLICATION تنظیم شده است؛ در نسخه‌های PHP قدیمی‌تر از v32.1.0 یا هنگام استفاده از دامنه‌های سفارشی، همچنین [OAUTH2] scopes را در google_ads_php.ini تنظیم کنید یا withScopes() را فراخوانی کنید، زیرا fromEnvironmentVariables() دامنه‌های OAuth2 را از متغیر محیطی نمی‌خواند).
      • GOOGLE_ADS_IMPERSONATED_EMAIL: این مقدار را روی نشانی ایمیل حسابی تنظیم کنید که هنگام استفاده از واگذاری در سطح دامنه Google Workspace، خود را به‌جای آن جا می‌زنید. این تنظیم اختیاری است.
    • حالت «اعتبارنامه پیش‌فرض برنامه»
      • GOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS: این مقدار را روی true تنظیم کنید تا بااستفاده از «اعتبارنامه پیش‌فرض برنامه» (ADC) اصالت‌سنجی شود. در Java v41.1.0 و نسخه‌های جدیدتر، Python v28.3.0 و نسخه‌های جدیدتر، و Ruby v36.1.0 و نسخه‌های جدیدتر پشتیبانی می‌شود (در NET .v24.1.0 و نسخه‌های جدیدتر، LoadFromEnvironmentVariables() به‌جای آن متغیر بدون پیشوند USE_APPLICATION_DEFAULT_CREDENTIALS را می‌خواند، یا UseApplicationDefaultCredentials = true را در GoogleAdsConfig تنظیم می‌کند؛ در PHP، وقتی هیچ اطلاعات کاربری OAuth2 صریحی تنظیم نشده باشد، OAuth2TokenBuilder به‌طور خودکار به ADC برمی‌گردد؛ Perl از ADC پشتیبانی نمی‌کند).
  • Google Ads API
    • GOOGLE_ADS_LOGIN_CUSTOMER_ID: این شناسه مشتریِ مشتری مجاز برای استفاده در درخواست است، بدون خط تیره (-).
    • GOOGLE_ADS_LINKED_CUSTOMER_ID: این سرصفحه فقط برای روش‌هایی لازم است که منابع نهاد را هنگام صدور مجوز ازطریق «حساب‌های پیوندشده» در میانای کاربری Google Ads (منبع AccountLink در Google Ads API) به‌روز می‌کنند. این مقدار را روی شناسه مشتری ارائه‌دهنده داده‌ای تنظیم کنید که منابع شناسه مشتری مشخص‌شده را به‌روز می‌کند. باید بدون خط تیره (-) تنظیم شود. برای کسب اطلاعات بیشتر درباره «حساب‌های پیوندشده»، به مرکز راهنمایی مراجعه کنید.

متغیرهای محیطی معمولاً در فایل پیکربندی bash تعریف می‌شوند، مثل فایل .bashrc یا .bash_profile که در دایرکتوری $HOME قرار دارد. همچنین می‌توان آن‌ها را بااستفاده از خط فرمان تعریف کرد.

در اینجا چند مرحله اصلی برای تعریف متغیر محیطی بااستفاده از فایل .bashrc بااستفاده از پایانه آورده شده است:

# Append the line "export GOOGLE_ADS_CLIENT_ID=1234567890" to
# the bottom of your .bashrc file.
echo "export GOOGLE_ADS_CLIENT_ID=1234567890" >> ~/.bashrc

# Update your bash environment to use the most recently updated
# version of your .bashrc file.
source ~/.bashrc

متغیرهای محیطی را می‌توان مستقیماً از خط فرمان در نمونه پایانه نیز تنظیم کرد:

export GOOGLE_ADS_CLIENT_ID=1234567890

راه دیگر این است که متغیرهای محیطی را هنگام فراخوانی فرمانی که از آن‌ها استفاده می‌کند تنظیم کنید:

GOOGLE_ADS_CLIENT_ID=1234567890 php /path/to/script/that/uses/envvar.php

واکشی نهادها

GoogleAdsService.SearchStream معمولاً برای واکشی نهادها استفاده می‌شود و نتایج به‌صورت جریانی از ردیف‌ها برگردانده می‌شود. یا می‌توانید از GoogleAdsService.Search برای واکشی نهادها ازطریق اتصال اینترنت غیرقابل‌اعتماد استفاده کنید. GoogleAdsService.Search نتایج را به‌صورت اندازه صفحه ثابت ۱۰٬۰۰۰ ردیف در هر صفحه برمی‌گرداند.

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

جاوا

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());
      }
    }
  }
}
      

C#‎

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;
    }
}
      

PHP

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
        );
    }
}
      

Python

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.'
            )
      

Ruby

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
end
      

پرل

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;
}
      

curl

نمونه‌های کد

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