البدء بسرعة

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

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

  • مشروع Google Cloud: يشكّل مشروع Google Cloud الأساس لإنشاء جميع خدمات Google وتفعيلها واستخدامها، بما في ذلك إدارة واجهات برمجة التطبيقات وبيانات اعتماد OAuth 2.0 API. يمكنك إنشاء مشروع من 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 API. يمكنك العثور على مشاريعك الحالية على Google Cloud أو إنشاء مشروع من خلال الانتقال إلى وحدة تحكّم Google Cloud.

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

تفعيل Google Ads API

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

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

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

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

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

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

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

  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>48.0.0</version>
</dependency>

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

implementation 'com.google.api-ads:google-ads:48.0.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.5.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.V26.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.2.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\V26\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==34.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 gems لمكتبة البرامج على RubyGems. تأكَّد من تثبيت إصدار متوافق من Ruby، واستخدِم Bundler لتثبيت المكتبة:

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

    gem 'google-ads-googleads', '~> 46.0.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::V26::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 CLI.

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/v26/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"

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