کتابخانههای کارخواه Google Ads API نماهای سطح بالا و بلوکهای ساختمانی پایه عملکرد Google Ads API را ارائه میدهند و توسعه سریع برنامهها را آسانتر میکنند. اگر با API آشنا نیستید، با کتابخانه کارخواه شروع کنید.
جدول زیر کتابخانههای رسمی کارخواه و پیوندهای مربوط به راهنماهای راهاندازی، مخازن منبع، بستهها، و نمونه کدهای آنها را فهرست میکند:
کتابخانههای انجمن
ما از چندین کتابخانه که توسط انجمن متنباز نگهداری میشوند مطلع هستیم. ما این فهرست را حفظ میکنیم تا به توسعهدهندگان علاقهمند کمک کنیم آنها را پیدا کنند. ما این کتابخانهها را آزمایش نمیکنیم، در آنها مشارکت نمیکنیم، یا از آنها نگهداری نمیکنیم؛ با مسئولیت خودتان از آنها استفاده کنید. هر سؤالی که ممکن است داشته باشید باید به مالکان پروژههای متنباز ارجاع داده شود.
اگر از کتابخانهای اطلاع دارید که ما آن را ازقلم انداختهایم، روی ارسال بازخورد در بالای صفحه کلیک کنید و به ما اطلاع دهید.
- Node.js:
google-ads-apiدر npm - Go:
google-ads-pbدر GitHub
نسخههای پشتیبانیشده میانای برنامهسازی کاربردی
این جدول نشان میدهد کدام کتابخانههای کارخواه با کدام نسخههای میانای برنامهسازی کاربردی کار میکنند.
حداقل نسخه فهرستشده کتابخانه کارخواه برای نسخه اصلی Google Ads API (مانند v26) کافی است. برای دیدن نسخه کتابخانه مشتری موردنیاز برای نسخههای جزئی، به «گزارش تغییرات» پیوندشده مراجعه کنید.
جاوا
Google Ads API |
کتابخانه کارخواه برای جاوا |
v26 |
Min: 48.0.0Max: - |
v25 |
Min: 44.0.0Max: - |
v24 |
Min: 43.0.0Max: - |
v23 |
Min: 42.0.0Max: - |
C#
Google Ads API |
کتابخانه کارخواه برای NET. |
v26 |
Min: 27.5.0Max: - |
v25 |
Min: 26.1.0Max: - |
v24 |
Min: 25.3.0Max: - |
v23 |
Min: 25.1.0Max: - |
PHP
Google Ads API |
کتابخانه مشتری برای PHP |
v26 |
Min: 35.2.0Max: - |
v25 |
Min: 33.6.0Max: - |
v24 |
Min: 33.3.0Max: - |
v23 |
Min: 32.2.0Max: - |
Python
Google Ads API |
کتابخانه کارخواه برای Python |
v26 |
Min: 34.0.0Max: - |
v25 |
Min: 31.2.0Max: - |
v24 |
Min: 30.1.0Max: - |
v23 |
Min: 29.2.0Max: - |
Ruby
Google Ads API |
کتابخانه کارخواه برای Ruby |
v26 |
Min: 46.0.0Max: - |
v25 |
Min: 43.0.0Max: - |
v24 |
Min: 40.0.0Max: - |
v23 |
Min: 38.0.0Max: - |
پرل
Google Ads API |
کتابخانه مشتری برای Perl |
v26 |
Min: 36.0.0Max: - |
v25 |
Min: 33.0.0Max: - |
v24 |
Min: 32.0.0Max: - |
v23 |
Min: 31.0.0Max: - |
پیکربندی
هر کتابخانه کارخواه 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) اصالتسنجی شود. در Javav41.1.0و نسخههای جدیدتر، Pythonv28.3.0و نسخههای جدیدتر، و Rubyv36.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 بررسی کنید.