تفويض واجهة برمجة تطبيقات "إدارة العلامات من Google"

ويوضّح المستند طريقة حصول أحد التطبيقات على تفويض لإرسال طلبات إلى واجهة برمجة تطبيقات إدارة العلامات من Google.

الموافقة على الطلبات

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

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

نبذة عن بروتوكولات التفويض

يجب أن يستخدم تطبيقك OAuth 2.0 للسماح بالطلبات. ولا يُسمح باستخدام أي بروتوكولات أخرى للموافقة على الطلبات. إذا كان تطبيقك يستخدم ميزة تسجيل الدخول باستخدام حساب Google، ستتم معالجة بعض جوانب عملية الموافقة على الطلبات نيابةً عنك.

الموافقة على الطلبات باستخدام OAuth 2.0

يجب أن يصادق مستخدم تمت مصادقته على جميع الطلبات إلى واجهة برمجة تطبيقات "إدارة العلامات من Google".

تختلف تفاصيل عملية الموافقة على الطلبات لبروتوكول OAuth 2.0 نوعًا ما حسب نوع التطبيق الذي تكتبه. وتسري العملية العامة التالية على كل أنواع التطبيقات:

  1. عند إنشاء التطبيق، يجب تسجيله باستخدام وحدة التحكم في واجهة Google API. ويوفر محرك البحث Google المعلومات التي ستحتاجها في ما بعد، مثل معرّف العميل وسر العميل.
  2. عليك تفعيل واجهة برمجة تطبيقات "إدارة العلامات من Google" في وحدة تحكّم Google API. (يمكنك تخطّي هذه الخطوة إذا كانت واجهة برمجة التطبيقات غير مدرَجة في وحدة التحكم في واجهة Google API.)
  3. إذا احتاج التطبيق الدخول إلى بيانات المستخدِم، يطلب التطبيق من Google نطاقًا معينًا للدخول.
  4. يعرض Google شاشة الموافقة للمستخدم، ويطلب منه السماح لتطبيقك بطلب بعض بياناته.
  5. عند موافقة المستخدِم، يمنح Google تطبيقك رمز دخول قصير الأجل.
  6. يطلب تطبيقك بيانات المستخدِم، من خلال إرفاق رمز الدخول بالطلب.
  7. يعرض Google البيانات المطلوبة بعد تحققه من صلاحية طلبك والرمز المميز.

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

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

النطاق المعنى
https://www.googleapis.com/auth/tagmanager.readonly عرض حاويات "إدارة العلامات من Google".
https://www.googleapis.com/auth/tagmanager.edit.containers إدارة حاويات أداة "إدارة العلامات من Google"
https://www.googleapis.com/auth/tagmanager.delete.containers حذف حاويات أداة "إدارة العلامات من Google"
https://www.googleapis.com/auth/tagmanager.edit.containerversions إدارة إصدارات حاويات أداة "إدارة العلامات من Google"
https://www.googleapis.com/auth/tagmanager.publish انشر حاويات "إدارة العلامات من Google".
https://www.googleapis.com/auth/tagmanager.manage.users إدارة أذونات المستخدمين في بيانات إدارة العلامات من Google.
https://www.googleapis.com/auth/tagmanager.manage.accounts يمكنك إدارة حساباتك على أداة "إدارة العلامات من Google".

لطلب الدخول باستخدام بروتوكول OAuth 2.0، يحتاج التطبيق معلومات عن النطاق، بالإضافة إلى المعلومات التي يوفّرها Google عند تسجيل التطبيق (مثل معرِّف العميل وسر العميل).

البدء

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

لإعداد حساب خدمة جديد، يُرجى اتّباع الخطوات التالية:

  1. انقر على إنشاء بيانات اعتماد > مفتاح حساب الخدمة.
  2. اختَر ما إذا كنت تريد تنزيل المفتاح العام/الخاص لحساب الخدمة كملف P12 عادي، أو كملف JSON يمكن تحميله من خلال مكتبة برامج Google API.

