В этом руководстве рассказывается, как начать работу с Developer Knowledge API, используя официальные клиентские библиотеки. Вы узнаете, как настроить среду, установить клиентскую библиотеку для нужного языка и выполнять вызовы API для поиска и получения документации для разработчиков.
Подготовка
Прежде чем начать использовать клиентские библиотеки Developer Knowledge API, выполните инструкции из следующих разделов.
Включение API
- Откройте страницу Developer Knowledge API в библиотеке API Google.
- Убедитесь, что выбран нужный проект, в котором вы планируете использовать API.
- Нажмите Включить. Для включения и использования API не требуются специальные роли IAM.
Как настроить аутентификацию
Клиентские библиотеки Developer Knowledge API используют учетные данные по умолчанию (ADC) для аутентификации запросов.
Чтобы настроить учетные данные для локальной аутентификации, выполните следующую команду:
gcloud auth application-default login
Чтобы узнать больше о вариантах учетных данных, например сервисных аккаунтах, ознакомьтесь с документацией по Application Default Credentials.
Установите клиентскую библиотеку
Чтобы установить официальную клиентскую библиотеку API Developer Knowledge, выберите язык программирования:
Python
pip install --upgrade google-developer-knowledge
Node.js и TypeScript
npm install @google/developer-knowledge
Проложить маршрут
go get cloud.google.com/go/developerknowledge/apiv1
Java
Если вы используете Maven, добавьте в файл pom.xml следующую зависимость:
<dependency>
<groupId>com.google.cloud</groupId>
<artifactId>google-cloud-developer-knowledge</artifactId>
<version>0.6.0</version>
</dependency>
Если вы используете Gradle, добавьте в файл build.gradle следующую зависимость:
implementation 'com.google.cloud:google-cloud-developer-knowledge:0.6.0'
Как получать ответы на основе документации
Конечная точка AnswerQuery отвечает на сложные вопросы, заданные на естественном языке, например о настройке кода, устранении неполадок и возможностях продукта, используя информацию из официальной документации.
Выберите вкладку с языком, чтобы посмотреть пример того, как позвонить на номер AnswerQuery:
Python
from google.cloud import developer_knowledge_v1
def answer_query(
query: str = "How do I create a Google Cloud Storage bucket?",
) -> developer_knowledge_v1.AnswerQueryResponse:
"""Answers a developer question grounded in Google developer documentation.
Args:
query: The technical question to answer.
Returns:
The AnswerQueryResponse containing the grounded answer,
citations, and references.
"""
client = developer_knowledge_v1.DeveloperKnowledgeClient()
request = developer_knowledge_v1.AnswerQueryRequest(
query=query,
)
response = client.answer_query(request=request)
print(f"Answer:\n{response.answer.answer_text}\n")
print(f"Citations count: {len(response.answer.citations)}")
print(f"References count: {len(response.answer.references)}")
return response
Node.js и TypeScript
const {DeveloperKnowledgeClient} = require('@google/developer-knowledge');
/**
* Answers a developer question grounded in Google developer documentation.
*
* @param {string} query The technical question to answer.
*/
async function answerQuery(
query = 'How do I create a Google Cloud Storage bucket?'
) {
const client = new DeveloperKnowledgeClient();
const request = {
query,
};
const [response] = await client.answerQuery(request);
console.log(`Answer:\n${response.answer.answerText}\n`);
const citationsCount = response.answer.citations
? response.answer.citations.length
: 0;
const referencesCount = response.answer.references
? response.answer.references.length
: 0;
console.log(`Citations count: ${citationsCount}`);
console.log(`References count: ${referencesCount}`);
return response;
}
Проложить маршрут
import (
"context"
"fmt"
"io"
developerknowledge "cloud.google.com/go/developerknowledge/apiv1"
developerknowledgepb "cloud.google.com/go/developerknowledge/apiv1/developerknowledgepb"
)
// answerQuery answers a developer question grounded in Google developer documentation.
func answerQuery(w io.Writer, query string) (*developerknowledgepb.AnswerQueryResponse, error) {
ctx := context.Background()
client, err := developerknowledge.NewDeveloperKnowledgeClient(ctx)
if err != nil {
return nil, fmt.Errorf("developerknowledge.NewDeveloperKnowledgeClient: %w", err)
}
defer client.Close()
req := &developerknowledgepb.AnswerQueryRequest{
Query: query,
}
resp, err := client.AnswerQuery(ctx, req)
if err != nil {
return nil, fmt.Errorf("AnswerQuery: %w", err)
}
if resp.GetAnswer() != nil {
fmt.Fprintf(w, "Answer:\n%s\n\n", resp.GetAnswer().GetAnswerText())
fmt.Fprintf(w, "Citations count: %d\n", len(resp.GetAnswer().GetCitations()))
fmt.Fprintf(w, "References count: %d\n", len(resp.GetAnswer().GetReferences()))
}
return resp, nil
}
Java
import com.google.developers.knowledge.v1.AnswerQueryRequest;
import com.google.developers.knowledge.v1.AnswerQueryResponse;
import com.google.developers.knowledge.v1.DeveloperKnowledgeClient;
import java.io.IOException;
public class AnswerQuery {
public static void main(String[] args) throws IOException {
// TODO(developer): Replace these variables before running the sample.
String query = "How do I create a Google Cloud Storage bucket?";
answerQuery(query);
}
// Answers a developer question grounded in Google developer documentation.
public static AnswerQueryResponse answerQuery(String query) throws IOException {
// Initialize client that will be used to send requests. This client only needs to be created
// once, and can be reused for multiple requests. After completing all of your requests, call
// the "close" method on the client to safely clean up any remaining background resources.
try (DeveloperKnowledgeClient client = DeveloperKnowledgeClient.create()) {
AnswerQueryRequest request =
AnswerQueryRequest.newBuilder().setQuery(query).build();
AnswerQueryResponse response = client.answerQuery(request);
System.out.println("Answer:\n" + response.getAnswer().getAnswerText() + "\n");
System.out.println("Citations count: " + response.getAnswer().getCitationsCount());
System.out.println("References count: " + response.getAnswer().getReferencesCount());
return response;
}
}
}
Поиск фрагментов документов
Чтобы найти в документации точные фрагменты текста на определенном языке, а не сгенерированный ответ, используйте конечную точку SearchDocumentChunks. Этот метод сканирует корпус и возвращает отдельные фрагменты контента вместе с идентификаторами родительских документов, которые можно использовать для получения полного контента документа.
Чтобы посмотреть пример поиска фрагментов документа, выберите вкладку с нужным языком:
Python
from google.cloud import developer_knowledge_v1
def search_document_chunks(
query: str = "How to create a Cloud Storage bucket",
page_size: int = 5,
) -> (
developer_knowledge_v1.services.developer_knowledge.pagers.SearchDocumentChunksPager
):
"""Searches developer documentation chunks for a given query.
Args:
query: The natural language search query.
page_size: The maximum number of document chunks to return.
Returns:
The SearchDocumentChunksPager containing relevant document chunks.
"""
client = developer_knowledge_v1.DeveloperKnowledgeClient()
request = developer_knowledge_v1.SearchDocumentChunksRequest(
query=query,
page_size=page_size,
)
response = client.search_document_chunks(request=request)
count = 0
for chunk in response:
print(f"Parent Document: {chunk.parent}")
print(f"Chunk ID: {chunk.id}")
print(f"Content: {chunk.content[:100]}...\n")
count += 1
if page_size > 0 and count >= page_size:
break
return response
Node.js и TypeScript
const {DeveloperKnowledgeClient} = require('@google/developer-knowledge');
/**
* Searches developer documentation chunks for a given query.
*
* @param {string} query The search query string.
* @param {number} pageSize The maximum number of document chunks to return.
*/
async function searchDocumentChunks(
query = 'How to create a Cloud Storage bucket',
pageSize = 5
) {
const client = new DeveloperKnowledgeClient();
const request = {
query,
pageSize,
};
// Warning: Should always disable autoPaginate to avoid iterating through all pages.
// By default NodeJS SDK returns an iterable where you can iterate through all
// search results instead of only the limited number of results requested on pageSize.
const [chunks] = await client.searchDocumentChunks(request, {
autoPaginate: false,
});
for (const chunk of chunks) {
console.log(`Parent Document: ${chunk.parent}`);
console.log(`Chunk ID: ${chunk.id}`);
console.log(`Content Preview: ${chunk.content.substring(0, 100)}...\n`);
}
return chunks;
}
Проложить маршрут
import (
"context"
"fmt"
"io"
developerknowledge "cloud.google.com/go/developerknowledge/apiv1"
developerknowledgepb "cloud.google.com/go/developerknowledge/apiv1/developerknowledgepb"
"google.golang.org/api/iterator"
)
// searchDocumentChunks searches developer documentation chunks for a given query.
func searchDocumentChunks(w io.Writer, query string, pageSize int32) ([]*developerknowledgepb.DocumentChunk, error) {
ctx := context.Background()
client, err := developerknowledge.NewDeveloperKnowledgeClient(ctx)
if err != nil {
return nil, fmt.Errorf("developerknowledge.NewDeveloperKnowledgeClient: %w", err)
}
defer client.Close()
req := &developerknowledgepb.SearchDocumentChunksRequest{
Query: query,
PageSize: pageSize,
}
var results []*developerknowledgepb.DocumentChunk
it := client.SearchDocumentChunks(ctx, req)
for {
chunk, err := it.Next()
if err == iterator.Done {
break
}
if err != nil {
return nil, fmt.Errorf("SearchDocumentChunks: %w", err)
}
results = append(results, chunk)
fmt.Fprintf(w, "Parent Document: %s\n", chunk.GetParent())
fmt.Fprintf(w, "Chunk ID: %s\n", chunk.GetId())
fmt.Fprintf(w, "Content: %s\n\n", chunk.GetContent())
if pageSize > 0 && len(results) >= int(pageSize) {
break
}
}
return results, nil
}
Java
import com.google.developers.knowledge.v1.DeveloperKnowledgeClient;
import com.google.developers.knowledge.v1.DeveloperKnowledgeClient.SearchDocumentChunksPagedResponse;
import com.google.developers.knowledge.v1.DocumentChunk;
import com.google.developers.knowledge.v1.SearchDocumentChunksRequest;
import java.io.IOException;
public class SearchDocumentChunks {
public static void main(String[] args) throws IOException {
// TODO(developer): Replace these variables before running the sample.
String query = "How to create a Cloud Storage bucket";
int pageSize = 5;
searchDocumentChunks(query, pageSize);
}
// Searches developer documentation chunks for a given query.
public static SearchDocumentChunksPagedResponse searchDocumentChunks(
String query, int pageSize) throws IOException {
// Initialize client that will be used to send requests. This client only needs to be created
// once, and can be reused for multiple requests. After completing all of your requests, call
// the "close" method on the client to safely clean up any remaining background resources.
try (DeveloperKnowledgeClient client = DeveloperKnowledgeClient.create()) {
SearchDocumentChunksRequest request =
SearchDocumentChunksRequest.newBuilder()
.setQuery(query)
.setPageSize(pageSize)
.build();
SearchDocumentChunksPagedResponse response = client.searchDocumentChunks(request);
for (DocumentChunk chunk : response.getPage().getValues()) {
System.out.println("Parent Document: " + chunk.getParent());
System.out.println("Chunk ID: " + chunk.getId());
String preview = chunk.getContent();
if (preview.length() > 100) {
preview = preview.substring(0, 100) + "...";
}
System.out.println("Content: " + preview + "\n");
}
return response;
}
}
}
Как найти документ
Каждый фрагмент документа содержит поле parent с названием ресурса родительского документа. Используйте GetDocument с названием ресурса, чтобы получить полный документ.
В приведенных ниже примерах показано, как получить образец документа. Вы можете заменить название sample
document любым названием ресурса parent, полученным в результатах поиска.
Выберите вкладку с языком, чтобы посмотреть пример того, как позвонить на номер GetDocument:
Python
from google.cloud import developer_knowledge_v1
def get_document(
name: str = "documents/docs.cloud.google.com/storage/docs/creating-buckets",
) -> developer_knowledge_v1.Document:
"""Retrieves a single developer documentation page by its resource name.
Args:
name: The resource name of the document in format
'documents/{uri_without_scheme}'.
Returns:
The Document containing the full Markdown content and metadata.
"""
client = developer_knowledge_v1.DeveloperKnowledgeClient()
request = developer_knowledge_v1.GetDocumentRequest(
name=name,
)
document = client.get_document(request=request)
print(f"Title: {document.title}")
print(f"URI: {document.uri}")
print(f"Data Source: {document.data_source}")
print(f"Content Length: {document.content_length_bytes} bytes")
print(f"Content Preview: {document.content[:150]}...\n")
return document
Node.js и TypeScript
const {DeveloperKnowledgeClient} = require('@google/developer-knowledge');
/**
* Retrieves a single developer documentation page by its resource name.
*
* @param {string} name The resource name in format 'documents/{uri_without_scheme}'.
*/
async function getDocument(
name = 'documents/docs.cloud.google.com/storage/docs/creating-buckets'
) {
const client = new DeveloperKnowledgeClient();
const request = {
name,
};
const [document] = await client.getDocument(request);
console.log(`Title: ${document.title}`);
console.log(`URI: ${document.uri}`);
console.log(`Data Source: ${document.dataSource}`);
console.log(`Content Length: ${document.contentLengthBytes} bytes`);
console.log(`Content Preview: ${document.content.substring(0, 150)}...\n`);
return document;
}
Проложить маршрут
import (
"context"
"fmt"
"io"
developerknowledge "cloud.google.com/go/developerknowledge/apiv1"
developerknowledgepb "cloud.google.com/go/developerknowledge/apiv1/developerknowledgepb"
)
// getDocument retrieves a single developer documentation page by its resource name.
func getDocument(w io.Writer, name string) (*developerknowledgepb.Document, error) {
ctx := context.Background()
client, err := developerknowledge.NewDeveloperKnowledgeClient(ctx)
if err != nil {
return nil, fmt.Errorf("developerknowledge.NewDeveloperKnowledgeClient: %w", err)
}
defer client.Close()
req := &developerknowledgepb.GetDocumentRequest{
Name: name,
}
doc, err := client.GetDocument(ctx, req)
if err != nil {
return nil, fmt.Errorf("GetDocument: %w", err)
}
fmt.Fprintf(w, "Title: %s\n", doc.GetTitle())
fmt.Fprintf(w, "URI: %s\n", doc.GetUri())
fmt.Fprintf(w, "Data Source: %s\n", doc.GetDataSource())
fmt.Fprintf(w, "Content Length: %d bytes\n\n", doc.GetContentLengthBytes())
return doc, nil
}
Java
import com.google.developers.knowledge.v1.DeveloperKnowledgeClient;
import com.google.developers.knowledge.v1.Document;
import com.google.developers.knowledge.v1.GetDocumentRequest;
import java.io.IOException;
public class GetDocument {
public static void main(String[] args) throws IOException {
// TODO(developer): Replace these variables before running the sample.
String name = "documents/docs.cloud.google.com/storage/docs/creating-buckets";
getDocument(name);
}
// Retrieves a single developer documentation page by its resource name.
public static Document getDocument(String name) throws IOException {
// Initialize client that will be used to send requests. This client only needs to be created
// once, and can be reused for multiple requests. After completing all of your requests, call
// the "close" method on the client to safely clean up any remaining background resources.
try (DeveloperKnowledgeClient client = DeveloperKnowledgeClient.create()) {
GetDocumentRequest request = GetDocumentRequest.newBuilder().setName(name).build();
Document document = client.getDocument(request);
System.out.println("Title: " + document.getTitle());
System.out.println("URI: " + document.getUri());
System.out.println("Data Source: " + document.getDataSource());
System.out.println("Content Length: " + document.getContentLengthBytes() + " bytes");
String preview = document.getContent();
if (preview.length() > 150) {
preview = preview.substring(0, 150) + "...";
}
System.out.println("Content Preview: " + preview + "\n");
return document;
}
}
}
Как получить несколько документов
Используйте BatchGetDocuments, чтобы получить до 20 документов по названию ресурса за один вызов API.
Выберите вкладку с языком, чтобы посмотреть пример того, как позвонить на номер BatchGetDocuments:
Python
from typing import List, Optional
from google.cloud import developer_knowledge_v1
def batch_get_documents(
names: Optional[List[str]] = None,
) -> developer_knowledge_v1.BatchGetDocumentsResponse:
"""Retrieves multiple developer documentation pages in a single request.
Args:
names: A list of resource names in format 'documents/{uri_without_scheme}'.
Returns:
The BatchGetDocumentsResponse containing the retrieved documents.
"""
if names is None:
names = [
"documents/docs.cloud.google.com/storage/docs/creating-buckets",
"documents/docs.cloud.google.com/storage/docs/deleting-buckets",
]
client = developer_knowledge_v1.DeveloperKnowledgeClient()
request = developer_knowledge_v1.BatchGetDocumentsRequest(
names=names,
)
response = client.batch_get_documents(request=request)
for doc in response.documents:
print(f"Title: {doc.title}")
print(f"URI: {doc.uri}")
print(f"Content Length: {doc.content_length_bytes} bytes\n")
return response
Node.js и TypeScript
const {DeveloperKnowledgeClient} = require('@google/developer-knowledge');
/**
* Retrieves multiple developer documentation pages in a single request.
*
* @param {string[]} names Array of resource names in format 'documents/{uri_without_scheme}'.
*/
async function batchGetDocuments(
names = [
'documents/docs.cloud.google.com/storage/docs/creating-buckets',
'documents/docs.cloud.google.com/storage/docs/deleting-buckets',
]
) {
const client = new DeveloperKnowledgeClient();
const request = {
names,
};
const [response] = await client.batchGetDocuments(request);
if (response.documents) {
for (const doc of response.documents) {
console.log(`Title: ${doc.title}`);
console.log(`URI: ${doc.uri}`);
console.log(`Content Length: ${doc.contentLengthBytes} bytes\n`);
}
}
return response;
}
Проложить маршрут
import (
"context"
"fmt"
"io"
developerknowledge "cloud.google.com/go/developerknowledge/apiv1"
developerknowledgepb "cloud.google.com/go/developerknowledge/apiv1/developerknowledgepb"
)
// batchGetDocuments retrieves multiple developer documentation pages in a single request.
func batchGetDocuments(w io.Writer, names []string) (*developerknowledgepb.BatchGetDocumentsResponse, error) {
ctx := context.Background()
client, err := developerknowledge.NewDeveloperKnowledgeClient(ctx)
if err != nil {
return nil, fmt.Errorf("developerknowledge.NewDeveloperKnowledgeClient: %w", err)
}
defer client.Close()
req := &developerknowledgepb.BatchGetDocumentsRequest{
Names: names,
}
resp, err := client.BatchGetDocuments(ctx, req)
if err != nil {
return nil, fmt.Errorf("BatchGetDocuments: %w", err)
}
for _, doc := range resp.GetDocuments() {
fmt.Fprintf(w, "Title: %s\n", doc.GetTitle())
fmt.Fprintf(w, "\tURI: %s\n", doc.GetUri())
fmt.Fprintf(w, "\tContent Length: %d bytes\n\n", doc.GetContentLengthBytes())
}
return resp, nil
}
Java
import com.google.developers.knowledge.v1.BatchGetDocumentsRequest;
import com.google.developers.knowledge.v1.BatchGetDocumentsResponse;
import com.google.developers.knowledge.v1.DeveloperKnowledgeClient;
import com.google.developers.knowledge.v1.Document;
import java.io.IOException;
import java.util.Arrays;
import java.util.List;
public class BatchGetDocuments {
public static void main(String[] args) throws IOException {
// TODO(developer): Replace these variables before running the sample.
List<String> names =
Arrays.asList(
"documents/docs.cloud.google.com/storage/docs/creating-buckets",
"documents/docs.cloud.google.com/storage/docs/deleting-buckets");
batchGetDocuments(names);
}
// Retrieves multiple developer documentation pages in a single request.
public static BatchGetDocumentsResponse batchGetDocuments(List<String> names) throws IOException {
// Initialize client that will be used to send requests. This client only needs to be created
// once, and can be reused for multiple requests. After completing all of your requests, call
// the "close" method on the client to safely clean up any remaining background resources.
try (DeveloperKnowledgeClient client = DeveloperKnowledgeClient.create()) {
BatchGetDocumentsRequest request =
BatchGetDocumentsRequest.newBuilder().addAllNames(names).build();
BatchGetDocumentsResponse response = client.batchGetDocuments(request);
for (Document doc : response.getDocumentsList()) {
System.out.println("Title: " + doc.getTitle());
System.out.println("URI: " + doc.getUri());
System.out.println("Content Length: " + doc.getContentLengthBytes() + " bytes\n");
}
return response;
}
}
}
Дальнейшие действия
- Полный список включенной документации можно найти в справочнике по корпусу.
- Подробную информацию о методах и параметрах API можно найти в справочной документации по API.
- Подробнее о том, как настроить сервер MCP в Google Antigravity…