البدء

يمكنك استخدام واجهة برمجة تطبيقات "مدير إعلانات Google" لإنشاء التطبيقات التي تدير المستودع الإعلاني وتُنشئ الطلبات وسحب التقارير وغير ذلك.

تستخدِم واجهة برمجة تطبيقات "مدير الإعلانات" نطاق SOAP. لمساعدتك على البدء، نقدّم مكتبات للعملاء للغة Java و .NET وPython وPHP وRuby.

لإجراء أول طلب من واجهة برمجة التطبيقات، اتّبِع الخطوات التالية:

الوصول إلى شبكة على "مدير الإعلانات"

إذا لم يكن لديك حساب، اشترِك للحصول على حساب على "مدير الإعلانات". يمكنك أيضًا إنشاء شبكة اختبار إذا كنت تريد اختبار واجهة برمجة التطبيقات في بيئة منفصلة. لاحظ أنك لا تحتاج إلى حساب AdSense لأغراض الاختبار.

دوِّن رمز الشبكة. يمكنك العثور عليه في عنوان URL عند تسجيل الدخول إلى شبكتك. على سبيل المثال، في عنوان URL https://admanager.google.com/1234#home، يكون الرمز 1234 هو رمز الشبكة.

إنشاء بيانات اعتماد المصادقة

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

  1. افتح صفحة بيانات اعتماد وحدة تحكم واجهة Google API.

  2. من قائمة المشروع، اختَر إنشاء مشروع وأدخِل اسمًا للمشروع، ويمكنك تعديل رقم تعريف المشروع المقدَّم إذا أردت. انقر على إنشاء.

  3. في صفحة "بيانات الاعتماد"، اختَر إنشاء بيانات اعتماد، ثم اختَر مفتاح حساب الخدمة.

  4. اختَر حساب خدمة جديد واختَر JSON كنوع المفتاح.

  5. انقر على إنشاء لتنزيل ملف يحتوي على مفتاح خاص.

إعداد شبكة "مدير الإعلانات"

  1. سجِّل الدخول إلى "مدير إعلانات Google"

  2. في الشريط الجانبي، انقر على المشرف > الإعدادات العامة.

  3. ضمن الإعدادات العامة > الوصول إلى واجهة برمجة التطبيقات، انقر على شريط التمرير مفعَّل.

  4. انقر على الزر حفظ في أسفل الصفحة.

إعداد البرنامج

نزِّل إحدى مكتبات عملاء "مدير الإعلانات". توفّر المكتبات وظائف وميزات تضمين تجعل عملية تطوير التطبيقات أسهل وأسرع.

توفر علامات التبويب أدناه انطلاقات سريعة للترميز بكل لغة من اللغات التي توجد بها مكتبة برامج.

Java

إليك مثال أساسي يوضّح كيفية استخدام مكتبة عميل Java. للحصول على معلومات أكثر تفصيلاً عن الاستخدام، يمكنك الرجوع إلى ملف README في توزيع مكتبة البرامج.

  1. إعداد بيانات الاعتماد

    نفِّذ الأمر التالي في واجهة الأوامر:

    curl https://raw.githubusercontent.com/googleads/googleads-java-lib/main/examples/admanager_axis/src/main/resources/ads.properties -o ~/ads.properties
    افتح ملف ~/ads.properties واملأ الحقول التالية:
    [...]
    api.admanager.applicationName=INSERT_APPLICATION_NAME_HERE
    api.admanager.jsonKeyFilePath=INSERT_PATH_TO_JSON_KEY_FILE_HERE
    api.admanager.networkCode=INSERT_NETWORK_CODE_HERE
    [...]
  2. تحديد التبعيات

    عدِّل ملف pom.xml وأضِف ما يلي إلى العلامة dependencies. يمكنك العثور على أحدث رقم إصدار على جيت هب.

    <dependency>
      <groupId>com.google.api-ads</groupId>
      <artifactId>ads-lib</artifactId>
      <version>RELEASE</version>
    </dependency>
    <dependency>
      <groupId>com.google.api-ads</groupId>
      <artifactId>dfp-axis</artifactId>
      <version>RELEASE</version>
    </dependency>

  3. كتابة بعض الرموز وتقديم طلب

    import com.google.api.ads.common.lib.auth.OfflineCredentials;
    import com.google.api.ads.common.lib.auth.OfflineCredentials.Api;
    import com.google.api.ads.admanager.axis.factory.AdManagerServices;
    import com.google.api.ads.admanager.axis.v202402.Network;
    import com.google.api.ads.admanager.axis.v202402.NetworkServiceInterface;
    import com.google.api.ads.admanager.lib.client.AdManagerSession;
    import com.google.api.client.auth.oauth2.Credential;
    
    public class App {
      public static void main(String[] args) throws Exception {
        Credential oAuth2Credential = new OfflineCredentials.Builder()
            .forApi(Api.AD_MANAGER)
            .fromFile()
            .build()
            .generateCredential();
    
        // Construct an AdManagerSession.
        AdManagerSession session = new AdManagerSession.Builder()
            .fromFile()
            .withOAuth2Credential(oAuth2Credential)
            .build();
    
        // Construct a Google Ad Manager service factory, which can only be used once per
        // thread, but should be reused as much as possible.
        AdManagerServices adManagerServices = new AdManagerServices();
    
        // Retrieve the appropriate service
        NetworkServiceInterface networkService = adManagerServices.get(session,
            NetworkServiceInterface.class);
    
        // Make a request
        Network network = networkService.getCurrentNetwork();
    
        System.out.printf("Current network has network code '%s' and display" +
            " name '%s'.%n", network.getNetworkCode(), network.getDisplayName());
      }
    }
    

