البدء

يوضّح هذا المستند المعلومات الأساسية التي تحتاجها لاستخدام Google Site Verification API.

مقدمة

تم تصميم واجهة برمجة تطبيقات التحقق من المواقع من Google للمطورين الذين يريدون كتابة تطبيقات أو خدمات إثبات ملكية الموقع أو النطاق بطريقة آلية. هذا مهم، نظرًا لأن بعض يمكن لمالكي المواقع الإلكترونية أو النطاقات فقط استخدام خدمات Google. يمكنك استخدام واجهة برمجة التطبيقات Google Site Verification API من أجل التحقق من أن المستخدم الذي تمت مصادقته هو مالك النطاق أو الموقع، ربما يكون المالك الأول في توفير خدمات Google الأخرى آليًا.

يفترض هذا المستند أنك على دراية بمفاهيم برمجة الويب وتنسيقات بيانات الويب أنّه يمكنك تعديل الملفات أو سجلّات نظام أسماء النطاقات لموقعك الإلكتروني أو نطاقك آليًا.

نظرة عامة

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

يجب أن يوافق مستخدم تمت مصادقته على جميع طلبات البيانات من واجهة برمجة التطبيقات، ويتم تنفيذ جميع طلبات البيانات من واجهة برمجة التطبيقات. في سياق حساب المستخدم الذي تمت مصادقته.

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

قبل البدء

الحصول على حساب Google

عليك التأكّد من أنّك قد أعددت حساب Google. ننصحك باستخدام حساب Google منفصل لأغراض التطوير والاختبار لحمايتك من فقدان البيانات غير المقصود.

التعرّف على عملية إثبات ملكية الموقع الإلكتروني

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

التعرّف على كيفية الموافقة على الطلبات

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

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

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

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

يجب أن يوافق مستخدم مصادَق عليه على كلّ الطلبات الموجّهة إلى Google Site Verification API.

تختلف تفاصيل عملية الموافقة على الطلبات لبروتوكول 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/siteverification إذن بالقراءة بشكل كامل للمواقع الإلكترونية الحالية التي تم إثبات ملكيتها، بالإضافة إلى إمكانية إثبات ملكية المواقع الإلكترونية الجديدة
https://www.googleapis.com/auth/siteverification.verify_only إمكانية إثبات ملكية مواقع إلكترونية جديدة، ولا تتوفّر إمكانية قراءة المواقع الإلكترونية الحالية التي تم إثبات ملكيتها.

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

نصيحة: يمكن لمكتبات عملاء Google APIs معالجة جزء من عملية السماح بالنيابة عنك. وتتوفّر هذه المكتبات للعديد من لغات البرمجة، ويمكنك الاطّلاع على صفحة المكتبات والنماذج للحصول على مزيد من التفاصيل.

خلفية واجهة برمجة تطبيقات التحقق من المواقع من Google

المفاهيم

يمكنك استخدام Google Site Verification API لإثبات ملكية المستخدم للأنواع التالية من موارد الويب:

  • النطاق: هو نطاق أو نطاق فرعي. يُعتبَر مالك النطاق هو مالك جميع المواقع والنطاقات الفرعية ضمن هذا النطاق. على سبيل المثال، المالك المباشر لـ bar.com يُعتبر أيضًا المالك غير المباشر للموقع الإلكتروني foo.bar.com.
  • الموقع الإلكتروني: هو عنوان URL يتوافق مع النطاق الأساسي ومسار الموقع الإلكتروني. في هذه الحالة، يكون مالك الموقع الإلكتروني مالكًا لجميع المواقع الإلكترونية المندرجة ضمنه. فعلى سبيل المثال، يُعتبر مالك الموقع http://www.example.com/site أيضًا مالكًا للموقع الإلكتروني "http://www.example.com/site/subsite".

ونظرًا إلى أنّ ملكية النطاق قابلة للتطبيق على نطاق أوسع من ملكية الموقع، نوصي بإثبات الملكية باستخدام النطاقات كلما أمكن ذلك.

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

القيود

لأسباب أمنية وتقنية، تفرض واجهة برمجة التطبيقات Google Site Verification API بعض القيود على طريقة استخدامها:

  • الوصول إلى البيانات للمستخدم الذي تمت المصادقة عليه فقط: تتطلّب جميع العمليات مصادقة المستخدم وتفويضه.
  • إثبات الملكية للمستخدم الذي تمت مصادقته فقط: لا يمكن لواجهة برمجة التطبيقات إثبات ملكية المواقع الإلكترونية أو النطاقات للحساب الذي تمت مصادقته حاليًا إلا. ومع ذلك، يمكن للمستخدم الذي تمت مصادقته تفويض الملكية إلى مستخدمين آخرين بعد إثبات ملكيته للموقع الإلكتروني. لاحظ أنه يتم إشعار جميع المالكين عبر البريد الإلكتروني عند إجراء تغييرات على قائمة الملكية.
  • عناوين URL وأسماء النطاقات التي تمت تسويتها فقط: لا تتيح واجهة برمجة التطبيقات لإثبات ملكية الموقع من Google ترميز IDN (اسم النطاق الدولي). تأكد من توافق جميع عناوين URL وأسماء النطاقات ونطاقات عناوين البريد الإلكتروني مع مجموعة أحرف اسم النطاق القياسي (RFC 1034 §3.5) باستخدام Punycoding إذا لزم الأمر.

