البدء بسرعة

يساعدك دليل البدء السريع هذا في إجراء أول طلب بيانات من Google Ads API.

المفاهيم الرئيسية

  • مشروع Google Cloud: يشكّل مشروع Google Cloud الأساس لإنشاء جميع خدمات Google وتفعيلها واستخدامها، بما في ذلك إدارة واجهات برمجة التطبيقات وبيانات اعتماد واجهة برمجة التطبيقات OAuth 2.0. يمكنك إنشاء مشروع من Google Cloud Console.
  • مستوى الوصول إلى واجهة برمجة التطبيقات: يتحكّم مستوى الوصول إلى واجهة برمجة التطبيقات في مشروعك على Google Cloud في عدد طلبات البيانات من واجهة برمجة التطبيقات التي يمكنك إجراؤها يوميًا والبيئات التي يمكنك إرسال طلبات البيانات إليها. يظهر مستوى الوصول إلى واجهة برمجة التطبيقات في مشروعك في صفحة "نظرة عامة" في Google Ads API الخاصة بمشروعك.
  • الحساب الإداري على "إعلانات Google": يُستخدَم الحساب الإداري على "إعلانات Google" لإدارة حسابات أخرى على "إعلانات Google"، والتي يمكن أن تكون مجموعة من حسابات العملاء على "إعلانات Google" أو حسابات إدارية أخرى على "إعلانات Google".
  • حساب العميل على "إعلانات Google": حساب "إعلانات Google" المستخدَم لعرض الإعلانات التي تريد استهدافها بطلبات البيانات من واجهة برمجة التطبيقات.
  • رقم تعريف عميل الحساب الإداري: هو الرقم المكوّن من 10 أرقام الذي يحدّد حساب عميل على "إعلانات Google". إذا نسخت هذا المعرّف من واجهة مستخدم "إعلانات Google"، احرص على إزالة الشرطات.
  • بروتوكول OAuth 2.0: هو بروتوكول متوافق مع معايير المجال للتفويض، وتستخدمه جميع واجهات Google APIs. تحتاج إلى حساب خدمة ومفتاح لإنشاء بيانات اعتماد OAuth 2.0 من أجل طلب البيانات من واجهة برمجة التطبيقات.
  • حساب الخدمة: هو نوع خاص من حسابات Google التي يملكها تطبيقك وليس مستخدمًا فرديًا. ويُستخدَم هذا الرمز للمصادقة على تطبيقك في Google Ads API. يجب أن يكون لديك مشروع على Google Cloud للحصول على حساب خدمة.
  • مفتاح حساب الخدمة: هو ملف JSON لبيانات اعتماد التطبيق يحتوي على المفتاح الخاص لحساب الخدمة. يُستخدَم لإنشاء بيانات اعتماد OAuth 2.0 للمصادقة على حساب خدمة عند إجراء طلب إلى Google Ads API. يجب توفير حساب خدمة للحصول على مفتاح حساب الخدمة.

المتطلبات الأساسية

لإجراء طلب إلى Google Ads API، عليك إكمال الخطوات التالية.

ضبط مشروعك على السحابة الإلكترونية للوصول إلى Google Ads API

يُستخدَم مشروع Google Cloud لإدارة واجهات Google APIs وبيانات اعتماد واجهة برمجة تطبيقات OAuth 2.0. يمكنك العثور على مشاريعك الحالية على Google Cloud أو إنشاء مشروع جديد من خلال الانتقال إلى وحدة تحكّم Google Cloud.

ابدأ بتفعيل Google Ads API في مشروعك:

تفعيل Google Ads API

بعد ذلك، انتقِل إلى صفحة "نظرة عامة على Google Ads API". تعرض الصفحة مستوى الوصول الحالي إلى واجهة برمجة التطبيقات. إذا كان مستوى الوصول الحالي إلى واجهة برمجة التطبيقات هو اختبار، وسِّع قسم ترقية مستوى الوصول. اتّبِع التعليمات لتقديم طلب للحصول على مستوى الوصول Explorer.

بعد إكمال طلبك، ستراجعه Google تلقائيًا وترقّيه إلى Explorer في معظم الحالات. إذا لم يتم منحك إذن الوصول إلى Explorer، لا تقلق، سيقدّم لك هذا الدليل التعليمات المناسبة عند إعداد حساب عميلك على "إعلانات Google".

