البدء

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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 يمكنك العثور على أحدث إصدار على الرابط . GitHub.

    <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.v202408.Network;
    import com.google.api.ads.admanager.axis.v202408.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 مع Python الإصدار 3.6 أو الإصدارات الأحدث. لمزيد من التفاصيل حول الاستخدام يمكنك الاطّلاع على ملف README ملف في توزيع مكتبة العملاء.

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

    شغِّل الأوامر التالية في واجهة Shell:

    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='v202408')
    
    # 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\v202408\ApiException;
    use Google\AdsApi\AdManager\v202408\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. إضافة المراجع المطلوبة للمكتبة إلى مشروعك

    إضافة تبعية nuget لـ Google.Dfp.

  3. إعداد App.config

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

    • configuration/AdManagerApi
    • configuration/configSections/section[name=&quot;AdManagerApi&quot;]
    • 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 واحصل على ملف الإعداد.

    شغِّل الأوامر التالية في واجهة Shell:

    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, :v202408)
    
    # 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.

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

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

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

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