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

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

الإصدار الثاني من Bid Manager API هو أحدث إصدار متاح ومقترَح.

1- قبل البدء

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

2. الاستعداد للمصادقة

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

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

لمزيد من المعلومات، يُرجى الاطّلاع على السماح بالطلبات.

3. استدعاء واجهة برمجة تطبيقات Bid Manager

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

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.");
    }
    

لمزيد من المعلومات التفصيلية عن استخدام واجهة برمجة تطبيقات Bid Manager مع لغة Java، يُرجى الرجوع إلى الملف README في أمثلة واجهة برمجة تطبيقات Bid Manager.

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.')
    

لمزيد من المعلومات التفصيلية عن استخدام واجهة برمجة تطبيقات Bid Manager مع لغة بايثون، يُرجى الرجوع إلى الملف README في أمثلة واجهة برمجة تطبيقات إدارة عرض الأسعار.

PHP

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

php -S localhost:8000 -t ./

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

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

    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 API"

    $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>';
    }
    

لمزيد من المعلومات التفصيلية عن استخدام واجهة برمجة تطبيقات Bid Manager مع لغة PHP، يُرجى الرجوع إلى الملف README في أمثلة واجهة برمجة تطبيقات إدارة عرض الأسعار.

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

بعد أن أصبح لديك مكتبة عملاء قيد التشغيل، اطّلع على الوثائق المرجعية وابدأ في إعداد عملية التنفيذ.

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