تم إيقاف العمل بالإصدار 1.1 من واجهة برمجة تطبيقات "مدير عروض الأسعار" في آب (أغسطس) 2022، وسينتهي العمل بها في 28 شباط (فبراير) 2023.

يُرجى نقل البيانات إلى الإصدار 2 لتجنُّب انقطاع الخدمة. راجع دليل الترحيل للتعرف على خطوات الترحيل إلى الإصدار 2.

بدء استخدام واجهة برمجة التطبيقات

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

يوضّح هذا المستند كيفية البدء في كتابة التطبيقات التي تستخدم واجهة برمجة التطبيقات Google Ad Manager API. تتيح لك واجهة برمجة التطبيقات إدارة طلبات البحث واسترداد بيانات إعداد التقارير.

الإصدار 2 من واجهة برمجة تطبيقات "إدارة عرض السعر" هو أحدث إصدار متاح ومقترَح.

1- قبل البدء

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

2. التحضير للمصادقة

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

أنشِئ بيانات اعتماد OAuth 2.0 من خلال النقر على إنشاء بيانات اعتماد &gt؛ معرِّف عميل OAuth، إذا لم تكن قد فعلت ذلك من قبل. بعد إنشاء بيانات الاعتماد، يمكنك رؤية معرِّف العميل على صفحة بيانات الاعتماد. انقر على معرّف العميل للحصول على التفاصيل، مثل سر العميل ومعرّفات الموارد المنتظمة (URI) وعنوان URL لمصادر JavaScript وعنوان البريد الإلكتروني.

لمزيد من المعلومات، يمكنك الاطّلاع على تفويض الطلبات.

3- الاتصال بواجهة برمجة تطبيقات إدارة عرض السعر

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

Java

  1. استيراد المكتبات اللازمة:

    import static java.nio.charset.StandardCharsets.UTF_8;
    import com.google.api.client.auth.oauth2.Credential;
    import com.google.api.client.extensions.java6.auth.oauth2.AuthorizationCodeInstalledApp;
    import com.google.api.client.extensions.jetty.auth.oauth2.LocalServerReceiver;
    import com.google.api.client.googleapis.auth.oauth2.GoogleAuthorizationCodeFlow;
    import com.google.api.client.googleapis.auth.oauth2.GoogleClientSecrets;
    import com.google.api.client.googleapis.util.Utils;
    import com.google.api.services.doubleclickbidmanager.DoubleClickBidManager;
    import com.google.api.services.doubleclickbidmanager.model.ListQueriesResponse;
    import com.google.api.services.doubleclickbidmanager.model.Query;
    import java.io.Reader;
    import java.nio.file.Files;
    import java.nio.file.Paths;
    
  2. تحميل ملف أسرار العميل وإنشاء بيانات اعتماد التفويض

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

    // Read client secrets file.
    GoogleClientSecrets clientSecrets;
    try (Reader reader = Files.newBufferedReader(Paths.get(path-to-client-secrets-file), UTF_8)) {
      clientSecrets = GoogleClientSecrets.load(Utils.getDefaultJsonFactory(), reader);
    }
    
    // Generate authorization credentials.
    // Set up the authorization code flow.
    GoogleAuthorizationCodeFlow flow =
        new GoogleAuthorizationCodeFlow.Builder(
            Utils.getDefaultTransport(),
            Utils.getDefaultJsonFactory(),
            clientSecrets,
            oauth-scopes)
        .build();
    
    Credential credential =
        new AuthorizationCodeInstalledApp(flow, new LocalServerReceiver()).authorize("user");
    
  3. إنشاء عميل معتمَد لواجهة برمجة التطبيقات

    // Create authorized API client.
    DoubleClickBidManager service =
        new DoubleClickBidManager.Builder(credential.getTransport(), credential.getJsonFactory(), credential)
            .setApplicationName("bidmanager-java-installed-app-sample")
            .build();
    
  4. نفِّذ عملية.

    // Perform an operation.
    // Call the API, getting a list of 10 queries.
    ListQueriesResponse queriesResponse = service.queries().list().setPageSize(10).execute();
    
    // Print them out.
    System.out.println("Id\t\tName");
    if (queriesResponse.getQueries().size() > 0) {
      for (int i = 0; i < queriesResponse.getQueries().size(); i++) {
        Query currentQuery = queriesResponse.getQueries().get(i);
        System.out.printf(
            "%s\t%s%n",
            currentQuery.getQueryId(),
            currentQuery.getMetadata().getTitle());
      }
    } else {
      System.out.println("No queries exist.");
    }
    

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