Python

إليك مثال أساسي يوضّح كيفية استخدام مكتبة برامج Python. تتوافق مكتبة برامج Python مع الإصدار 3.6 أو الإصدارات الأحدث من لغة Python. للحصول على معلومات أكثر تفصيلاً عن الاستخدام، راجع ملف README في توزيع مكتبة البرامج.

  1. ثبِّت المكتبة واضبط بيانات الاعتماد.

    يمكنك تشغيل الأوامر التالية في واجهة الأوامر:

    pip install googleads
    curl https://raw.githubusercontent.com/googleads/googleads-python-lib/main/googleads.yaml \
         -o ~/googleads.yaml
    
  2. إعداد ملف ~/googleads.yaml

    املأ الحقول التالية:

    ad_manager:
      application_name: INSERT_APPLICATION_NAME_HERE
      network_code: INSERT_NETWORK_CODE_HERE
      path_to_private_key_file: INSERT_PATH_TO_FILE_HERE
    
  3. نفِّذ بعض الرموز وقدِّم طلبًا.
    # Import the library.
    from googleads import ad_manager
    
    # Initialize a client object, by default uses the credentials in ~/googleads.yaml.
    client = ad_manager.AdManagerClient.LoadFromStorage()
    
    # Initialize a service.
    network_service = client.GetService('NetworkService', version='v202402')
    
    # Make a request.
    current_network = network_service.getCurrentNetwork()
    
    print("Current network has network code '%s' and display name '%s'." %
            (current_network['networkCode'], current_network['displayName']))
    

PHP

إليك مثال أساسي يوضّح كيفية استخدام مكتبة عملاء PHP.

  1. تثبيت المكتبة وإعداد بيانات الاعتماد

    شغِّل الأوامر التالية في واجهة أوامر لتثبيت مكتبة العملاء وتنزيل ملف adsapi_php.ini في الدليل الرئيسي:

    composer require googleads/googleads-php-lib
    curl https://raw.githubusercontent.com/googleads/googleads-php-lib/main/examples/AdManager/adsapi_php.ini -o ~/adsapi_php.ini
  2. إعداد ملف ~/adsapi_php.ini

    املأ الحقول التالية:

    [AD_MANAGER]
    networkCode = "INSERT_NETWORK_CODE_HERE"
    applicationName = "INSERT_APPLICATION_NAME_HERE"
    
    [OAUTH2]
    jsonKeyFilePath = "INSERT_ABSOLUTE_PATH_TO_OAUTH2_JSON_KEY_FILE_HERE"
    scopes = "https://www.googleapis.com/auth/dfp"
    
  3. تنفيذ بعض الرموز وتقديم طلب
    <?php
    require 'vendor/autoload.php';
    use Google\AdsApi\AdManager\AdManagerSession;
    use Google\AdsApi\AdManager\AdManagerSessionBuilder;
    use Google\AdsApi\AdManager\v202402\ApiException;
    use Google\AdsApi\AdManager\v202402\ServiceFactory;
    use Google\AdsApi\Common\OAuth2TokenBuilder;
    
    // Generate a refreshable OAuth2 credential for authentication.
    $oAuth2Credential = (new OAuth2TokenBuilder())
        ->fromFile()
        ->build();
    // Construct an API session configured from a properties file and the OAuth2
    // credentials above.
    $session = (new AdManagerSessionBuilder())
        ->fromFile()
        ->withOAuth2Credential($oAuth2Credential)
        ->build();
    
    // Get a service.
    $serviceFactory = new ServiceFactory();
    $networkService = $serviceFactory->createNetworkService($session);
    
    // Make a request
    $network = $networkService->getCurrentNetwork();
    printf(
        "Network with code %d and display name '%s' was found.\n",
        $network->getNetworkCode(),
        $network->getDisplayName()
    );
    

NET.

