کتابخانههای کلاینت ما نماهای سطح بالا و بلوکهای سازندهی اولیهی عملکرد API گوگل ادز را ارائه میدهند و توسعهی سریع برنامهها را آسانتر میکنند. اگر در استفاده از API تازهکار هستید، توصیه میکنیم با یکی از آنها شروع کنید.
کتابخانههای محلی
ما از وجود چندین کتابخانه که توسط جامعه متنباز نگهداری میشوند، آگاه هستیم. ما این لیست را برای کمک به توسعهدهندگان علاقهمند در یافتن آنها تهیه کردهایم. ما این کتابخانهها را آزمایش، توسعه یا نگهداری نمیکنیم؛ استفاده از آنها با مسئولیت خودتان است. هرگونه سؤالی که دارید باید با مالکان پروژههای متنباز در میان بگذارید.
اگر از کتابخانهای اطلاع دارید که ما آن را از قلم انداختهایم، روی ارسال بازخورد در بالای صفحه کلیک کنید و به ما اطلاع دهید.
نسخههای 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 تبلیغات گوگل را بررسی کنید .