المتطلبات الأساسية

يصف هذا المستند الأشياء التي يجب عليك القيام بها قبل كتابة تطبيق العميل الأول.

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

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

تجربة Google Search Console

تفترض مستندات واجهة برمجة التطبيقات هذه أنّك استخدمت Google Search Console وأنّك على دراية بمفاهيم برمجة الويب وتنسيقات بيانات الويب.

إذا لم يسبق لك استخدام Google Search Console، ننصحك بتجربة واجهة المستخدم قبل بدء الترميز. تمثّل كل واجهة برمجة تطبيقات وظيفة تقرير في Search Console. لفهم البيانات التي تتلقّاها، يجب قراءة المستندات الخاصة بالتقرير المكافئ قبل استخدام واجهة برمجة التطبيقات.

إنشاء مشروع وبيانات اعتماد لعميلك

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

تتطلب جميع واجهات برمجة تطبيقات Search Console بيانات اعتماد OAuth2، باستثناء واجهة برمجة التطبيقات الخاصة بـ "أدوات الاختبار". توفر أدلة البدء السريع للغة Python وJava تفاصيل حول كيفية إنشاء مشروع والحصول على بيانات الاعتماد لعميلك.

فهم أساسيات REST

هناك طريقتان لاستدعاء واجهة برمجة التطبيقات:

إذا قررت عدم استخدام مكتبات العملاء، فستحتاج إلى فهم أساسيات REST.

أساسيات REST

REST هو نمط من بنية البرامج التي توفر نهجًا مناسبًا ومتسقًا لطلب البيانات وتعديلها.

إنّ المصطلح REST هو اختصار لـ "التحويل التمثيلي للولاية". في سياق Google APIs، يشير ذلك إلى استخدام أفعال HTTP لاسترداد وتعديل تمثيلات البيانات التي خزنتها Google.

في نظام REST، يتم تخزين الموارد في مخزن بيانات؛ يرسل العميل طلبًا بأن يقوم الخادم بتنفيذ إجراء معين (مثل إنشاء مورد أو استرداده أو تحديثه أو حذفه)، وينفذ الخادم الإجراء ويرسل استجابة غالبًا في شكل تمثيل للمورد المحدد.

في واجهات برمجة التطبيقات RESTful من Google، يحدّد العميل إجراءً باستخدام فعل HTTP مثل POST أو GET أو PUT أو DELETE. يحدد موردًا من خلال معرف موارد منتظم (URI) فريد عالميًا بالصيغة التالية:

https://www.googleapis.com/apiName/apiVersion/resourcePath?parameters

ونظرًا لأن جميع موارد واجهة برمجة التطبيقات تتضمن معرفات موارد منتظمة (URI) فريدة يمكن الوصول إليها عبر HTTP، فإن REST تتيح التخزين المؤقت للبيانات ويتم تحسينها للعمل مع البنية الأساسية الموزَّعة على الويب.

قد تجد تعريفات الطريقة في مستندات معايير HTTP 1.1 مفيدة، وتضم مواصفات GET وPOST وPUT وDELETE.

بروتوكول REST في واجهة برمجة التطبيقات في Google Search Console

ترتبط عمليات واجهة برمجة التطبيقات في Google Search Console مباشرةً بأفعال REST HTTP.

يظهر تنسيق معظم معرّفات الموارد المنتظمة (URI) لواجهة برمجة التطبيقات الخاصة بخدمة Google Search Console على النحو التالي:

VERB https://www.googleapis.com/webmasters/v3/resourcePath?parameters

يمكنك الاطّلاع على المجموعة الكاملة من معرّفات الموارد المنتظمة (URI) والأفعال المُستخدَمة لكل طريقة في النظرة العامة على مرجع واجهة برمجة التطبيقات في Google Search Console.

فهم أساسيات JSON

تعرض واجهة برمجة التطبيقات لخدمة Google Search Console البيانات بتنسيق JSON.

JSON (JavaScript Object Notation) هو تنسيق بيانات شائع ومستقل عن اللغة ويقدم تمثيلاً نصيًا بسيطًا بُنى البيانات العشوائية. لمزيد من المعلومات، راجع json.org.