إجراء طلب بيانات من واجهة برمجة التطبيقات

يتطلب هذا الدليل العديد من الإعدادات الأساسية التي تم ضبطها في الخطوات السابقة. ابدأ بـ المقدمة إذا أنك لم تفعل ذلك بعد.

كما يستخدم هذا الدليل الرموز المميزة لإعادة التحميل، وهي عبارة عن سير عمل يمكن للمستخدم من خلاله الحصول على حق الوصول إلى حساب إعلانات Google يفوّض تطبيقك - لمرة واحدة - في إعداد إجراء طلبات بيانات من واجهة برمجة التطبيقات بلا اتصال بالإنترنت على الحساب بدون أي تدخل إضافي من المستخدم. يمكنك استخدام الرموز المميّزة لإعادة التحميل لإنشاء عمليات سير عمل بلا اتصال بالإنترنت، مثل مهام cron. أو مسارات البيانات وسير العمل التفاعلي، مثل تطبيقات الويب أو تطبيقات الأجهزة الجوّالة.

استرجاع الرمز المميّز لإعادة التحميل

تستخدم 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.

    تأكَّد من تسجيل الدخول باستخدام عنوان البريد الإلكتروني من الخطوة التي تبدأ بها الذي حدّد الرقم التعريفي لعميل تسجيل الدخول

    إذا لم يتم التحقّق من تطبيقك، قد تظهر لك شاشة تحذير. في مثل هذه الحالات، من الآمن أن تنقر على رابط إظهار الخيارات المتقدمة وتنقر على خيار الانتقال إلى PROJECT_NAME (لم يتم التحقق منه).

  3. بعد التحقق من النطاقات، امنح الإذن بالنقر على زر متابعة

    يظهر طلب في المتصفِّح بالنص التالي:

    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"
    }
    

إجراء طلب بيانات من واجهة برمجة التطبيقات

حدِّد العميل الذي تختاره للحصول على تعليمات حول كيفية إجراء طلب بيانات من واجهة برمجة التطبيقات:

Java

يتم نشر عناصر مكتبة العملاء على Maven Central المستودع. إضافة مكتبة العملاء كتبعية لمشروعك على النحو التالي:

تبعية Maven هي:

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

تبعية Gradle هي:

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

#C

يتم نشر حزم مكتبة العملاء على Nuget.org المستودع. ابدأ بإضافة مرجع موجز إلى حزمة 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.V17.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:22.0.0

أنشئ نسخة من google_ads_php.ini من مستودع جيت هب وتعديله لتضمين بيانات الاعتماد الخاصة بك.

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

Python

يتم توزيع مكتبة البرامج على PyPI. يمكن تثبيته باستخدام الأمر pip على النحو التالي:

python -m pip install google-ads==21.3.0

إنشاء نسخة من google-ads.yaml من مستودع جيت هب وتعديله لتضمين بيانات الاعتماد الخاصة بك.

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 من خلال استدعاء الدالة طريقة GoogleAdsClient.load_from_storage. تمرير المسار إلى 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.'
            )

Ruby

يتم نشر أحجار Ruby لمكتبة العملاء في حجر Rubygems المستضيف. الطريقة الموصى بها للتثبيت هي استخدام أداة حزم البيانات. إضافة سطر إلى Gemfile:

gem 'google-ads-googleads', '~> 30.0.0'

بعد ذلك، شغِّل:

bundle install

أنشئ نسخة من google_ads_config.rb من مستودع جيت هب وتعديله لتضمين بيانات الاعتماد الخاصة بك.

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

Perl

يتم توزيع المكتبة على 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 من مستودع جيت هب وتعديله لتضمين بيانات الاعتماد الخاصة بك.

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::V17::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/v17/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"
}