Developer Knowledge API دسترسی برنامه‌ریزی‌شده به مستندات عمومی توسعه‌دهنده Google را فراهم می‌کند و به شما امکان می‌دهد این پایگاه دانش را در برنامه‌ها و گردش‌های کاری خود ادغام کنید.
نمای کلی
«میانای برنامه‌سازی کاربردی دانش توسعه‌دهنده» به‌عنوان منبع متعارف برای دسترسی ماشین‌خوان به اسناد توسعه‌دهنده Google طراحی شده است. این مدل توابعی برای جستجو و بازیابی اسناد و پاسخ به پُرسمان‌ها ارائه می‌دهد:
SearchDocumentChunksبرای پیدا کردن شناسه منبع یکسان صفحه مربوط و گزیده‌های محتوا براساس پُرسمان.GetDocumentیاBatchGetDocumentsبرای واکشی محتوای کامل نتیجه(های) جستجو.AnswerQueryبرای تولید پاسخ به پُرسمان‌های برگرفته از مجموعه اسناد.
Developer Knowledge API از جستجو و بازیابی صفحه‌های اسناد به‌عنوان محتوای Markdown بدون ساختار پشتیبانی می‌کند. پیکره محتوای قابل‌جستجو در مرجع پیکره فهرست شده است.
روش‌های استفاده از «دانش توسعه‌دهنده»
بسته به گردش کارتان، می‌توانید ازطریق سطوح زیر به «دانش توسعه‌دهنده» دسترسی پیدا کنید:
- REST API و RPC API: نقاط پایانی HTTP یا gRPC را مستقیماً فراخوانی کنید. برای مشخصات روش، به مرجع REST و مرجع RPC مراجعه کنید.
- کتابخانه‌های کارخواه: Developer Knowledge API را بااستفاده از کتابخانه‌های کارخواه رسمی برای C#، Go، Java، Node.js و TypeScript، PHP، Python، و Ruby در برنامه‌هایتان ادغام کنید.
- Google Cloud CLI (
gcloud): دستوراتgcloud developer-knowledgeرا از پایانه خود اجرا کنید تا بخش‌های سند را جستجو کنید، محتوای Markdown را واکشی کنید، و پاسخ تولید کنید. - سرور MCP دانش توسعه‌دهنده: دستیار یا عامل کدنویسی هوش مصنوعی خود را بااستفاده از ابزارهای «پروتکل بافتار مدل» (MCP) (
search_documents،get_documents، وanswer_query) به اسناد Google متصل کنید. به مرجع MCP مراجعه کنید.
انتخاب بین API و سرور MCP
Developer Knowledge API و سرور Developer Knowledge MCP برای نیازهای ادغام متفاوت طراحی شده‌اند:
- از Developer Knowledge API، کتابخانه‌های کارخواه، یا gcloud CLI استفاده کنید وقتی:
- پروژه شما از عامل هوش مصنوعی استفاده نمی‌کند.
- می‌خواهید ابزارها یا مجموعه‌های ابزار سفارشی را برای عاملتان تعریف کنید.
- می‌خواهید نتایج را قبل‌از ارسال به مدل پردازش یا ترکیب کنید (برای مثال، بررسی طول بایت سند قبل‌از واکشی محتوای کامل).
- باید
نتایج جستجو را فیلتر کنید
(مثلاً براساس
data_sourceیاupdate_time) یا پوشش‌های فیلد را اعمال کنید.
- از سرور MCP و مهارت عامل Developer Knowledge استفاده کنید وقتی:
- می‌خواهید بدون نوشتن تعریف‌ها و شرح‌های ابزار سفارشی، دستیار کدنویسی هوش مصنوعی یا کارگزاری را متصل کنید.
- می‌خواهید با اضافه شدن قابلیت‌های جدید به سرور MCP «دانش توسعه‌دهنده»، به‌روزرسانی‌ها به‌طور خودکار انجام شود.
- به فیلتر کردن فراداده سفارشی در نتایج جستجو نیاز ندارید.
فعال کردن میانای برنامه‌سازی کاربردی
برای استفاده از Developer Knowledge API، ابتدا باید آن را برای پروژه Google Cloud خود فعال کنید.
- صفحه Developer Knowledge API را در کتابخانه Google APIs باز کنید.
- بررسی کنید پروژه صحیحی را که قصد دارید در آن از API استفاده کنید انتخاب کرده باشید.
- روی فعال کردن کلیک کنید. برای فعال کردن یا استفاده از API، به نقش‌های IAM خاصی نیاز نیست.
اصالت‌سنجی
می‌توانید درخواست‌های ارسال‌شده به Developer Knowledge API را بااستفاده از یکی از روش‌های زیر اصالت‌سنجی کنید:
- کلید API: اصالت‌سنجی درخواست‌های REST مستقیم یا
سرور MCP «دانش توسعه‌دهنده» بااستفاده از پارامتر پُرسمان
keyیا سرصفحهX-Goog-Api-Key. - اطلاعات اعتباری پیش‌فرض برنامه (ADC)، OAuth 2.0، یا حساب‌های سرویس: هنگام استفاده از کتابخانه‌های کارخواه رسمی یا گردش‌های کار تولید، درخواست‌ها را درستی‌سنجی کنید. برای کسب اطلاعات بیشتر درباره تنظیم اعتبارنامه‌ها، به اسناد اعتبارنامه‌های پیش‌فرض برنامه مراجعه کنید.
- اعتبارنامه‌های کاربر (gcloud CLI): با ورود به سیستم حساب Google Cloud خود با
gcloud auth login، درخواست‌های CLI را اصالت‌سنجی کنید. برای دستورالعمل‌های راه‌اندازی، به شروع سریع gcloud CLI مراجعه کنید.
حوزه‌های OAuth
هنگام اصالت‌سنجی با OAuth 2.0 یا حساب‌های سرویس، سرور Developer Knowledge MCP و Developer Knowledge API دامنه‌های 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 مراجعه کنید.
اسناد موجود
برای کسب اطلاعات درباره اینکه کدام اسناد توسط API جستجو می‌شوند، به مرجع مجموعه پیکره مراجعه کنید.
هدف «میانای برنامه‌سازی کاربردی دانش توسعه‌دهندگان» ارائه دسترسی به جدیدترین اسناد توسعه‌دهندگان Google است. هدف ما این است که محتوا را ظرف ۴۸ ساعت پس‌از انتشار مجدداً نمایه‌سازی کنیم تا اسناد جدید یا به‌روزشده ظرف ۲ روز کاری دردسترس قرار گیرد.محدودیت‌های شناخته‌شده
- کیفیت Markdown: Markdown از HTML منبع تولید می‌شود. ممکن است برخی‌از موارد با هم مطابقت نداشته باشند یا مشکل قالب‌بندی وجود داشته باشد.
- محدوده محتوا: فقط صفحه‌های عمومی در مرجع مجموعه پیکره گنجانده می‌شود. محتوای منابع دیگر مانند GitHub، سایت‌های OSS، وبلاگ‌ها، یا YouTube درنظر گرفته نمی‌شود.