طرق التحقق والرموز المميزة

توفّر واجهة برمجة التطبيقات طلبات لمراحل منفصلة من إثبات الملكية:

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

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

طريقة إثبات ملكية النطاق

تتوفّر طريقتان لإثبات ملكية النطاقات:

DNS_CNAME

ينشئ تطبيقك سجلّ CNAME جديدًا لنطاق المالك، ربما من خلال جهة تسجيل النطاقات لديه، باستخدام الرمز المميّز لبيانات السجلّ. يتكون الرمز المميز من جزأين مفصولين بمسافة: الجزء الأول هو اسم سجل CNAME الجديد، والجزء الثاني هو قيمة سجل CNAME الجديد.

DNS_TXT

ينشئ تطبيقك سجل TXT جديدًا لنطاق المالك، ربما من خلال جهة تسجيل النطاق لديه، باستخدام الرمز المميز لبيانات السجل.

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

طرق إثبات ملكية الموقع الإلكتروني

تتوفّر ثلاث طرق لإثبات ملكية المواقع الإلكترونية:

ملف
يضع تطبيقك الرمز المميّز في شكل ملف على الموقع الإلكتروني للمالك. يجب إنشاء ملف، مُسمى لمطابقة سلسلة الرمز المميز، مع المحتوى التالي: 
google-site-verification: token

على سبيل المثال، إذا كان المستخدم يملك الموقع http://www.example.com/ ، وكان الرمز المميّز المعروض هو google12cfc68677988bb4.html، ما عليك سوى إنشاء ملف على http://www.example.com/google12cfc68677988bb4.html (في المستوى الأعلى من موقعه الإلكتروني)، يتضمّن المحتوى التالي:

google-site-verification: google12cfc8677988bb4.html

للحصول على مزيد من المعلومات، راجِع مستندات مركز المساعدة حول طريقة إثبات ملكية الملفات.

Meta

يُدرِج تطبيقك الرمز المميّز على شكل علامة HTML <meta> ضمن العنصر <head> في الملف التلقائي (index.html أو default.html أو غير ذلك) في المستوى الأعلى من الموقع الإلكتروني للمالك. قد يظهر ملف HTML الذي يتضمن الرمز المميز لإثبات الملكية على النحو التالي:

<html>
  <head>
    <title>Awesome Dive Sites</title>
    <meta name="google-site-verification" content="-dhsoFQadgDKJR7BsB6bc1j5yfqjUpg_b-1pFjr7o3x" />
  </head>
  <body>
    ...

للحصول على مزيد من المعلومات، يمكنك الاطّلاع على مستندات مركز المساعدة حول طريقة إثبات الملكية باستخدام Meta.

الإحصاءات

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

إدارة العلامات

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

قد يفيدك فهم المفاهيم الأساسية وسير العمل إذا حاولت أولاً إثبات ملكية بضعة مواقع إلكترونية يدويًا باستخدام واجهة مستخدم "إثبات ملكية الموقع الإلكتروني".

نموذج البيانات

مورد ويب

تطبِّق واجهة برمجة التطبيقات Google Site Verification API دلالات REST (HTTP GET وPOST وما إلى ذلك) على الكيانات التي تُسمّى موارد الويب. مورد الويب هو موقع إلكتروني أو نطاق ينتمي إلى المستخدم الذي تمت مصادقته.

في ما يلي مثال على مورد ويب:

{
  "owners": [
    "myself@example.com",
    "another@example.com"
  ],
  "id": "http%3A%2F%2Fwww.example.com%2F",
  "site": {
    "identifier": "http://www.example.com/",
    "type": "SITE"
  }
}

الحقل id هو معرّف فريد لمورد الويب هذا. يمكنك استخدامه للإشارة إلى هذا المورد على الويب تحديدًا من أجل الاسترجاع والتعديل. خزِّن الحقل id من مخرجات العملية list لاستخدامه لاحقًا كمعرّف.

يحتوي الكائن site على عنوان URL أو اسم النطاق لمورد الويب، ونوع المورد. تكون المواقع الإلكترونية محدّدة بالنوع SITE. يتم تحديد النطاقات بالنوع INET_DOMAIN.

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

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

مجموعة موارد الويب

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

كما ورد سابقًا في قسم القيود، لا يمكن الوصول من خلال Site Verification API إلى موارد الويب التي تخص مستخدمين آخرين غير المستخدم الذي تمت المصادقة عليه.