Developer Knowledge API

توفّر واجهة برمجة التطبيقات Developer Knowledge API إمكانية الوصول الآلي إلى مستندات المطوّرين العامة من Google، ما يتيح لك دمج قاعدة المعلومات هذه في تطبيقاتك وسير عملك.

نظرة عامة

تم تصميم واجهة برمجة التطبيقات Developer Knowledge API لتكون المصدر الأساسي الذي يتيح الوصول إلى مستندات المطوّرين من Google بتنسيق يمكن معالجتها آليًا. ويوفّر وظائف للبحث عن المستندات واستردادها والإجابة عن طلبات البحث:

• SearchDocumentChunks للعثور على معرّفات الموارد المنتظمة (URI) للصفحات ذات الصلة ومقتطفات المحتوى استنادًا إلى طلب بحث.
• GetDocument أو BatchGetDocuments لجلب المحتوى الكامل لنتائج البحث
• AnswerQuery لإنشاء إجابات عن طلبات البحث المستخرَجة من مجموعة المستندات

تتيح واجهة Developer Knowledge API البحث عن صفحات المستندات واستردادها كمحتوى Markdown غير منظَّم. يتم إدراج مجموعة المحتوى القابل للبحث في مرجع مجموعة المحتوى.

طرق استخدام Developer Knowledge

يمكنك الوصول إلى Developer Knowledge من خلال المساحات التالية حسب سير العمل:

• REST API وRPC API: يمكنك طلب نقاط نهاية HTTP أو gRPC مباشرةً. يُرجى الرجوع إلى مرجع REST ومرجع RPC للاطّلاع على مواصفات الطريقة.
• مكتبات البرامج: يمكنك دمج Developer Knowledge API في تطبيقاتك باستخدام مكتبات البرامج الرسمية للغات C#‎ وGo وJava وNode.js وTypeScript وPHP وPython وRuby.
• واجهة سطر الأوامر (CLI) في Google Cloud (gcloud): يمكنك تنفيذ أوامر gcloud developer-knowledge من نافذة الأوامر للبحث عن أجزاء من المستندات وجلب محتوى Markdown وإنشاء إجابات.
• خادم "بروتوكول سياق النموذج" (MCP) الخاص بـ Developer Knowledge: يمكنك ربط مساعدك أو وكيلك في البرمجة المستندَين إلى الذكاء الاصطناعي بمستندات Google باستخدام أدوات "بروتوكول سياق النموذج" (MCP) (search_documents وget_documents وanswer_query). يُرجى الرجوع إلى مرجع "بروتوكول سياق النموذج" (MCP).

ملاحظة: إذا كنت تستخدم مساعد ترميز يعمل بالذكاء الاصطناعي، ثبِّت مهارة وكيل retrieving-developer-knowledge من خلال تنفيذ npx skills add google/skills --skill retrieving-developer-knowledge. توفّر هذه المهارة لمساعدك تعليمات مدمجة حول أداة خادم MCP الخاصة بـ Developer Knowledge التي يجب اختيارها، وكيفية التعامل مع الأخطاء، وكيفية طلب REST API باستخدام curl في حال عدم توفّر خادم MCP. لمزيد من المعلومات، يُرجى الاطّلاع على المقالة استخدام مهارة "قاعدة معلومات المطوّرين".

الاختيار بين واجهة برمجة التطبيقات وخادم MCP

تم تصميم واجهة برمجة التطبيقات Developer Knowledge API وخادم Developer Knowledge MCP لتلبية احتياجات مختلفة في ما يتعلّق بعمليات الدمج:

• استخدام Developer Knowledge API أو مكتبات البرامج أو gcloud CLI في الحالات التالية:
  • لا يستخدم مشروعك وكيل ذكاء اصطناعي.
  • تريد تحديد أدوات أو مجموعات أدوات مخصّصة للوكيل.
  • تريد معالجة النتائج أو دمجها قبل تمريرها إلى نموذج (على سبيل المثال، التحقّق من طول بايت المستند قبل جلب المحتوى الكامل).
  • عليك فلترة نتائج البحث (مثلاً حسب data_source أو update_time) أو تطبيق أقنعة الحقول.
• استخدِم خادم MCP ومهارة الوكيل في "معرفة المطوّرين" في الحالات التالية:
  • إذا أردت ربط مساعد أو وكيل برمجة مستنِد إلى الذكاء الاصطناعي بدون كتابة تعريفات وأوصاف مخصّصة للأدوات
  • تريد الحصول على تحديثات تلقائية عندما يضيف خادم MCP الخاص بـ "معرفة المطوّرين" إمكانات جديدة.
  • لا تحتاج إلى فلترة البيانات الوصفية المخصّصة في نتائج البحث.

تفعيل واجهة برمجة التطبيقات

لاستخدام Developer Knowledge API، عليك أولاً تفعيلها لمشروعك على Google Cloud.