يتم إنشاء زوج المفتاح العام/الخاص وتنزيله على جهازك، ويعد هذا الزوج هو النسخة الوحيدة من هذا المفتاح. وأنت مسؤول عن تخزينها بأمان.

التدفقات الشائعة لبروتوكول OAuth 2.0

توضّح الإرشادات التالية حالات الاستخدام الشائعة لتدفقات OAuth 2.0 المحددة:

خادم الويب

هذا المسار مناسب للوصول التلقائي/بلا إنترنت/المجدول إلى حساب المستخدم على أداة "إدارة العلامات من Google".

مثال:
  • تعديل معلومات أداة "إدارة العلامات من Google" تلقائيًا من خادم

من جهة العميل

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

مثال:
  • أداة ضبط مخصَّصة مستندة إلى المتصفِّح

التطبيقات المثبّتة

للتطبيقات التي يتم توزيعها كحزمة وتثبيتها من قِبل المستخدم ويتطلب ذلك أن يكون للتطبيق أو المستخدم إمكانية الوصول إلى متصفح لإكمال عملية المصادقة.

أمثلة:
  • تطبيق مصغّر لسطح المكتب على جهاز كمبيوتر شخصي أو جهاز Mac.
  • مكوّن إضافي لنظام إدارة المحتوى. ويتمثّل فائدة هذا المسار مقارنةً بخادم الويب أو من جهة العميل في إمكانية استخدام مشروع واحد لوحدة تحكم في واجهة برمجة التطبيقات. ويسمح هذا الإجراء للمستخدمين بتسهيل عملية التثبيت.

حسابات الخدمة

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

تحديد المشاكل وحلّها

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

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

مساحة تشغيل OAuth 2.0

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

منحة غير صالحة

إذا تلقّيت استجابة الخطأ invalid_grant عند محاولة استخدام رمز مميّز لإعادة التحميل، قد يكون سبب حدوث الخطأ أحد السببَين التاليَين أو كليهما:

  1. ساعة الخادم غير متزامنة مع NTP.
  2. لقد تجاوزت الحدّ الأقصى المسموح به للرمز المميّز لإعادة التحميل.
    يمكن أن تطلب التطبيقات عدة رموز مميزة لإعادة التحميل للوصول إلى حساب واحد على أداة "إدارة العلامات من Google". على سبيل المثال، يُعدّ ذلك مفيدًا في الحالات التي يريد فيها المستخدم تثبيت تطبيق على أجهزة متعددة والوصول إلى حساب أداة "إدارة العلامات من Google" نفسه. في هذه الحالة، يجب توفّر رمزين مميزين لإعادة التحميل، ورمز لكل عملية تثبيت. وعندما يتجاوز عدد الرموز المميّزة لإعادة التحميل الحدّ الأقصى، تصبح الرموز المميّزة القديمة غير صالحة. وإذا حاول التطبيق استخدام رمز مميّز تم إبطاله لإعادة التحميل، سيتم عرض استجابة الخطأ invalid_grant. ويمكن أن تحتوي كل مجموعة فريدة من رقم تعريف العميل/الحساب على ما يصل إلى 25 رمزًا مميّزًا لإعادة التحميل. (يُرجى العلم أنّ هذا الحدّ الأقصى عرضة للتغيير). إذا واصل التطبيق طلب الرموز المميّزة لإعادة التحميل لمجموعة معرّف العميل/الحساب نفسها، وبعد إصدار الرمز المميّز السادس والعشرين، يصبح الرمز المميّز الأول لإعادة التحميل الذي تم إصداره غير صالح. إنّ الرمز المميّز المطلوب لإعادة التحميل في اليوم السابع والعشرين يؤدي إلى إلغاء صلاحية الرمز المميّز الذي تم إصداره الثاني، وهكذا.