في ما يلي مثال أساسي يوضّح كيفية استخدام مكتبة برامج.NET

  1. إنشاء مشروع جديد

    افتح Visual Studio وأنشئ مشروعًا جديدًا (تطبيق Console).

  2. إضافة مراجع المكتبة المطلوبة إلى مشروعك

    أضِف تبعية لـ Google.Dfp.

  3. إعداد App.config

    انسخ src\App.config إلى دليل مشروعك وأضفه إلى مشروعك. إذا كان تطبيقك يحتوي على ملف App.config الخاص به، يمكنك نسخ العُقد التالية إلى ملف App.config:

    • الإعداد/AdManagerApi
    • configuration/configSections/section[name="AdManagerApi"]
    • Configuration/system.net
  4. بيانات اعتماد الإعداد

    افتح App.config وعدِّل المفاتيح التالية:

    <add key="ApplicationName" value="INSERT_YOUR_APPLICATION_NAME_HERE" />
    <add key="NetworkCode" value="INSERT_YOUR_NETWORK_CODE_HERE" />
    <add key="OAuth2Mode" value="SERVICE_ACCOUNT" />
    <add key="OAuth2SecretsJsonPath" value="INSERT_OAUTH2_SECRETS_JSON_FILE_PATH_HERE" />
    

  5. إجراء مكالمة مع المكتبة

    يمكنك استدعاء المكتبة كما هو موضّح في مقتطف رمز C# التالي

    AdManagerUser user = new AdManagerUser();
          using (InventoryService inventoryService = user.GetService<InventoryService>())
                {
                    // Create a statement to select ad units.
                    int pageSize = StatementBuilder.SUGGESTED_PAGE_LIMIT;
                    StatementBuilder statementBuilder =
                        new StatementBuilder().OrderBy("id ASC").Limit(pageSize);
    
                    // Retrieve a small amount of ad units at a time, paging through until all
                    // ad units have been retrieved.
                    int totalResultSetSize = 0;
                    do
                    {
                        AdUnitPage page =
                            inventoryService.getAdUnitsByStatement(statementBuilder.ToStatement());
    
                        // Print out some information for each ad unit.
                        if (page.results != null)
                        {
                            totalResultSetSize = page.totalResultSetSize;
                            int i = page.startIndex;
                            foreach (AdUnit adUnit in page.results)
                            {
                                Console.WriteLine(
                                    "{0}) Ad unit with ID \"{1}\" and name \"{2}\" was found.", i++,
                                    adUnit.id, adUnit.name);
                            }
                        }
    
                        statementBuilder.IncreaseOffsetBy(pageSize);
                    } while (statementBuilder.GetOffset() < totalResultSetSize);
    
                    Console.WriteLine("Number of results found: {0}", totalResultSetSize);
                }
            

إذا لم تكن تريد ضبط بيانات الاعتماد في ملف App.config، يمكنك الرجوع إلى مقالة wiki هذه للتعرّف على الطرق البديلة لاستخدام فئة AdManagerUser. للحصول على معلومات أكثر تفصيلاً حول استخدام مكتبة برامج .NET، يُرجى الرجوع إلى README . إذا أردت التطوير في .NET بدون مكتبة البرامج، يُرجى الرجوع إلى مقالة NoClientLibrary على wiki.

Ruby

إليك مثال أساسي يوضّح كيفية استخدام مكتبة عميل Ruby. تتطلب مكتبة عميل Ruby الإصدار 2.1 أو إصدار أحدث.

  1. ثبِّت جوهرة Ruby واحصل على ملف الإعداد.

    يمكنك تشغيل الأوامر التالية في واجهة الأوامر:

    gem install google-dfp-api
    curl https://raw.githubusercontent.com/googleads/google-api-ads-ruby/main/ad_manager_api/ad_manager_api.yml -o ~/ad_manager_api.yml
    
  2. إعداد بيانات الاعتماد

    عليك تعبئة الحقول المطلوبة في ملف ~/ad_manager_api.yml. إذا لم يكن لديك ملف مفتاح OAuth2، فستحتاج إلى اتباع خطوات إنشاء بيانات اعتماد OAuth2.

    :authentication:
      :oauth2_keyfile: INSERT_PATH_TO_JSON_KEY_FILE_HERE
      :application_name: INSERT_APPLICATION_NAME_HERE
      :network_code: INSERT_NETWORK_CODE_HERE
    
  3. كتابة بعض الرموز وتقديم طلب
    # Import the library.
    require 'ad_manager_api'
    
    # Initialize an Ad Manager client instance (uses credentials in ~/ad_manager_api.yml by default).
    ad_manager = AdManagerApi::Api.new
    
    # Get a service instance.
    network_service = ad_manager.service(:NetworkService, :v202402)
    
    # Make a request.
    network = network_service.get_current_network()
    
    puts "The current network is %s (%d)." %
            [network[:display_name], network[:network_code]]
    

يمكن العثور على خطوات أكثر تفصيلاً للبدء في ملف README الذي يتم توزيعه مع مكتبة برامج Ruby. يمكنك أيضًا الاطّلاع على مكتبة الأمثلة الكاملة للغة Ruby.

الخطوات التالية

عندما يكون لديك مكتبة عملاء قيد التشغيل، فقم بتعديل الأمثلة المقدمة لتوسيعها حسب احتياجاتك.

تصفَّح المستندات المرجعية لمعرفة المزيد من المعلومات حول واجهة برمجة التطبيقات.

إذا كنت بحاجة إلى المساعدة، يُرجى الانتقال إلى صفحة الدعم.