این راهنما به چندین تنظیمات پیش نیاز نیاز دارد که در مراحل قبلی پیکربندی شده اند. اگر این کار را نکرده اید با مقدمه شروع کنید.
این راهنما همچنین از نشانههای تازهسازی استفاده میکند، یک گردش کاری که در آن کاربر با دسترسی کافی به حساب Google Ads میتواند برنامه شما را در یک راهاندازی یکبار اجازه دهد تا تماسهای API آفلاین با حساب را بدون هیچ گونه مداخله کاربر دیگری برقرار کند. میتوانید از نشانههای تازهسازی برای ایجاد گردشهای کاری آفلاین، مانند cron job یا خطوط انتقال داده، و گردشهای کاری تعاملی، مانند برنامههای وب یا تلفن همراه استفاده کنید.
واکشی نشانه تازهسازی
Google Ads API از OAuth 2.0 به عنوان مکانیزم مجوز استفاده می کند. به طور پیش فرض، احراز هویت OAuth 2.0 یک نشانه دسترسی صادر می کند که پس از مدتی محدود منقضی می شود. برای تمدید خودکار رمز دسترسی، به جای آن یک نشانه تازهسازی صادر کنید.
oauth2l
با اجرای ابزار oauth2l توکن رفرش را ایجاد کنید:
oauth2l fetch --credentials credentials.json --scope adwords \ --output_format refresh_token
فایل
credentials.json
مربوط به مرحله قبل است.دستور
oauth2l
یک پنجره ورود به حساب Google را در یک پنجره مرورگر جدید باز می کند و شما را از مراحل احراز هویت OAuth 2.0 عبور می دهد.مطمئن شوید که با استفاده از آدرس ایمیل از مرحله ای که شناسه مشتری ورود به سیستم خود را شناسایی کرده اید، وارد شوید.
اگر برنامه شما تأیید نشده باشد، ممکن است یک صفحه هشدار مشاهده کنید. در چنین مواردی، میتوانید روی پیوند نمایش پیشرفته کلیک کنید و روی گزینه Go to PROJECT_NAME (تأیید نشده) کلیک کنید.
بعد از اینکه دامنه ها را تأیید کردید، با کلیک روی دکمه Continue ، مجوز را اعطا کنید.
اعلانی با متن زیر در مرورگر نمایش داده می شود:
Authorization code granted. Close this tab.
دستور
oauth2l
قطعه JSON زیر را خروجی می دهد:{ "client_id": "******.apps.googleusercontent.com", "client_secret": "******", "token_uri": "https://oauth2.googleapis.com/token", "auth_uri": "https://accounts.google.com/o/oauth2/auth", "refresh_token": "******", "type": "authorized_user" }
gcloud CLI
با اجرای ابزار gcloud CLI، توکن تازهسازی را ایجاد کنید:
gcloud auth application-default \ login --scopes=https://www.googleapis.com/auth/adwords,https://www.googleapis.com/auth/cloud-platform \ --client-id-file=<path_to_credentials.json>
فایل
credentials.json
مربوط به مرحله قبل است.دستور
gcloud
یک پنجره ورود به حساب Google را در یک پنجره مرورگر جدید باز می کند و شما را از مراحل احراز هویت OAuth 2.0 راهنمایی می کند.مطمئن شوید که با استفاده از آدرس ایمیل از مرحله ای که شناسه مشتری ورود به سیستم خود را شناسایی کرده اید، وارد شوید.
اگر برنامه شما تأیید نشده باشد، ممکن است یک صفحه هشدار مشاهده کنید. در چنین مواردی، میتوانید روی پیوند نمایش پیشرفته کلیک کنید و روی گزینه Go to PROJECT_NAME (تأیید نشده) کلیک کنید.
بعد از اینکه دامنه ها را تأیید کردید، برای اعطای مجوز، روی دکمه Continue کلیک کنید.
مرورگر به https://cloud.google.com/sdk/auth_success هدایت می شود که نشان می دهد احراز هویت با موفقیت انجام شده است.
Authorization code granted. Close this tab.
دستور
gcloud
خروجی ای مانند زیر را چاپ می کند:Credentials saved to file: [/****/.config/gcloud/application_default_credentials.json]
حالا فایل
application_default_credentials.json
را باز کنید. محتوای آن باید مشابه موارد زیر باشد:{ "account": "", "client_id": "******.apps.googleusercontent.com", "client_secret": "******", "refresh_token": "******", "type": "authorized_user", "universe_domain": "googleapis.com" }
دیگران
اگر ترجیح می دهید به جای آن از curl
یا کلاینت HTTP خود استفاده کنید، برای مثال به راهنمای OAuth 2.0 for Mobile and Desktop Apps مراجعه کنید.
یک تماس API برقرار کنید
مشتری مورد نظر خود را برای دستورالعملهای نحوه برقراری تماس API انتخاب کنید:
جاوا
مصنوعات کتابخانه مشتری در مخزن مرکزی Maven منتشر می شود. کتابخانه مشتری را به عنوان یک وابستگی به پروژه خود به صورت زیر اضافه کنید:
وابستگی Maven عبارت است از:
<dependency>
<groupId>com.google.api-ads</groupId>
<artifactId>google-ads</artifactId>
<version>34.0.0</version>
</dependency>
وابستگی Gradle عبارت است از:
implementation 'com.google.api-ads:google-ads:34.0.0'
یک فایل ~/ads.properties
با محتوای زیر ایجاد کنید:
api.googleads.clientId=INSERT_CLIENT_ID_HERE
api.googleads.clientSecret=INSERT_CLIENT_SECRET_HERE
api.googleads.refreshToken=INSERT_REFRESH_TOKEN_HERE
api.googleads.developerToken=INSERT_DEVELOPER_TOKEN_HERE
api.googleads.loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE
یک شی GoogleAdsClient
به صورت زیر ایجاد کنید:
GoogleAdsClient googleAdsClient = null;
try {
googleAdsClient = GoogleAdsClient.newBuilder().fromPropertiesFile().build();
} catch (FileNotFoundException fnfe) {
System.err.printf(
"Failed to load GoogleAdsClient configuration from file. Exception: %s%n",
fnfe);
System.exit(1);
} catch (IOException ioe) {
System.err.printf("Failed to create GoogleAdsClient. Exception: %s%n", ioe);
System.exit(1);
}
در مرحله بعد، یک گزارش کمپین را با استفاده از روش GoogleAdsService.SearchStream
اجرا کنید تا کمپین های موجود در حساب خود را بازیابی کنید. این راهنما جزئیات گزارش را پوشش نمی دهد.
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());
}
}
}
}
سی شارپ
بسته های کتابخانه مشتری در مخزن Nuget.org منتشر می شوند. با افزودن یک مرجع nuget به بسته Google.Ads.GoogleAds
شروع کنید.
dotnet add package Google.Ads.GoogleAds --version 18.1.0
یک شی GoogleAdsConfig
با تنظیمات مربوطه ایجاد کنید و از آن برای ایجاد یک شی GoogleAdsClient
استفاده کنید.
GoogleAdsConfig config = new GoogleAdsConfig()
{
DeveloperToken = "******",
OAuth2Mode = "APPLICATION",
OAuth2ClientId = "******.apps.googleusercontent.com",
OAuth2ClientSecret = "******",
OAuth2RefreshToken = "******",
LoginCustomerId = ******
};
GoogleAdsClient client = new GoogleAdsClient(config);
در مرحله بعد، یک گزارش کمپین را با استفاده از روش GoogleAdsService.SearchStream
اجرا کنید تا کمپین های موجود در حساب خود را بازیابی کنید. این راهنما جزئیات گزارش را پوشش نمی دهد.
public void Run(GoogleAdsClient client, long customerId)
{
// Get the GoogleAdsService.
GoogleAdsServiceClient googleAdsService = client.GetService(
Services.V18.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
بسته های کتابخانه مشتری در مخزن Packagist منتشر می شوند. به دایرکتوری ریشه پروژه خود تغییر دهید و دستور زیر را برای نصب کتابخانه و تمام وابستگی های آن در پوشه vendor/
دایرکتوری ریشه پروژه خود اجرا کنید.
composer require googleads/google-ads-php:25.0.0
یک کپی از فایل google_ads_php.ini
از مخزن GitHub تهیه کنید و آن را طوری تغییر دهید که شامل اعتبار شما باشد.
[GOOGLE_ADS]
developerToken = "INSERT_DEVELOPER_TOKEN_HERE"
loginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"
[OAUTH2]
clientId = "INSERT_OAUTH2_CLIENT_ID_HERE"
clientSecret = "INSERT_OAUTH2_CLIENT_SECRET_HERE"
refreshToken = "INSERT_OAUTH2_REFRESH_TOKEN_HERE"
یک نمونه از شی GoogleAdsClient
ایجاد کنید.
$oAuth2Credential = (new OAuth2TokenBuilder())
->fromFile('/path/to/google_ads_php.ini')
->build();
$googleAdsClient = (new GoogleAdsClientBuilder())
->fromFile('/path/to/google_ads_php.ini')
->withOAuth2Credential($oAuth2Credential)
->build();
در مرحله بعد، یک گزارش کمپین را با استفاده از روش GoogleAdsService.SearchStream
اجرا کنید تا کمپین های موجود در حساب خود را بازیابی کنید. این راهنما جزئیات گزارش را پوشش نمی دهد.
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
);
}
}
پایتون
کتابخانه مشتری که در PyPI توزیع شده است را می توان با استفاده از دستور pip
به صورت زیر نصب کرد:
python -m pip install google-ads==21.3.0
یک کپی از فایل google-ads.yaml
از مخزن GitHub تهیه کنید و آن را طوری تغییر دهید که اعتبار شما را در بر بگیرد.
client_id: INSERT_OAUTH2_CLIENT_ID_HERE
client_secret: INSERT_OAUTH2_CLIENT_SECRET_HERE
refresh_token: INSERT_REFRESH_TOKEN_HERE
developer_token: INSERT_DEVELOPER_TOKEN_HERE
login_customer_id: INSERT_LOGIN_CUSTOMER_ID_HERE
با فراخوانی روش GoogleAdsClient.load_from_storage
یک نمونه GoogleAdsClient
ایجاد کنید. هنگام فراخوانی، مسیر google-ads.yaml
خود را به عنوان رشته ای از متد ارسال کنید:
from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_storage("path/to/google-ads.yaml")
در مرحله بعد، یک گزارش کمپین را با استفاده از روش GoogleAdsService.SearchStream
اجرا کنید تا کمپین های موجود در حساب خود را بازیابی کنید. این راهنما جزئیات گزارش را پوشش نمی دهد.
def main(client, customer_id):
ga_service = client.get_service("GoogleAdsService")
query = """
SELECT
campaign.id,
campaign.name
FROM campaign
ORDER BY campaign.id"""
# Issues a search request using streaming.
stream = ga_service.search_stream(customer_id=customer_id, query=query)
for batch in stream:
for row in batch.results:
print(
f"Campaign with ID {row.campaign.id} and name "
f'"{row.campaign.name}" was found.'
)
روبی
سنگهای روبی برای کتابخانه مشتری در سایت میزبانی جواهر Rubygems منتشر شده است. روش توصیه شده برای نصب استفاده از باندلر است. یک خط به Gemfile خود اضافه کنید:
gem 'google-ads-googleads', '~> 30.0.0'
سپس اجرا کنید:
bundle install
یک کپی از فایل google_ads_config.rb
از مخزن GitHub تهیه کنید و آن را طوری تغییر دهید که شامل اعتبار شما باشد.
Google::Ads::GoogleAds::Config.new do |c|
c.client_id = 'INSERT_CLIENT_ID_HERE'
c.client_secret = 'INSERT_CLIENT_SECRET_HERE'
c.refresh_token = 'INSERT_REFRESH_TOKEN_HERE'
c.developer_token = 'INSERT_DEVELOPER_TOKEN_HERE'
c.login_customer_id = 'INSERT_LOGIN_CUSTOMER_ID_HERE'
end
با عبور از مسیری که این فایل را در آن نگهداری می کنید، یک نمونه GoogleAdsClient
ایجاد کنید.
client = Google::Ads::GoogleAds::GoogleAdsClient.new('path/to/google_ads_config.rb')
در مرحله بعد، یک گزارش کمپین را با استفاده از روش GoogleAdsService.SearchStream
اجرا کنید تا کمپین های موجود در حساب خود را بازیابی کنید. این راهنما جزئیات گزارش را پوشش نمی دهد.
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
پرل
کتابخانه بر روی CPAN توزیع شده است. با شبیه سازی مخزن google-ads-perl
در فهرست انتخابی خود شروع کنید.
git clone https://github.com/googleads/google-ads-perl.git
به دایرکتوری google-ads-perl
تغییر دهید و دستور زیر را در خط فرمان اجرا کنید تا تمام وابستگی های مورد نیاز برای استفاده از کتابخانه نصب شود.
cd google-ads-perl
cpan install Module::Build
perl Build.PL
perl Build installdeps
یک کپی از فایل googleads.properties
را از مخزن GitHub تهیه کنید و آن را طوری تغییر دهید که اعتبار شما را در بر بگیرد.
clientId=INSERT_OAUTH2_CLIENT_ID_HERE
clientSecret=INSERT_OAUTH2_CLIENT_SECRET_HERE
refreshToken=INSERT_OAUTH2_REFRESH_TOKEN_HERE
developerToken=INSERT_DEVELOPER_TOKEN_HERE
loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE
با عبور از مسیری که این فایل را در آن نگهداری می کنید، یک نمونه Client
ایجاد کنید.
my $properties_file = "/path/to/googleads.properties";
my $api_client = Google::Ads::GoogleAds::Client->new({
properties_file => $properties_file
});
در مرحله بعد، یک گزارش کمپین را با استفاده از روش GoogleAdsService.SearchStream
اجرا کنید تا کمپین های موجود در حساب خود را بازیابی کنید. این راهنما جزئیات گزارش را پوشش نمی دهد.
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::V18::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;
}
استراحت
با استفاده از یک سرویس گیرنده HTTP برای واکشی نشانه دسترسی OAuth 2.0 شروع کنید. این راهنما از دستور curl
استفاده می کند.
curl \
--data "grant_type=refresh_token" \
--data "client_id=CLIENT_ID" \
--data "client_secret=CLIENT_SECRET" \
--data "refresh_token=REFRESH_TOKEN" \
https://www.googleapis.com/oauth2/v3/token
در مرحله بعد، یک گزارش کمپین را با استفاده از روش GoogleAdsService.SearchStream
اجرا کنید تا کمپین های موجود در حساب خود را بازیابی کنید. این راهنما جزئیات گزارش را پوشش نمی دهد.
curl -i -X POST https://googleads.googleapis.com/v18/customers/CUSTOMER_ID/googleAds:searchStream \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "developer-token: DEVELOPER_TOKEN" \
-H "login-customer-id: LOGIN_CUSTOMER_ID" \
--data-binary "@query.json"
محتویات query.json
به شرح زیر است:
{
"query": "SELECT campaign.id, campaign.name, campaign.network_settings.target_content_network FROM campaign ORDER BY campaign.id"
}