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

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

كما يستخدم هذا الدليل الرموز المميزة لإعادة التحميل، وهي عبارة عن سير عمل يمكن للمستخدم من خلاله الحصول على إذن الوصول إلى حساب "إعلانات 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
``` The `credentials.json` file is from a [previous
step](/google-ads/api/docs/get-started/oauth-cloud-project#id-secret).

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

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

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

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

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

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

واجهة سطر الأوامر gcloud

  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>
``` The `credentials.json` file is from a [previous
step](/google-ads/api/docs/get-started/oauth-cloud-project#id-secret).

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

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

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

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

    ينتقل المتصفّح إلى https://cloud.google.com/sdk/auth_success، ما يشير إلى نجاح المصادقة.

    Authorization code granted. Please 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>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());
      }
    }
  }
}
GetCampaigns.java

#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;
    }
}
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

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

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;
}
get_campaigns.pl

راحة

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