إعداد OAuth واستخدامه

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

تستخدم واجهة برمجة تطبيقات "الخدمات المحلّية" بروتوكول OAuth 2.0 لمصادقة المستخدمين. لمزيد من المعلومات عن OAuth 2.0، اطّلِع على استخدام OAuth 2.0 للوصول إلى واجهات برمجة تطبيقات Google.

إعداد مشروع وحدة تحكم Google API لواجهة برمجة تطبيقات "الخدمات المحلّية"

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

للحصول على بيانات الاعتماد هذه، يمكنك اتّباع الخطوات التالية:

  1. أنشئ مشروعًا. ولإجراء ذلك، انتقِل إلى وحدة التحكم في واجهة Google API. انقر على إنشاء مشروع، وأدخِل اسمًا، ثم انقر على إنشاء.

  2. تفعيل واجهة برمجة تطبيقات "الخدمات المحلّية" في مشروعك:

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

      إذا لم تكن واجهة برمجة تطبيقات "الخدمات المحلّية" مرئية في القائمة، استخدِم مربّع البحث للعثور عليها.

    2. اختَر واجهة برمجة تطبيقات "الخدمات المحلّية"، ثم انقر على تفعيل.

  3. اختَر نوع تطبيق. تستخدم واجهة برمجة تطبيقات "الخدمات المحلّية" أنواع التطبيقات نفسها مثل "إعلانات Google API". لمزيد من التفاصيل حول نوع التطبيق المراد استخدامه، راجِع اختيار نوع التطبيق.

  4. أنشئ معرِّف عميل وسر عميل. بالنسبة إلى واجهة برمجة التطبيقات في "الخدمات المحلّية"، اتّبِع الخطوات نفسها لإنشاء معرّف عميل وسرّ عميل كما هو الحال في Google Ads API. وتكون الخطوات متطابقة في حالتَي الاستخدام.

استخدام "مكتبة العميل" للحصول على رموز OAuth 2.0 المميزة

للحصول على قائمة بمكتبات العملاء التي يمكنك استخدامها لتقديم طلبات تفويض OAuth 2.0، اطّلِع على مكتبات العميل. اتّبِع التعليمات الخاصة بالمكتبة لمعرفة كيفية استخدام رمز مميّز لإعادة التحميل للحصول على رمز دخول جديد.

كيفية الحصول على رمز مميز لإعادة تحميل OAuth 2.0

نقترح عليك استخدام مكتبات العميل في مرحلة الإنتاج لمصادقة المستخدمين. إذا كنت تريد استخدام برنامج HTTP لأغراض الاختبار، يمكنك اتّباع التعليمات التالية للحصول على رمز مميّز لإعادة تحميل OAuth 2.0 ورمز دخول. الخطوات 1 و2 و3 هي تعليمات إعداد لمرة واحدة يجب تنفيذها يدويًا، ويمكن تشغيل الخطوتين 4 و5 بشكل مبرمَج بعد ذلك لتشغيلها بدون تدخل من البشر، مثل مهمة corn.

  1. نزِّل ملف curl وثبِّته، وهو أداة سطر أوامر لإجراء طلبات HTTP على الويب.

  2. اتّبِع التعليمات الواردة في صفحة مساحة التخزين في OAuth للحصول على رمز مميّز لإعادة تحميل OAuth 2.0. يمكنك استخدام النطاق التالي لواجهة برمجة تطبيقات "الخدمات المحلّية":

    https://www.googleapis.com/auth/adwords

    هذا هو نطاق OAuth 2.0 نفسه الذي تستخدمه واجهة برمجة التطبيقات مع "إعلانات Google".

    في نهاية هذه الخطوة، ستتلقى رمزَين مميزَين: رمز مميّز لإعادة التحميل ورمز مميّز للوصول. احفظ الاثنين.

  3. شغّل الأمر التالي في موجه أوامر لإثبات نجاح الخطوة السابقة:

    curl https://oauth2.googleapis.com/tokeninfo?access_token=<INSERT_ACCESS_TOKEN>

    إذا كانت مخرجات الأمر تعرض رسالة على النحو التالي، يعني ذلك أنّ الأمر كان ناجحًا:

    {
  "azp": "************-********************************.apps.googleusercontent.com",
  "aud": "************-********************************.apps.googleusercontent.com",
  "scope": "https://www.googleapis.com/auth/adwords [googleapis.com]",
  "exp": "1611183382",
  "expires_in": "3482",
  "access_type": "offline"
}

    إذا كان هناك خطأ أو كان النطاق غير صحيح، جرِّب إنشاء الرموز المميزة مرة أخرى.

  4. إنشاء رمز دخول جديد بدون تدخل يدوي. هذا الإجراء مهم لأن صلاحية رموز الدخول تنتهي كل ساعة. تستغرق صلاحية الرموز المميّزة لإعادة التحميل وقتًا أطول، لذا غالبًا ما تحتاج إلى إبطالها يدويًا عندما لا تكون هناك حاجة إليها.

    للحصول على رمز دخول جديد، شغِّل الأمر التالي:

    curl --data "refresh_token=<INSERT_REFRESH_TOKEN>&client_id=<INSERT_CLIENT_ID>&client_secret=<INSERT_CLIENT_SECRET>&grant_type=refresh_token" -X POST "https://oauth2.googleapis.com/token”

  5. تشغيل طلب البيانات من واجهة برمجة التطبيقات التالي:

    curl -H "Authorization: Bearer <INSERT_ACCESS_TOKEN>" https://localservices.googleapis.com/v1/accountReports:search?query=manager_customer_id:<INSERT_10_DIGIT_MANAGER_CUSTOMER_ID_WITHOUT_HYPHENS>

    إذا نجحت هذه المكالمة، اكتمل الإعداد.