بدء استخدام Ads Data Hub API

يوضّح هذا الدليل كيفية البدء في كتابة التطبيقات التي تستخدم Ads Data Hub REST API للتفاعل مع Ads Data Hub. تتيح لك واجهة برمجة التطبيقات REST API في Ads Data Hub عرض عملاء Ads Data Hub المرتبطين بحسابك على Google، وإنشاء طلبات بحث، وتنفيذ طلبات البحث.

الإعداد

هناك بعض الخطوات التي يجب إكمالها قبل استخدام واجهة برمجة التطبيقات Ads Data Hub:

1. تأكَّد من منح المستخدم الذي يفعّل واجهة برمجة التطبيقات إذن serviceusage.services.enable في مشروع على السحابة الإلكترونية من Google. يجب أيضًا إدراج المستخدم الذي لديه إذن serviceusage.services.enable في القائمة المسموح بها للوصول إلى واجهة برمجة التطبيقات.
2. فعِّل واجهة برمجة التطبيقات Ads Data Hub API في مشروع Google Cloud الذي تم فيه إنشاء بيانات اعتماد العميل أو حساب الخدمة. لتفعيل واجهة برمجة تطبيقات Ads Data Hub API لمشروع باستخدام وحدة التحكّم، اتّبِع الخطوات التالية:
   1. انتقِل إلى مكتبة واجهات برمجة التطبيقات في Cloud Console.
   2. اختَر المشروع الذي تريد استخدامه من قائمة المشاريع.
   3. ابحث عن "Ads Data Hub API".
   4. في صفحة واجهة برمجة التطبيقات، انقر على تفعيل.
3. إدارة الأذونات:
   1. يجب إضافة عنوان البريد الإلكتروني أو حساب الخدمة المستخدَمَين لإنشاء بيانات الاعتماد إلى Ads Data Hub مع الأذونات المناسبة. بالنسبة إلى حساب الخدمة، يكون هذا هو عنوان البريد الإلكتروني لحساب الخدمة. بالنسبة إلى OAuth، هذا هو عنوان البريد الإلكتروني للمستخدم. يضمن ذلك أنّ حساب الخدمة أو حساب المستخدم النهائي لديه إذن بتنفيذ طلبات البحث في Ads Data Hub.
4. (يُنصح به) ثبِّت مكتبة برامج Google API:
   1. تتوفّر مكتبات عملاء Google APIs بعدة لغات رائجة، وتتيح لك استخدام العديد من واجهات Google APIs. على الرغم من أنّ ذلك ليس مطلوبًا، إلا أنّ مكتبات البرامج تقلّل مقدار الرموز البرمجية التي عليك كتابتها، وتسهّل عملية إعداد المصادقة.

مكتبة العميل	أمثلة على Ads Data Hub
Google API Client Library for Java	Java
Google API Client Library for Python

المصادقة والتفويض

يمكن لواجهة برمجة التطبيقات Ads Data Hub API الوصول إلى البيانات وتغييرها في حسابك على Ads Data Hub، لذا يجب أن تتأكّد من أنّك مستخدم معتمَد. لهذا السبب، قبل البدء في التفاعل مع واجهة برمجة التطبيقات Ads Data Hub API، عليك اتّباع خطوات عملية منح الأذونات. يوفّر لك مسار منح الإذن الأذونات اللازمة للتفاعل مع واجهة برمجة التطبيقات. يمكنك المصادقة باستخدام بروتوكول OAuth 2.0 أو حساب خدمة.

OAuth 2.0 حساب الخدمة

إعداد OAuth 2.0

تتيح واجهة برمجة التطبيقات سلسلة خطوات التطبيق المثبَّت وسلسلة خطوات تطبيق الويب، ولكن في هذا المثال، سنشرح سلسلة خطوات التطبيق المثبَّت.

1. انتقِل إلى "وحدة تحكّم واجهة Google API" وانتقِل إلى مشروع المشرف.
2. تأكَّد من تفعيل Ads Data Hub API لمشروعك.
   1. إذا لم تكن مفعَّلة، انقر على "تفعيل واجهات برمجة التطبيقات والخدمات" (+ Enable APIs and services) لتفعيلها.
3. في شريط التنقل الأيمن، انقر على "بيانات الاعتماد".
4. افتح القائمة المنسدلة "إنشاء بيانات اعتماد" (Create credentials) واختَر "معرّف عميل OAuth" (OAuth client ID). في الصفحة التالية:
   1. انقر على "غير ذلك".
   2. يمكنك اختياريًا منح العميل اسمًا.
   3. انقر على "إنشاء".