Python

  1. استيراد المكتبات اللازمة:

    from google_auth_oauthlib.flow import InstalledAppFlow
    from googleapiclient import discovery
    
  2. تحميل ملف أسرار العميل وإنشاء بيانات اعتماد التفويض

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

    # Set up a flow object to create the credentials using the
    # client secrets file and OAuth scopes.
    credentials = InstalledAppFlow.from_client_secrets_file(
        path-to-client-secrets-file, oauth-scopes).run_local_server()
    
  3. إنشاء عميل معتمَد لواجهة برمجة التطبيقات

    # Build the discovery document URL.
    discovery_url = f'https://doubleclickbidmanager.googleapis.com/$discovery/rest?version=v2'
    
    # Build the API service.
    service = discovery.build(
        'doubleclickbidmanager',
        'v2',
        discoveryServiceUrl=discovery_url,
        credentials=credentials)
    
  4. نفِّذ عملية.

    # Build and execute queries.listqueries request.
    response = service.queries().list(pageSize='10').execute()
    
    # Print queries out.
    if 'queries' in response:
      print('Id\t\tName')
      for query in response['queries']:
        print('%s\t%s' % (query['queryId'], query['metadata']['title']))
    else:
      print('No queries exist.')
    

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

PHP

يفترض هذا النموذج أنك تشغّل لغة PHP مع خادم ويب مضمّن وأنك ضبطت بيانات اعتمادك لإعادة التوجيه إلى صفحة الويب ذات الصلة. على سبيل المثال، يمكن تشغيل هذا الرمز، في ملف index.php، باستخدام الأمر التالي وبيانات الاعتماد التي تم ضبطها لإعادة التوجيه إلى http://localhost:8000 بعد المصادقة:

php -S localhost:8000 -t ./

  1. نزِّل عميل Google API PHP وثبِّته.

    الطريقة المفضّلة هي من خلال الملحّن:

    composer require google/apiclient:^2.12.1
    

    بعد التثبيت، احرص على تضمين أداة التحميل التلقائي

    require_once '/path/to/your-project/vendor/autoload.php';
    

  2. أنشئ عنصرًا في Google_Client.

    $client = new Google_Client();
    
  3. يمكنك إعداد العميل وإعادة التوجيه إلى عنوان URL للمصادقة عند الحاجة إليه واسترداد رمز الدخول.

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

    // Set up the client.
    $client->setApplicationName('DBM API PHP Samples');
    $client->addScope(oauth-scope);
    $client->setAccessType('offline');
    $client->setAuthConfigFile(path-to-client-secrets-file);
    
    // If the code is passed, authenticate. If not, redirect to authentication page.
    if (isset($_GET['code'])) {
      $client->authenticate($_GET['code']);
    } else {
      $authUrl = $client->createAuthUrl();
      header('Location: ' . $authUrl);
    }
    
    // Exchange authorization code for an access token.
    $accessToken = $client->getAccessToken();
    $client->setAccessToken($accessToken);
    
  4. أنشئ برنامجًا لخدمة واجهة برمجة تطبيقات "مساحة العرض والفيديو 360".

    $service = new Google_Service_DoubleClickBidManager($client);
    
  5. نفِّذ عملية.

    // Configure params for the Queries.listqueries request.
    $optParams = array('pageSize' => 10);
    
    // Execute the request.
    $result = $service->queries->listQueries($optParams);
    
    // Print the retrieved queries.
    if (!empty($result->getQueries())) {
      print('<pre><p>Id Name</p>');
      foreach ($result->getQueries() as $query) {
        printf('<p>%s %s</p>', $query->queryId, $query->metadata->title);
      }
      print('</pre>');
    } else {
      print '<p>No queries exist.</p>';
    }
    

للحصول على معلومات أكثر تفصيلاً عن استخدام واجهة برمجة تطبيقات إدارة عروض الأسعار مع لغة PHP، يمكنك الرجوع إلى ملف ReadME في أمثلة على واجهة برمجة تطبيقات إدارة عروض الأسعار.

4. الخطوات اللاحقة

بعد أن أصبح لديك مكتبة عملاء قيد التشغيل، استكشِف المستندات المرجعية وابدأ في تنفيذ عملية التنفيذ.

تتوفّر أيضًا أدلة إضافية حول استخدام التقارير المجدولة واتّباع أفضل ممارسات إعداد التقارير.