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

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

الإعداد

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

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

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

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

إعداد حساب الخدمة

  1. انتقِل إلى وحدة تحكّم Google API وانتقِل إلى مشروع المشرف.
  2. تحقَّق من تفعيل واجهة برمجة تطبيقات Ads Data Hub API لمشروعك ضمن واجهات برمجة التطبيقات والخدمات.
    1. وإذا لم تكن كذلك، انقر على + تفعيل واجهات برمجة التطبيقات والخدمات وفعِّل واجهة برمجة تطبيقات Ads Data Hub API.
  3. في قائمة التنقّل اليمنى، انقر على إدارة الهوية وإمكانية الوصول والمشرف > حسابات الخدمة.
    1. إذا لم تكن قد أنشأت حساب خدمة بعد، يمكنك إنشاء حساب.
  4. انقر على قائمة النقاط الثلاث () ضمن "الإجراءات"، ثم انقر على إدارة المفاتيح.
    1. انقر على إضافة مفتاح > إنشاء مفتاح جديد.
    2. بعد التأكّد من اختيار ملف "JSON"، انقر على إنشاء.
  5. أضِف عنوان البريد الإلكتروني لحساب الخدمة كمستخدم في حسابك على Ads Data Hub.

إرسال نموذج طلب

#!/usr/bin/env python3

"""This sample shows how to retrieve all accounts associated with the user.
"""
import json
from google.oauth2.service_account import Credentials
from googleapiclient.discovery import build

SCOPES = ['https://www.googleapis.com/auth/adsdatahub']
DISCOVERY_URL = 'https://adsdatahub.googleapis.com/$discovery/rest?version=v1'
creds = Credentials.from_service_account_file(
    'service-account.json').with_scopes(SCOPES)
developer_key = 'YOUR_DEVELOPER_KEY'  # Replace with your developer key.
service = build('AdsDataHub', 'v1', credentials=creds,
                developerKey=developer_key, discoveryServiceUrl=DISCOVERY_URL)

# Replace with your customer ID.
customer_name = input('Customer name (e.g. "customers/123"): ').strip()
queries = service.customers().analysisQueries().list(
    parent=customer_name).execute()
print(json.dumps(queries, sort_keys=True, indent=4))

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

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