إنشاء حساب خدمة

يجب أن يكون لديك حساب خدمة ومفتاح حساب خدمة لإجراء طلبات البيانات من واجهة برمجة التطبيقات. إذا كنت تستخدم حاليًا واجهة برمجة تطبيقات أخرى من Google وأنشأت حساب خدمة ومفتاح OAuth 2.0، يمكنك تخطّي هذه الخطوة وإعادة استخدام بيانات الاعتماد الحالية.

كيفية إنشاء حساب خدمة ومفتاح

  1. في Google Cloud Console، انتقِل إلى "القائمة" > المشرف وإدارة الهوية وإمكانية الوصول > حسابات الخدمة.

    الانتقال إلى حسابات الخدمة

  2. اختَر حساب الخدمة.
  3. انقر على المفاتيح > إضافة مفتاح > إنشاء مفتاح جديد.
  4. اختَر JSON، ثمّ انقر على إنشاء.

    يتم إنشاء زوج المفتاح العام/الخاص الجديد وتنزيله على جهازك كملف جديد. احفظ ملف JSON الذي تم تنزيله باسم credentials.json في دليل العمل. هذا الملف هو النسخة الوحيدة من هذا المفتاح. لا ترسِل credentials.json إلى نظام التحكم في الإصدارات (على سبيل المثال، لا تُضِفها إلى ملف .gitignore).

  5. انقر على إغلاق (Close).

ابدأ بتحديد حساب "إعلانات Google" الذي تريد إرسال طلبات البيانات إلى واجهة برمجة التطبيقات بشأنه. يعتمد نوع الحساب الذي يمكنك إرسال طلبات إلى واجهة برمجة التطبيقات عليه على مستوى الوصول إلى واجهة برمجة التطبيقات في مشروعك على Google Cloud. راجِع صفحة "نظرة عامة" في Google Ads API لمعرفة مستوى الوصول إلى واجهة برمجة التطبيقات.

مستويات الوصول "مستكشف" و"أساسي" و"عادي"

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

إمكانية الوصول إلى الاختبار

لا يمكن استخدام مشروعك على Google Cloud لتقديم طلبات بيانات من واجهة برمجة التطبيقات إلى حساب إنتاج على "إعلانات Google". يمكنك إجراء طلبات البيانات من واجهة برمجة التطبيقات مقابل حسابات الاختبار على "إعلانات Google" فقط.

كيفية إنشاء حساب تجريبي على "إعلانات Google"

تؤدي التعليمات التالية إلى إنشاء حساب إداري تجريبي على "إعلانات Google" وحساب معلِن تجريبي على "إعلانات Google" ضمنه.

  1. انقر على الزر الأزرق لإنشاء حساب إداري تجريبي على "إعلانات Google". إذا طُلب منك ذلك، سجِّل الدخول باستخدام حساب Google غير مرتبط بحسابك الإداري على "إعلانات Google". إذا لم يكن لديك حساب، استخدِم الزر إنشاء حساب في تلك الصفحة لإنشاء حساب جديد على Google.

    إنشاء حساب إداري تجريبي على "إعلانات Google"

  2. أثناء تواجدك في حسابك الإداري التجريبي على "إعلانات Google"، أنشئ حساب عميل تجريبيًا على "إعلانات Google" من خلال النقر على الحسابات > > إنشاء حساب جديد وملء النموذج. أي حسابات على "إعلانات Google" تنشئها من حسابك الإداري التجريبي على "إعلانات Google" ستكون تلقائيًا حسابات تجريبية على "إعلانات Google".
  3. يمكنك اختياريًا إنشاء بعض الحملات ضمن حساب عميل الاختبار على "إعلانات Google" من صفحة "إعلانات Google".

لإجراء طلب بيانات من واجهة برمجة التطبيقات إلى أحد عملاء "إعلانات Google"، يجب منح حساب الخدمة إذن الوصول والأذونات المناسبة إلى حساب العميل على "إعلانات Google". لتنفيذ ذلك، يجب أن يكون لديك إذن وصول إداري إلى حساب العميل.

