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

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

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

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

تستخدم Google Ads API بروتوكول OAuth 2.0 كآلية تفويض. تُصدر مصادقة OAuth 2.0 تلقائيًا رمز دخول تنتهي صلاحيته بعد فترة زمنية محدودة. لتجديد رمز الوصول تلقائيًا، يمكنك إصدار رمز إعادة تحميل بدلاً من ذلك.

oauth2l

  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. 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

  1. أنشئ الرمز المميّز لإعادة التحميل من خلال تشغيل أداة 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 من خطوة سابقة.

  2. يفتح الأمر gcloud نافذة تسجيل الدخول إلى حساب Google في نافذة متصفّح جديدة وينقلك خلال خطوات مصادقة OAuth 2.0.

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

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

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

    ينتقل المتصفّح إلى 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 لتطبيقات الأجهزة الجوّالة وأجهزة الكمبيوتر المكتبي للحصول على مثال.

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

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

Java

يتم نشر عناصر مكتبة العميل في مستودع Maven central. أضِف مكتبة العميل كمكتبة يعتمد عليها مشروعك على النحو التالي:

تبعية 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());
      }
    }
  }
}
GetCampaigns.java

#C

يتم نشر حِزم مكتبة العميل في مستودع 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;
    }
}
GetCampaigns.cs

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
        );
    }
}
GetCampaigns.php

Python

يتم توزيع مكتبة العميل على 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 من خلال استدعاء الأسلوب 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.'
            )
get_campaigns.py

Ruby

يتم نشر ملفات Rubygems الخاصة بمكتبة العميل على موقع استضافة ملف 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
get_campaigns.rb

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 من مستودع 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;
}
get_campaigns.pl

REST

ابدأ باستخدام برنامج HTTP client لاسترداد رمز دخول 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"
}
السابق
تنزيل الأدوات والمكتبات
التالي
الأخطاء الشائعة