ملاحظة: إذا لم يكن لديك مشروع على السحابة الإلكترونية من Google، يمكنك إنشاء مشروع باتّباع تعليمات Google Cloud أو Firebase.

1. افتح صفحة Developer Knowledge API في مكتبة Google APIs.
2. تأكَّد من اختيار المشروع الصحيح الذي تريد استخدام واجهة برمجة التطبيقات فيه.
3. انقر على تفعيل. لا تتطلّب واجهة برمجة التطبيقات أي أدوار محدّدة في "إدارة الهوية وإمكانية الوصول" لتفعيلها أو استخدامها.

المصادقة

يمكنك مصادقة الطلبات المرسَلة إلى Developer Knowledge API باستخدام إحدى الطرق التالية:

• مفتاح واجهة برمجة التطبيقات: يمكنك مصادقة طلبات REST المباشرة أو خادم MCP الخاص بـ Developer Knowledge باستخدام مَعلمة طلب البحث key أو العنوان X-Goog-Api-Key.
• بيانات الاعتماد التلقائية للتطبيق (ADC) أو OAuth 2.0 أو حسابات الخدمة: تتم مصادقة الطلبات عند استخدام مكتبات البرامج الرسمية أو إجراءات سير العمل الخاصة بالإنتاج. لمزيد من المعلومات حول إعداد بيانات الاعتماد، راجِع مستندات "بيانات الاعتماد التلقائية للتطبيق".
• بيانات اعتماد المستخدم (gcloud CLI): يمكنك مصادقة طلبات واجهة سطر الأوامر (CLI) من خلال تسجيل الدخول إلى حسابك على Google Cloud باستخدام gcloud auth login. راجِع دليل البدء السريع في gcloud CLI للحصول على تعليمات الإعداد.

نطاقات OAuth

عند المصادقة باستخدام OAuth 2.0 أو حسابات الخدمة، تقبل واجهة Developer Knowledge API وخادم Developer Knowledge MCP نطاقات OAuth التالية:

• ‫https://www.googleapis.com/auth/cloud-platform: النطاق التلقائي الذي تستخدمه "بيانات الاعتماد التلقائية للتطبيق" (ADC) وgcloud CLI ومكتبات برامج Google Cloud الرسمية
• ‫https://www.googleapis.com/auth/devprofiles.full_control: النطاق المستخدَم في عمليات موافقة المستخدمين على OAuth 2.0 وعمليات التكامل مع خادم MCP.
• ‫https://www.googleapis.com/auth/developerprofiles.readonly: إذن بالقراءة فقط نطاق متاح لحسابات الخدمة وبيانات الاعتماد التي لا تتطلّب شاشة طلب موافقة OAuth للمستخدم النهائي.

تفويض رمز الحامل المميّز

لإجراء مصادقة لطلبات REST المباشرة باستخدام حساب خدمة أو رمز مميّز للوصول إلى OAuth 2.0، مرِّر الرمز المميّز في العنوان Authorization: Bearer وحدِّد مشروع الفوترة في X-Goog-User-Project:

export ACCESS_TOKEN=$(gcloud auth print-access-token)
curl -X POST "https://developerknowledge.googleapis.com/v1:answerQuery" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-Goog-User-Project: PROJECT_ID" \
  -H "Content-Type: application/json" \
  -d '{"query": "How do I create a BigQuery dataset?"}'

استبدِل PROJECT_ID برقم تعريف مشروعك على Google Cloud.

بالنسبة إلى تطبيقات Python وNode.js وGo وJava، تتعامل مكتبات العملاء الرسمية مع "بيانات الاعتماد التلقائية للتطبيق" (ADC) وعمليات إعادة تحميل الرموز المميّزة تلقائيًا. للاطّلاع على أمثلة، يُرجى الرجوع إلى استخدام مكتبات العملاء مع Developer Knowledge API.

المستندات المضمّنة

يُرجى الرجوع إلى مرجع Corpus للحصول على معلومات حول المستندات التي تبحث عنها واجهة برمجة التطبيقات.

تهدف واجهة برمجة التطبيقات Developer Knowledge API إلى توفير إمكانية الوصول إلى أحدث مستندات المطوّرين من Google. هدفنا هو إعادة فهرسة المحتوى في غضون 48 ساعة من نشره، ليصبح المستند الجديد أو المعدَّل متاحًا في غضون يومَي عمل.

القيود المعروفة

• جودة Markdown: يتم إنشاء Markdown من مصدر HTML. قد تكون هناك بعض التناقضات أو مشكلات التنسيق.
• نطاق المحتوى: يتم تضمين الصفحات المتاحة للجميع فقط في مرجع المجموعة. لا يتم تضمين المحتوى من مصادر أخرى، مثل GitHub أو مواقع البرامج المفتوحة المصدر أو المدونات أو YouTube.