كيفية منح حساب الخدمة إذن الوصول إلى حسابك على "إعلانات Google"

  1. ابدأ بتسجيل الدخول إلى حسابك على "إعلانات Google" بصفتك مشرفًا.
  2. انتقِل إلى المشرف > الوصول والأمان.
  3. انقر على الزر ضمن علامة التبويب المستخدمون.
    صفحة "الوصول والأمان" في "إعلانات Google" تعرض زر "إضافة مستخدم"
  4. اكتب عنوان البريد الإلكتروني لحساب الخدمة في مربّع الإدخال البريد الإلكتروني. اختَر مستوى الوصول إلى الحساب المناسب وانقر على الزر إضافة حساب. يُرجى العِلم أنّ مستوى الوصول "البريد الإلكتروني" غير متاح لحسابات الخدمة.
    مربّع حوار لإضافة عنوان بريد إلكتروني لحساب خدمة واختيار مستوى الوصول
  5. يتم منح حساب الخدمة إذن الوصول.
    صفحة "الوصول والأمان" التي تعرض حساب الخدمة الذي لديه إذن الوصول
  6. [اختياري] لا يمكنك منح إذن وصول المشرف إلى حساب خدمة أثناء الإعداد الأوّلي. إذا كانت طلبات البيانات من واجهة برمجة التطبيقات تتطلّب إذن وصول المشرف، يمكنك ترقية إذن الوصول باتّباع الخطوات التالية.
    1. انقر على السهم المتّجه للأسفل بجانب مستوى الوصول إلى حساب الخدمة في عمود مستوى الوصول.
    2. اختَر المشرف من القائمة المنسدلة.

تنزيل الأدوات ومكتبات البرامج

يمكنك اختيار تنزيل مكتبة برامج أو عميل HTTP حسب الطريقة التي تريد استخدامها لإجراء طلبات البيانات من واجهة برمجة التطبيقات.

استخدام مكتبة برامج

نزِّل مكتبة برامج من اختيارك وثبِّتها.

استخدام عميل HTTP (REST)

curl

نزِّل وثبِّت curl، وهي أداة سطر الأوامر لنقل البيانات من خلال عنوان URL.

واجهة سطر الأوامر في Google Cloud

اتّبِع دليل تثبيت Google Cloud CLI لتثبيت gcloud CLI.

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

:~$ gcloud version
Google Cloud SDK 492.0.0
alpha 2024.09.06
beta 2024.09.06
bq 2.1.8
bundled-python3-unix 3.11.9
core 2024.09.06
enterprise-certificate-proxy 0.3.2
gcloud-crc32c 1.0.0
gsutil 5.30

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

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

جافا

يتم نشر عناصر مكتبة العميل في مستودع Maven Central.

لإدارة إصدارات التبعيات وتجنُّب التعارضات، يُرجى الاطّلاع على دليل قائمة المواد (BOM) لواجهة برمجة التطبيقات Google Ads API.

إذا كنت لا تستخدم قائمة المواد، أضِف مكتبة العميل مباشرةً إلى مشروعك باستخدام إحدى أدوات الإنشاء التالية:

Maven: أضِف الاعتمادية التالية إلى ملف pom.xml:

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

Gradle: أضِف الاعتمادية التالية إلى ملف build.gradle:

implementation 'com.google.api-ads:google-ads:46.1.0'

أنشئ ملف ads.properties في الدليل الرئيسي (~/ads.properties على نظامَي التشغيل Linux وmacOS، أو %USERPROFILE%\ads.properties على نظام التشغيل Windows) يتضمّن المحتوى التالي:

api.googleads.serviceAccountSecretsPath=JSON_KEY_FILE_PATH
api.googleads.loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE

قبل تنفيذ طلبات واجهة برمجة التطبيقات، أنشئ مثيلاً من GoogleAdsClient. بشكل تلقائي، fromPropertiesFile() يحمّل بيانات الاعتماد من ملف ads.properties الموجود في الدليل الرئيسي:

GoogleAdsClient googleAdsClient;
try {
  googleAdsClient = GoogleAdsClient.newBuilder().fromPropertiesFile().build();
} catch (IOException e) {
  System.err.printf("Failed to create GoogleAdsClient: %s%n", e);
  throw new RuntimeException("Initialization failed", e);
}

بعد ذلك، شغِّل تقرير حملة باستخدام 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. ابدأ بإضافة مرجع حزمة NuGet إلى الحزمة Google.Ads.GoogleAds:

