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

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

کتابخانه مشتری منبع توزیع نمونه‌های کد
Java 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 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» (مثل v26) کافی است. برای دیدن نسخه کتابخانه مشتری موردنیاز برای نسخه‌های جزئی، به «گزارش تغییرات» پیوندشده مراجعه کنید.

جاوا

Changelog

کتابخانه کارخواه برای جاوا
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

Changelog

کتابخانه کارخواه برای 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: -

پرل

Changelog

کتابخانه کارخواه برای 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.V25.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::V25::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 بررسی کنید.