یک تماس API برقرار کنید

این راهنما به چندین تنظیمات پیش نیاز نیاز دارد که در مراحل قبلی پیکربندی شده اند. اگر این کار را نکرده اید با مقدمه شروع کنید.

این راهنما همچنین از نشانه‌های تازه‌سازی استفاده می‌کند، یک گردش کاری که در آن کاربر با دسترسی کافی به حساب Google Ads می‌تواند برنامه شما را در یک راه‌اندازی یک‌بار اجازه دهد تا تماس‌های API آفلاین با حساب را بدون هیچ گونه مداخله کاربر دیگری برقرار کند. می‌توانید از نشانه‌های تازه‌سازی برای ایجاد گردش‌های کاری آفلاین، مانند cron job یا خطوط انتقال داده، و گردش‌های کاری تعاملی، مانند برنامه‌های وب یا تلفن همراه استفاده کنید.

واکشی نشانه تازه‌سازی

Google Ads API از OAuth 2.0 به عنوان مکانیزم مجوز استفاده می کند. به طور پیش فرض، احراز هویت OAuth 2.0 یک نشانه دسترسی صادر می کند که پس از مدتی محدود منقضی می شود. برای تمدید خودکار نشانه دسترسی، به جای آن باید یک نشانه رفرش صادر کنید.

  1. با اجرای ابزار oauth2l توکن رفرش را ایجاد کنید:

    oauth2l fetch --credentials credentials.json --scope adwords \
    --output_format refresh_token

    فایل credentials.json مربوط به مرحله قبل است.

  2. دستور oauth2l یک پنجره ورود به حساب Google را در یک پنجره مرورگر جدید باز می کند و شما را از مراحل احراز هویت OAuth 2.0 عبور می دهد.

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

    اگر برنامه شما تأیید نشده باشد، ممکن است یک صفحه هشدار مشاهده کنید. در چنین مواردی، می‌توانید روی پیوند نمایش پیشرفته کلیک کنید و روی گزینه Go to PROJECT_NAME (تأیید نشده) کلیک کنید.

  3. بعد از اینکه دامنه ها را تأیید کردید، با کلیک روی دکمه Continue ، مجوز را اعطا کنید.

    اعلانی با متن زیر در مرورگر نمایش داده می شود:

    Authorization code granted. Please 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"
}

یک تماس API برقرار کنید

مشتری مورد نظر خود را برای دستورالعمل‌های نحوه برقراری تماس API انتخاب کنید:

جاوا

مصنوعات کتابخانه مشتری در مخزن مرکزی Maven منتشر می شود. کتابخانه مشتری را به عنوان یک وابستگی به پروژه خود به صورت زیر اضافه کنید:

وابستگی Maven عبارت است از:

<dependency>
  <groupId>com.google.api-ads</groupId>
  <artifactId>google-ads</artifactId>
  <version>31.0.0</version>
</dependency>

وابستگی Gradle عبارت است از:

implementation 'com.google.api-ads:google-ads:31.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());
      }
    }
  }
}
GetCampaigns.java

سی شارپ

بسته های کتابخانه مشتری در مخزن 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.V16.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;
    }
}
GetCampaigns.cs

PHP

بسته های کتابخانه مشتری در مخزن Packagist منتشر می شوند. به دایرکتوری ریشه پروژه خود تغییر دهید و دستور زیر را برای نصب کتابخانه و تمام وابستگی های آن در پوشه vendor/ دایرکتوری ریشه پروژه خود اجرا کنید.

composer require googleads/google-ads-php:22.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
        );
    }
}
GetCampaigns.php

پایتون

کتابخانه مشتری که در 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.'
            )
get_campaigns.py

روبی

سنگهای روبی برای کتابخانه مشتری در سایت میزبانی جواهر Rubygems منتشر شده است. روش توصیه شده برای نصب استفاده از باندلر است. یک خط به Gemfile خود اضافه کنید:

gem 'google-ads-googleads', '~> 23.1.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
get_campaigns.rb

پرل

کتابخانه بر روی 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::V16::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;
}
get_campaigns.pl

باقی مانده

با استفاده از یک سرویس گیرنده 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/v16/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"
}
قبلی
دانلود ابزارها و کتابخانه ها
بعدی
خطاهای رایج