dotnet add package Google.Ads.GoogleAds --version 27.4.0

لإجراء طلبات إلى واجهة برمجة التطبيقات، أنشئ عنصر GoogleAdsConfig من إعدادات الضبط (مثل appsettings.json أو متغيرات البيئة أو الإعدادات المخصّصة) ومرِّره لضبط مثيل GoogleAdsClient:

GoogleAdsConfig config = new GoogleAdsConfig()
{
    OAuth2Mode = OAuth2Flow.SERVICE_ACCOUNT,
    OAuth2SecretsJsonPath = "JSON_KEY_FILE_PATH",
    LoginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"
};
GoogleAdsClient client = new GoogleAdsClient(config);

بعد ذلك، شغِّل تقرير حملة باستخدام طريقة GoogleAdsService.SearchStream لاسترداد الحملات في حسابك. لا يتناول هذا الدليل تفاصيل إعداد التقارير.

    public void Run(GoogleAdsClient client, long customerId)
{
    // Get the GoogleAdsService.
    GoogleAdsServiceClient googleAdsService = client.GetService(
        Services.V25.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. تأكَّد من توفّر إصدار متوافق من PHP وتثبيت Composer، ثم انتقِل إلى الدليل الجذر لمشروعك ونفِّذ الأمر التالي لتثبيت المكتبة والملفات التابعة لها في دليل vendor/ الخاص بمشروعك:

composer require googleads/google-ads-php:35.1.0

أنشئ نسخة من ملف google_ads_php.ini من مستودع GitHub، واحفظها في الدليل الرئيسي أو في الدليل الجذري لمشروعك، وعدِّلها لتضمين بيانات الاعتماد الخاصة بك:

[GOOGLE_ADS]
loginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"

[OAUTH2]
jsonKeyFilePath = "JSON_KEY_FILE_PATH"
scopes = "https://www.googleapis.com/auth/adwords"

أنشئ مثيلاً من GoogleAdsClient باستخدام ملف الإعداد google_ads_php.ini:

use Google\Ads\GoogleAds\Lib\OAuth2TokenBuilder;
use Google\Ads\GoogleAds\Lib\V25\GoogleAdsClientBuilder;

$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

يتم توزيع مكتبة برامج Google Ads API للغة Python على PyPI. تأكَّد من تثبيت إصدار متوافق من Python، ثم ثبِّت المكتبة باستخدام pip:

python -m pip install google-ads==33.0.0

لمصادقة طلبات البيانات من واجهة برمجة التطبيقات، اضبط ملف google-ads.yaml باتّباع الخطوات التالية:

  1. نزِّل نسخة من ملف google-ads.yaml النموذج من مستودع GitHub.
  2. احفظ الملف في الدليل الرئيسي (~/google-ads.yaml) أو في مسار مخصّص.
  3. افتح google-ads.yaml وعدِّله ليشمل بيانات الاعتماد:

    login_customer_id: INSERT_LOGIN_CUSTOMER_ID_HERE
    json_key_file_path: JSON_KEY_FILE_PATH
    

    اضبط إعدادات التسجيل قبل بدء تشغيل العميل حتى تتمكّن المكتبة من تسجيل أي تحذيرات بشأن بدء التشغيل أو الإعداد. يضبط المثال التالي مسجّل المكتبة لعرض سجلات INFO في الإخراج العادي (stdout):

import logging
import sys

logger = logging.getLogger("google.ads.googleads.client")
logger.setLevel(logging.INFO)
logger.addHandler(logging.StreamHandler(sys.stdout))

أنشئ مثيلاً من 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")

في حال عدم تضمين وسيطة المسار، سيبحث load_from_storage() عن ملف الإعداد في الدليل الرئيسي (~/google-ads.yaml) تلقائيًا.

بعد ذلك، شغِّل تقرير حملة باستخدام طريقة GoogleAdsService.SearchStream لاسترداد الحملات في حسابك:

    def main(client: GoogleAdsClient, customer_id: str) -> None:
    ga_service: GoogleAdsServiceClient = client.get_service("GoogleAdsService")

    query: str = """
        SELECT
          campaign.id,
          campaign.name
        FROM campaign
        ORDER BY campaign.id"""

    # Issues a search request using streaming.
    stream: Iterator[SearchGoogleAdsStreamResponse] = ga_service.search_stream(
        customer_id=customer_id, query=query
    )

    for batch in stream:
        rows: List[GoogleAdsRow] = batch.results
        for row in rows:
            print(
                f"Campaign with ID {row.campaign.id} and name "
                f'"{row.campaign.name}" was found.'
            )

Ruby

يتم نشر حِزم Ruby الخاصة بمكتبة البرامج على RubyGems. تأكَّد من تثبيت إصدار متوافق من Ruby، واستخدِم Bundler لتثبيت المكتبة:

  1. أضِف الجوهرة إلى Gemfile في تطبيقك:

    gem 'google-ads-googleads', '~> 45.1.0'
    
  2. ثبِّت الأداة عن طريق تنفيذ الأمر التالي:

    bundle install

لضبط بيانات الاعتماد، اتّبِع الخطوات التالية:

  1. انسخ ملف النموذج google_ads_config.rb من مستودع GitHub.
  2. احفظ الملف في الدليل الجذري لمشروعك أو في الدليل الرئيسي (~).
  3. افتح google_ads_config.rb واستبدِل قيم العناصر النائبة ببيانات اعتماد واجهة برمجة التطبيقات Google Ads API:

    Google::Ads::GoogleAds::Config.new do |c|
      c.login_customer_id = 'INSERT_LOGIN_CUSTOMER_ID_HERE'
      c.keyfile = 'JSON_KEY_FILE_PATH'
    end
    

    أنشئ مثيلاً من GoogleAdsClient عن طريق تمرير المسار إلى ملف الإعداد (google_ads_config.rb):

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

يتم توزيع مكتبة برامج Perl على CPAN وتتطلّب توفّر الإصدار 5.28 أو الإصدارات اللاحقة من Perl، بالإضافة إلى أداة إدارة الحزم cpan أو cpanm.

  1. استنسِخ مستودع google-ads-perl في الدليل الذي تختاره:

    git clone https://github.com/googleads/google-ads-perl.git
  2. انتقِل إلى دليل google-ads-perl ونفِّذ الأوامر التالية لتثبيت الموارد التابعة المطلوبة وإنشاء المكتبة:

    cd google-ads-perl
    cpan install Module::Build
    perl Build.PL
    perl Build installdeps
    perl Build
    perl Build install

لضبط بيانات الاعتماد، اتّبِع الخطوات التالية:

  1. انسخ نموذج ملف الإعداد googleads.properties من مستودع GitHub إلى الدليل الرئيسي (~/googleads.properties):

    cp googleads.properties ~/googleads.properties
  2. عدِّل ~/googleads.properties لتضمين بيانات الاعتماد:

    jsonKeyFilePath=JSON_KEY_FILE_PATH
    loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE
    

    أنشئ مثيلاً من Client عن طريق تمرير المسار إلى ملف googleads.properties الذي تم إعداده (مثل ~/googleads.properties):

my $api_client = Google::Ads::GoogleAds::Client->new({
  properties_file => "/path/to/googleads.properties"
});

بعد ذلك، شغِّل تقرير حملة باستخدام طريقة 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::V25::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;
}

عند تنفيذ النص البرمجي، يتم بث الصفوف المطابقة وطباعة رقم التعريف واسم كل حملة في حسابك.

curl

ابدأ بتعيين حساب الخدمة كبيانات الاعتماد النشطة في واجهة سطر الأوامر gcloud.

gcloud auth login --cred-file=JSON_KEY_FILE_PATH

بعد ذلك، احصل على رمز دخول OAuth 2.0 لواجهة Google Ads API.

gcloud auth \
  print-access-token \
  --scopes='https://www.googleapis.com/auth/adwords'

أنشئ ملفًا باسم query.json يحتوي على طلبك بلغة طلبات البحث في "إعلانات Google" (GAQL):

{
  "query": "SELECT campaign.id, campaign.name, campaign.network_settings.target_content_network FROM campaign ORDER BY campaign.id"
}

نفِّذ تقرير حملة باستخدام طريقة GoogleAdsService.SearchStream لاسترداد الحملات في حسابك:

curl -i -X POST \
  https://googleads.googleapis.com/v25/customers/CUSTOMER_ID/googleAds:searchStream \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "login-customer-id: LOGIN_CUSTOMER_ID" \
  --data-binary "@query.json"

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