البدء

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

مقدمة

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

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

نظرة عامة

يمكنك استخدام واجهة برمجة التطبيقات لإثبات ملكية المواقع من Google لتعديل بيانات إثبات ملكية موقع المستخدم على 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 Site Verification API في وحدة تحكّم 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 لإثبات ملكية المستخدم للأنواع التالية من موارد الويب:

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

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

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

القيود

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

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

طرق إثبات الملكية والرموز المميّزة

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

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

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

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

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

DNS_CNAME

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

_نظام أسماء النطاقات_TXT

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

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

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

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

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

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

google-site-verification: google12cfc8677988bb4.html

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

Meta

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

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

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

إحصاءات

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

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

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

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

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

مرجع الويب

تُطبِّق واجهة برمجة تطبيقات إثبات ملكية مواقع Google الإلكترونية دلالات 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 أو اسم النطاق لمورد الويب&#39، ونوع المورد. ويتم تحديد المواقع الإلكترونية من النوع SITE، في حين يتم تحديد النطاقات بالنوع INET_DOMAIN.

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

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

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

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

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