بدء استخدام 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 ADH account ID.
adh_account_id = input('ADH account ID (e.g. "customers/123456789"): ').strip()
queries = service.customers().analysisQueries().list(
    parent=adh_account_id).execute()
print(json.dumps(queries, sort_keys=True, indent=4))

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

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