Developer Knowledge API

Interfejs Developer Knowledge API umożliwia automatyczny dostęp do publicznej dokumentacji Google dla deweloperów, dzięki czemu możesz zintegrować tę bazę wiedzy z własnymi aplikacjami i przepływami pracy.

Przegląd

Interfejs Developer Knowledge API ma być kanonicznym źródłem dostępu do dokumentacji Google dla deweloperów w formacie odczytywalnym przez maszyny. Oferuje funkcje wyszukiwania i pobierania dokumentów oraz odpowiadania na zapytania:

  • SearchDocumentChunks umożliwia znajdowanie odpowiednich adresów URI stron i fragmentów treści na podstawie zapytania.
  • GetDocument lub BatchGetDocuments umożliwia pobieranie pełnej treści wyników wyszukiwania.
  • AnswerQuery umożliwia generowanie odpowiedzi na zapytania pochodzące z korpusu dokumentacji.

Interfejs Developer Knowledge API umożliwia wyszukiwanie i pobieranie stron dokumentacji jako nieustrukturyzowanej treści w formacie Markdown. Korpus treści, w których można wyszukiwać, jest wymieniony w dokumentacji korpusu.

Sposoby korzystania z Developer Knowledge

W zależności od przepływu pracy możesz uzyskać dostęp do Developer Knowledge za pomocą tych interfejsów:

  • REST API i RPC API: bezpośrednio wywołuj punkty końcowe HTTP lub gRPC. Specyfikacje metod znajdziesz w dokumentacji REST i RPC.
  • Biblioteki klienta: zintegruj interfejs Developer Knowledge API z aplikacjami za pomocą oficjalnych bibliotek klienta dla języków C#, Go, Java, Node.js i TypeScript, PHP, Python i Ruby.
  • Google Cloud CLI (gcloud): uruchamiaj gcloud developer-knowledge polecenia w terminalu, aby wyszukiwać fragmenty dokumentów, pobierać treści w formacie Markdown i generować odpowiedzi.
  • Serwer Developer Knowledge MCP: połącz asystenta kodowania lub agenta AI z dokumentacją Google za pomocą narzędzi Model Context Protocol (MCP) (search_documents, get_documents i answer_query). Więcej informacji znajdziesz w dokumentacji MCP.

Wybór między interfejsem API a serwerem MCP

Interfejs Developer Knowledge API i serwer MCP są przeznaczone do różnych potrzeb integracji:

  • Używaj interfejsu Developer Knowledge API, bibliotek klienta lub gcloud CLI, gdy:
    • Twój projekt nie korzysta z agenta AI.
    • Chcesz zdefiniować niestandardowe narzędzia lub zestawy narzędzi dla agenta.
    • Chcesz przetwarzać lub łączyć wyniki przed przekazaniem ich do modelu (np. sprawdzić długość dokumentu w bajtach przed pobraniem pełnej treści).
    • Musisz filtrować wyniki wyszukiwania (np. według data_source lub update_time) albo stosować maski pól.
  • Używaj serwera MCP Developer Knowledge i umiejętności agenta , gdy:
    • Chcesz połączyć asystenta wspomagania kodowania lub agenta AI bez pisania niestandardowych definicji i opisów narzędzi.
    • Chcesz otrzymywać automatyczne aktualizacje, gdy serwer Developer Knowledge MCP dodaje nowe funkcje.
    • Nie potrzebujesz niestandardowego filtrowania metadanych w wynikach wyszukiwania.

Włączanie interfejsu API

Aby korzystać z interfejsu Developer Knowledge API, musisz najpierw włączyć go w swoim projekcie w chmurze Google Cloud.

  1. Otwórz stronę Developer Knowledge API w bibliotece interfejsów API Google.
  2. Sprawdź, czy masz wybrany właściwy projekt, w którym chcesz używać interfejsu API.
  3. Kliknij Włącz. Do włączenia lub korzystania z interfejsu API nie są wymagane żadne konkretne role IAM.

Uwierzytelnianie

Żądania do interfejsu Developer Knowledge API możesz uwierzytelniać za pomocą jednej z tych metod:

zakresu protokołu OAuth

Podczas uwierzytelniania za pomocą protokołu OAuth 2.0 lub kont usługi interfejs Developer Knowledge API i serwer MCP akceptują te zakresy protokołu OAuth:

  • https://www.googleapis.com/auth/cloud-platform: domyślny zakres używany przez domyślne uwierzytelnianie aplikacji (ADC), gcloud CLI i oficjalne biblioteki klienta Google Cloud.
  • https://www.googleapis.com/auth/devprofiles.full_control: zakres używany w przypadku przepływów zgody użytkownika OAuth 2.0 i integracji z serwerem MCP.
  • https://www.googleapis.com/auth/developerprofiles.readonly: zakres tylko do odczytu obsługiwany w przypadku kont usługi i danych logowania, które nie wymagają ekranu zgody OAuth użytkownika.

Autoryzacja tokenem okaziciela

Aby uwierzytelnić bezpośrednie żądania REST za pomocą konta usługi lub tokena dostępu OAuth 2.0, przekaż token w nagłówku Authorization: Bearer i określ projekt rozliczeniowy w 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?"}'

Zastąp PROJECT_ID identyfikatorem projektu Google Cloud.

W przypadku aplikacji w językach Python, Node.js, Go i Java oficjalne biblioteki klienta automatycznie obsługują domyślne uwierzytelnianie aplikacji (ADC) i odświeżanie tokenów. Przykłady znajdziesz w artykule Korzystanie z bibliotek klienta z interfejsem Developer Knowledge API.

Dołączona dokumentacja

Informacje o tym, które dokumenty są przeszukiwane przez interfejs API, znajdziesz w dokumentacji korpusu.

Interfejs Developer Knowledge API ma na celu zapewnienie dostępu do najnowszej dokumentacji Google dla deweloperów. Naszym celem jest ponowne indeksowanie treści w ciągu 48 godzin od publikacji, aby nowa lub zaktualizowana dokumentacja była dostępna w ciągu 2 dni roboczych.

Znane ograniczenia

  • Jakość formatu Markdown: format Markdown jest generowany ze źródłowego kodu HTML. Mogą występować pewne rozbieżności lub problemy z formatowaniem.
  • Zakres treści: uwzględniane są tylko strony publiczne w dokumentacji korpusu. Treści z innych źródeł, takich jak GitHub, witryny OSS, blogi czy YouTube, nie są uwzględniane.