تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

البدء

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

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

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

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

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

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

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

افتح صفحة بيانات اعتماد وحدة تحكم Google API
من قائمة المشروع، اختَر إنشاء مشروع وأدخِل اسمًا للمشروع، ويمكنك اختياريًا تعديل رقم تعريف المشروع المقدَّم. انقر على إنشاء.
في صفحة "بيانات الاعتماد"، اختَر إنشاء بيانات اعتماد، ثم اختَر مفتاح حساب الخدمة.
اختَر حساب خدمة جديد واختَر JSON كنوع المفتاح.
انقر على إنشاء لتنزيل ملف يحتوي على مفتاح خاص.

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

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

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

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

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

لغة Java

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

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

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

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
[...]

تحديد التبعيات

عدِّل ملف 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>

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

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.v202311.Network;
import com.google.api.ads.admanager.axis.v202311.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());
  }
}

العرض على GitHub

لغة Python

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

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

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

pip install googleads
curl https://raw.githubusercontent.com/googleads/googleads-python-lib/main/googleads.yaml \
     -o ~/googleads.yaml

اضبط إعدادات ملف ~/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

نفِّذ بعض الرموز وأدخِل طلبًا.

# 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='v202311')

# 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']))

العرض على GitHub

‫2,999

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

تثبيت المكتبة وإعداد بيانات الاعتماد
شغِّل الأوامر التالية في واجهة الأوامر لتثبيت مكتبة البرامج وتنزيل ملف 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
```

عليك إعداد ملف ~/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"

يُرجى تنفيذ بعض الرموز وإجراء طلب.

يجب تشغيل هذا الرمز النموذجي من سطر الأوامر، وليس من متصفح. يجب وضع الملف الذي يحتوي على هذا الرمز في جذر دليل المشروع، حيث تم تشغيل composer require.

<?php
require 'vendor/autoload.php';
use Google\AdsApi\AdManager\AdManagerSession;
use Google\AdsApi\AdManager\AdManagerSessionBuilder;
use Google\AdsApi\AdManager\v202311\ApiException;
use Google\AdsApi\AdManager\v202311\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()
);

العرض على GitHub

NET.

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

إنشاء مشروع جديد
افتح Visual Studio وأنشئ مشروعًا جديدًا (تطبيق Console).
إضافة مراجع المكتبة المطلوبة إلى مشروعك
أضف تبعية nuget لـ Google.Dfp.
إعداد App.config
انسخ src\App.config إلى دليل مشروعك وأضِفه إلى مشروعك. إذا كان تطبيقك يحتوي على App.config الخاصة به، يمكنك نسخ العُقد التالية في App.config:
- الإعدادات/AdManagerApi
- Configuration/configsections/section[name="AdManagerApi"]
- الإعدادات/system.net

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

افتح 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" />

إجراء مكالمة للمكتبة

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

العرض على GitHub

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 أو إصدار أحدث من Ruby.

ثبِّت جوهرة 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
```
إذا واجهت خطأً مثل "cannot load such file -- mkmf (LoadError)" في أي وقت أثناء تثبيت الأحجار الكريمة، قد تحتاج إلى تثبيت مكتبات تطوير Ruby إضافية مثل Ruby-dev وRuby-devel وxcode-select وما إلى ذلك لبيئتك الخاصة.
إعداد بيانات الاعتماد
عليك تعبئة الحقول المطلوبة في ملف ~/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
```

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

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

# Make a request.
network = network_service.get_current_network()

puts "The current network is %s (%d)." %
        [network[:display_name], network[:network_code]]

العرض على GitHub

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

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

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

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

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

البدء

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

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

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

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

لغة Java

لغة Python

‫2,999

NET.

Ruby

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