کتابخانه های مشتری

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

کتابخانه مشتری منبع توزیع مثال‌های کد
جاوا تبلیغات گوگل-جاوا ماون ، tar.gz مشاهده در گیت‌هاب
دات نت تبلیغات گوگل دات نت nuget ، tar.gz، zip مشاهده در گیت‌هاب
پی اچ پی تبلیغات گوگل-php tar.gz مشاهده در گیت‌هاب
پایتون تبلیغات گوگل با پایتون tar.gz، زیپ مشاهده در گیت‌هاب
روبی تبلیغات گوگل-روبی گوهر، tar.gz، فایل زیپ مشاهده در گیت‌هاب
پرل تبلیغات گوگل-پرل tar.gz، زیپ مشاهده در گیت‌هاب

کتابخانه‌های محلی

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

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

نسخه‌های API پشتیبانی‌شده

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

جاوا

کتابخانه کلاینت برای جاوا
v22 Min: 41.0.0
Max: -
v21 Min: 39.0.0
Max: -
v20 Min: 38.0.0
Max: -
v19 Min: 36.0.0
Max: -

سی شارپ

کتابخانه کلاینت برای .NET
v21 Min: 24.1.0
Max: -
v21 Min: 24.0.0
Max: -
v20 Min: 23.0.0
Max: -
v19 Min: 22.1.0
Max: -

پی اچ پی

کتابخانه کلاینت برای PHP
v21 Min: 31.0.0
Max: -
v20 Min: 28.0.0
Max: -
v19 Min: 26.1.0
Max: -
v18 Min: 25.0.0
Max: 30.0.0

پایتون

کتابخانه کلاینت برای پایتون
v22 Min: 28.1.0
Max: -
v21 Min: 28.0.0
Max: -
v20 Min: 27.0.0
Max: -
v19 Min: 25.2.0
Max: -

روبی

کتابخانه کلاینت برای روبی
v22 Min: 36.0.0
Max: -
v21 Min: 35.0.0
Max: -
v20 Min: 34.0.0
Max: -
v19 Min: 32.0.0
Max: -

پرل

کتابخانه کلاینت برای پرل
v22 Min: 29.0.0
Max: -
v21 Min: 28.0.0
Max: -
v20 Min: 27.0.0
Max: -
v19 Min: 26.0.0
Max: -

پیکربندی

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

در اینجا متغیرهای محیطی که برای همه کتابخانه‌های کلاینت مشترک هستند و می‌توانند برای تنظیم تنظیمات پیکربندی بارگذاری شوند، آورده شده است:

  • کتابخانه مشتری
    • GOOGLE_ADS_CONFIGURATION_FILE_PATH : مسیر فایل پیکربندی.
  • OAuth2
    • حالت برنامه
      • GOOGLE_ADS_CLIENT_ID : این مقدار را روی شناسه کلاینت OAuth2 خود تنظیم کنید.
      • GOOGLE_ADS_CLIENT_SECRET : این مقدار را روی رمز کلاینت OAuth2 خود تنظیم کنید.
      • GOOGLE_ADS_REFRESH_TOKEN : اگر می‌خواهید از توکن‌های OAuth2 دوباره استفاده کنید، این مقدار را روی یک توکن رفرش OAuth2 از پیش تولید شده تنظیم کنید. این تنظیم اختیاری است.
    • حالت حساب سرویس
      • GOOGLE_ADS_JSON_KEY_FILE_PATH : این مقدار را روی مسیر فایل پیکربندی OAuth2 JSON تنظیم کنید.
      • GOOGLE_ADS_IMPERSONATED_EMAIL : این مقدار را روی آدرس ایمیل حسابی که جعل هویت می‌کنید، تنظیم کنید.
  • رابط برنامه‌نویسی کاربردی گوگل ادز
    • GOOGLE_ADS_DEVELOPER_TOKEN : این را روی توکن توسعه‌دهنده خود تنظیم کنید.
    • GOOGLE_ADS_LOGIN_CUSTOMER_ID : این شناسه مشتریِ مجاز برای استفاده در درخواست است، بدون خط تیره ( - ).
    • GOOGLE_ADS_LINKED_CUSTOMER_ID : این هدر فقط برای روش‌هایی که منابع یک موجودیت را به‌روزرسانی می‌کنند، در صورت مجوز از طریق حساب‌های مرتبط در رابط کاربری تبلیغات گوگل (منبع AccountLink در 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.
src ~/.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 نتایج را به صورت اندازه‌های ثابت صفحه با 10000 ردیف در هر صفحه برمی‌گرداند.

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

جاوا

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

سی شارپ

public void Run(GoogleAdsClient client, long customerId)
{
    // Get the GoogleAdsService.
    GoogleAdsServiceClient googleAdsService = client.GetService(
        Services.V22.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;
    }
}
      

پی اچ پی

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

پایتون

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

روبی

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

مثال‌های کد

نمونه‌های کد ما از برخی توابع رایج در API تبلیغات گوگل را بررسی کنید .