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

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

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

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

تجربة Google Search Console

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

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

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

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

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

فهم أساسيات REST

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

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

أساسيات REST

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

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

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

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

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

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

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

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

يتم ربط عمليات واجهة برمجة التطبيقات في 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 .