5. انقر على رمز التنزيل بجانب بيانات الاعتماد التي أنشأتها للتو.

الحصول على مفتاح واجهة برمجة التطبيقات

يُستخدَم مفتاح واجهة برمجة التطبيقات (المعروف أيضًا باسم مفتاح المطوّر) للمصادقة في عينة تعليمات برمجية للغة Python أدناه. للحصول على مفتاح واجهة برمجة التطبيقات، اتّبِع الخطوات التالية:

1. انتقِل إلى صفحة "بيانات الاعتماد" في وحدة تحكّم واجهة برمجة التطبيقات
2. تأكَّد من اختيار مشروع المشرف في القائمة المنسدلة في شريط التنقّل العلوي.
3. انقر على رمز التنزيل بجانب مفتاح واجهة برمجة التطبيقات.

إرسال طلب للحصول على عيّنة

Python

"""This sample shows how to retrieve all accounts associated with the user.

For the program to execute successfully, ensure that you run it using Python 3.
"""
import json
from google_auth_oauthlib import flow
from googleapiclient.discovery import build

appflow = flow.InstalledAppFlow.from_client_secrets_file(
    # Replace client_secrets.json with your own client secret file.
    'client_secrets.json',
    scopes=['https://www.googleapis.com/auth/adsdatahub'])
appflow.run_local_server()
credentials = appflow.credentials
developer_key = input('Developer key: ').strip()
# For versions of the Google API Python client library prior to 2.0, the
# `static_discovery` parameter below should be removed.
service = build('AdsDataHub', 'v1', credentials=credentials,
                developerKey=developer_key, static_discovery=False)


def pprint(x):
  print(json.dumps(x, sort_keys=True, indent=4))


adh_account_id = input('ADH account ID (e.g. "customers/123456789"): ').strip()
pprint(service.customers().analysisQueries().list(parent
                                                  =adh_account_id).execute())

      

جافا

/*
 * Copyright (c) 2019 Google Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
 * in compliance with the License. You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software distributed under the License
 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
 * or implied. See the License for the specific language governing permissions and limitations under
 * the License.
 */

package com.google.api.services.samples.adsdatahub.cmdline;

import com.google.api.services.adsdatahub.v1.AdsDataHub;
import com.google.api.services.adsdatahub.v1.model.Customer;
import com.google.api.services.adsdatahub.v1.model.ListCustomersResponse;
import java.io.IOException;
import java.util.List;

/**
 * This sample illustrates how to retrieve all accounts associated to the user.
 *
 * <p>See the <a href="customers.list reference
 * documentation">https://developers.google.com/ads-data-hub/reference/rest/v1/customers/list</a>
 * for more details.
 */
public class ListCustomers extends BaseSample {

  @Override
  public String getName() {
    return "List customers";
  }

  @Override
  public String getDescription() {
    return "Lists customers associated with the authorized user";
  }

  @Override
  public void execute(AdsDataHub client) throws IOException {
    String pageToken = null;
    boolean noData = true;

    System.out.println("========================================");
    System.out.printf("Listing of customers associated with the authorized user:\n");
    System.out.println("========================================");

    do {
      ListCustomersResponse response = client.customers().list().setPageToken(pageToken).execute();
      pageToken = response.getNextPageToken();
      List<Customer> customers = response.getCustomers();

      if (customers != null && customers.size() > 0) {
        noData = false;
        for (Customer customer : customers) {
          System.out.printf("* Customer id: %d\n", customer.getCustomerId());
          System.out.printf("\tCustomer name: %s\n", customer.getDisplayName());
        }
      }
    } while (pageToken != null);

    if (noData) {
      System.out.println("No customers were found associated with the authorized user.");
    }
  }
}

      

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

• اطّلِع على نماذج طلبات البحث في Ads Data Hub للحصول على أمثلة على طلبات البحث التي يمكنك إنشاؤها وتنفيذها باستخدام واجهة برمجة التطبيقات REST في Ads Data Hub.
• يمكنك الاطّلاع على النماذج للتعرّف على واجهة برمجة التطبيقات وتخصيصها لتناسب حالة الاستخدام. بعد ذلك، حاوِل إجراء ما يلي:
  • حالة عملية طلب البحث في الاستطلاع
  • استخدِم مكتبة برامج BigQuery لاسترداد نتائج طلب البحث المكتملة.
• يُرجى التواصل مع فريق دعم "مركز بيانات إعلانات Google" إذا كانت لديك أسئلة أو ملاحظات حول واجهة برمجة التطبيقات.