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.
• Google Cloud CLI (gcloud): выполняйте команды gcloud developer-knowledge в терминале, чтобы искать фрагменты документов, получать контент в формате Markdown и генерировать ответы.
• Сервер MCP Developer Knowledge. Подключите ИИ-помощника по написанию кода или агента к документации Google с помощью инструментов Model Context Protocol (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 недоступен. Подробнее о том, как использовать навык агента Developer Knowledge…

Как выбрать между API и MCP-сервером

API знаний о разработчиках и MCP-сервер знаний о разработчиках предназначены для разных целей интеграции:

• Используйте Developer Knowledge API, клиентские библиотеки или gcloud CLI, если:
  • В вашем проекте не используется ИИ-агент.
  • Вы хотите определить собственные инструменты или наборы инструментов для агента.
  • Вам нужно обработать или объединить результаты, прежде чем передавать их модели (например, проверить длину документа в байтах, прежде чем получать его полное содержимое).
  • Вам нужно отфильтровать результаты поиска (например, по data_source или update_time) или применить маски полей.
• Используйте MCP-сервер и навык агента Developer Knowledge, если:
  • Вы хотите подключить ИИ-помощника или агента по помощи в программировании, не создавая собственные определения и описания инструментов.
  • Вы хотите, чтобы обновления устанавливались автоматически, когда на MCP-сервере Developer Knowledge появляются новые возможности.
  • Вам не нужна фильтрация результатов поиска по специальным метаданным.

Включение API

Чтобы использовать Developer Knowledge API, сначала нужно включить его для проекта Google Cloud.

Совет. Если у вас нет облачного проекта Google Cloud, создайте его, следуя инструкциям для Google Cloud или Firebase.

1. Откройте страницу Developer Knowledge API в библиотеке API Google.
2. Убедитесь, что выбран нужный проект, в котором вы планируете использовать API.
3. Нажмите Включить. Для включения или использования API не требуются определенные роли IAM.

Аутентификация

Запросы к Developer Knowledge API можно аутентифицировать одним из следующих способов:

• Ключ API. Выполните аутентификацию прямых REST-запросов или MCP-сервера Developer Knowledge с помощью параметра запроса key или заголовка X-Goog-Api-Key.
• Стандартные учетные данные приложения (ADC), OAuth 2.0 или сервисные аккаунты – аутентификация запросов при использовании официальных клиентских библиотек или рабочих процессов. Подробнее о том, как настроить учетные данные, рассказывается в документации по Application Default Credentials.
• Учетные данные пользователя (gcloud CLI). Аутентифицируйте запросы CLI, войдя в аккаунт Google Cloud с помощью команды gcloud auth login. Инструкции по настройке приведены в кратком руководстве по gcloud CLI.

Области действия OAuth

При аутентификации с помощью OAuth 2.0 или сервисных аккаунтов Developer Knowledge API и MCP-сервер Developer Knowledge принимают следующие области действия OAuth:

• https://www.googleapis.com/auth/cloud-platform – область действия по умолчанию, используемая Application Default Credentials (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 официальные клиентские библиотеки автоматически обрабатывают Application Default Credentials (ADC) и обновление токенов. Примеры приведены в статье Как использовать клиентские библиотеки с Developer Knowledge API.

Документация в комплекте

Информацию о том, какие документы ищет API, можно найти в справочнике по корпусу.

Developer Knowledge API предоставляет доступ к актуальной документации Google для разработчиков. Мы стремимся повторно индексировать контент в течение 48 часов после публикации, чтобы новая или обновленная документация была доступна в течение двух рабочих дней.

Известные ограничения

• Качество разметки. Разметка генерируется на основе исходного HTML-кода. Возможны неточности и проблемы с форматированием.
• Область контента. Включаются только общедоступные страницы из справочного корпуса. Контент из других источников, таких как GitHub, сайты с открытым исходным кодом, блоги или YouTube, не учитывается.