Google używa technologii AI do tłumaczenia treści na Twój preferowany język. Tłumaczenia wygenerowane przez AI mogą zawierać błędy.

Wyszukiwanie i pobieranie dokumentów

Z tego dokumentu dowiesz się, jak korzystać z interfejsu Developer Knowledge API do programowego wyszukiwania i pobierania publicznej dokumentacji dla deweloperów Google. Zamiast ręcznie pobierać dane ze stron internetowych, interfejs API pomaga aplikacjom znajdować odpowiednie fragmenty tekstu lub pobierać pełne dokumenty w formacie Markdown.

W tym dokumencie znajdziesz przykłady tych zadań:

Przeszukiwanie korpusu dokumentacji.
przeglądanie wyników wyszukiwania na kolejnych stronach;
stosowanie złożonych filtrów do wyszukiwania;
Pobieranie pełnej zawartości dokumentu.
Optymalizacja ładunków odpowiedzi w celu zmniejszenia opóźnień.

Zanim zaczniesz, skonfiguruj środowisko pod kątem wybranego narzędzia:

gcloud

Zainstaluj i skonfiguruj gcloud CLI oraz włącz Developer Knowledge API.

REST

Włącz interfejs API i wygeneruj klucz Developer Knowledge API. Następnie zapisz klucz w zmiennej środowiskowej:

export DEVELOPERKNOWLEDGE_API_KEY="YOUR_API_KEY"

Zastąp YOUR_API_KEY kluczem interfejsu Developer Knowledge API.

Wyszukiwanie dokumentów

Użyj gcloud developer-knowledge documents search-chunkspolecenia lub metody documents.searchDocumentChunks REST, aby znaleźć fragmenty dokumentu pasujące do ciągu zapytania. Wyniki zawierają fragmenty treści z pasujących dokumentów wraz z parent odwołaniem, którego możesz użyć do pobrania pełnej treści tych dokumentów.

Poniższy przykład wyszukuje dokumenty pasujące do zapytania „BigQuery”:

gcloud

gcloud developer-knowledge documents search-chunks \
  --query="BigQuery"

REST

curl "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks?query=BigQuery&key=$DEVELOPERKNOWLEDGE_API_KEY"

Dane wyjściowe są podobne do tych:

{
  "results": [
    {
      "parent": "documents/docs.cloud.google.com/bigquery/docs/introduction",
      "id": "chunk_0",
      "content": "BigQuery is a fully managed enterprise data warehouse...",
      "document": {
        "name": "documents/docs.cloud.google.com/bigquery/docs/introduction",
        "uri": "https://docs.cloud.google.com/bigquery/docs/introduction",
        "title": "BigQuery overview",
        "dataSource": "docs.cloud.google.com",
        "updateTime": "2025-01-15T12:00:00Z"
      },
      "relevanceScore": 0.92
    }
  ]
}

Każdy wynik na liście results zawiera:

parent: nazwa zasobu dokumentu (np. documents/docs.cloud.google.com/bigquery/docs/introduction).
id: identyfikator fragmentu w dokumencie (np. chunk_0).
content: dopasowany fragment tekstu z dokumentu;
document: metadane dokumentu źródłowego, takie jak title, uri, dataSource i updateTime.
relevanceScore: wynik trafności fragmentu w odniesieniu do zapytania wyszukiwania w zakresie [0.0, 1.0].

Więcej informacji o schemacie odpowiedzi i wszystkich dostępnych polach metadanych znajdziesz w dokumentacji interfejsu documents.searchDocumentChunks API.

Stronicowanie wyników wyszukiwania

Gdy zapytanie zwraca wiele dopasowań, możesz poruszać się po zbiorze wyników za pomocą parametrów stronicowania:

--page-size (gcloud CLI) lub pageSize (liczba całkowita): określa maksymalną liczbę wyników do zwrócenia na stronie. Jeśli nie podasz żadnej wartości, interfejs API domyślnie zwróci 5 wyników. Maksymalna dozwolona wartość to 100. Wartości większe niż 100 są zaokrąglane do 100.
--limit (gcloud CLI) lub pageToken (ciąg znaków): w interfejsie wiersza poleceń gcloud użyj --limit, aby kontrolować łączną liczbę wyników zwracanych na stronach. W przypadku żądań REST przekaż wartość pageToken otrzymaną w poprzedniej odpowiedzi, aby pobrać następną stronę wyników.

gcloud

Przekaż flagi --page-size i --limit, aby kontrolować liczbę wyników na stronie i łączną liczbę zwracanych wyników:

gcloud developer-knowledge documents search-chunks \
  --query="BigQuery" \
  --page-size=5 \
  --limit=10

REST

Aby poprosić o pierwszą stronę, w żądaniu przekaż parametr pageSize:

curl "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks?query=BigQuery&pageSize=5&key=$DEVELOPERKNOWLEDGE_API_KEY"

Jeśli dostępne są dodatkowe wyniki, odpowiedź zawiera element nextPageToken:

{
  "results": [
    {
      "parent": "documents/docs.cloud.google.com/bigquery/docs/introduction",
      "id": "chunk_0",
      "content": "BigQuery is a fully managed enterprise data warehouse...",
      "document": {
        "name": "documents/docs.cloud.google.com/bigquery/docs/introduction",
        "uri": "https://docs.cloud.google.com/bigquery/docs/introduction",
        "title": "What is BigQuery?",
        "dataSource": "docs.cloud.google.com",
        "updateTime": "2025-01-15T12:00:00Z",
        "view": "DOCUMENT_VIEW_BASIC"
      },
      "relevanceScore": 0.88
    }
  ],
  "nextPageToken": "CAUQABgB"
}

Aby pobrać kolejne strony, przekaż wartość parametru nextPageToken do parametru pageToken w następnym żądaniu:
```
curl "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks?query=BigQuery&pageSize=5&pageToken=CAUQABgB&key=$DEVELOPERKNOWLEDGE_API_KEY"
```
Gdy dotrzesz do ostatniej strony wyników, w odpowiedzi nie będzie już znaku nextPageToken.

Filtrowanie wyników wyszukiwania

Aby zastosować ścisły filtr do wyników wyszukiwania, użyj flagi --query-filter w gcloud CLI lub parametru filter w żądaniach REST. Wyrażenie filtra jest stosowane do metadanych dokumentu nadrzędnego w przypadku każdego fragmentu.

Wyrażenie filtra może mieć maksymalnie 500 znaków.

Obsługiwane pola

Wyniki wyszukiwania możesz filtrować, korzystając z tych pól dokumentu nadrzędnego:

content_length_bytes (liczba całkowita): długość pola content dokumentu w bajtach.
data_source (ciąg znaków): domena źródłowa dokumentu, np. docs.cloud.google.com lub firebase.google.com. Wszystkie obsługiwane źródła danych znajdziesz w dokumentacji korpusu.
update_time (sygnatura czasowa): sygnatura czasowa ostatniej aktualizacji dokumentu. Wartości muszą być zgodne z formatem RFC 3339 (np."2025-01-01T00:00:00Z").
uri (string): pełny identyfikator URI dokumentu (np. https://docs.cloud.google.com/bigquery/docs/tables).

Obsługiwane operatory

Parser wyrażeń filtra obsługuje różne operatory w zależności od typu danych pola:

Pola tekstowe (data_source, uri): obsługują operatory = (równa się) i != (nie równa się) w przypadku dokładnego dopasowania ciągu znaków. Nie są obsługiwane dopasowania częściowe, dopasowania prefiksów ani dopasowania wyrażeń regularnych.
Pola sygnatury czasowej (update_time): obsługują =, <, <=, > i >=.
Pola liczb całkowitych (content_length_bytes): obsługują =, !=, <, <=, > i >=.
Operatory logiczne: łącz warunki za pomocą operatorów AND, OR i NOT (lub -).

Przykłady filtrów

Poniższe przykłady pokazują, jak tworzyć wyrażenia filtra. Jeśli używasz gcloud CLI, przekaż wyrażenie do flagi --query-filter. Podczas wywoływania interfejsu API REST za pomocą curl pamiętaj, aby zakodować w adresie URL parametr filter lub użyć --data-urlencode.

Dopasowywanie pojedynczego źródła danych

Ogranicz wyniki wyszukiwania do jednej domeny dokumentacji:

data_source = "docs.cloud.google.com"

gcloud

gcloud developer-knowledge documents search-chunks \
  --query="Cloud Functions deployment" \
  --query-filter='data_source = "docs.cloud.google.com"'

REST

curl -G "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks" \
  --data-urlencode "query=Cloud Functions deployment" \
  --data-urlencode 'filter=data_source = "docs.cloud.google.com"' \
  --data-urlencode "key=$DEVELOPERKNOWLEDGE_API_KEY"

Dopasowywanie wielu źródeł danych

Użyj ikony OR, aby uwzględnić dokumenty z wielu źródeł:

data_source = "docs.cloud.google.com" OR data_source = "firebase.google.com"

gcloud

gcloud developer-knowledge documents search-chunks \
  --query="database" \
  --query-filter='data_source = "docs.cloud.google.com" OR data_source = "firebase.google.com"'

REST

curl -G "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks" \
  --data-urlencode "query=database" \
  --data-urlencode 'filter=data_source = "docs.cloud.google.com" OR data_source = "firebase.google.com"' \
  --data-urlencode "key=$DEVELOPERKNOWLEDGE_API_KEY"

Filtrowanie według sygnatury czasowej

Użyj operatorów porównania z sygnaturami czasowymi RFC 3339, aby znaleźć treści zaktualizowane po określonej dacie:

update_time >= "2025-01-01T00:00:00Z"

gcloud

gcloud developer-knowledge documents search-chunks \
  --query="BigQuery" \
  --query-filter='update_time >= "2025-01-01T00:00:00Z"'

REST

curl -G "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks" \
  --data-urlencode "query=BigQuery" \
  --data-urlencode 'filter=update_time >= "2025-01-01T00:00:00Z"' \
  --data-urlencode "key=$DEVELOPERKNOWLEDGE_API_KEY"

Filtrowanie według długości treści

Używaj operatorów porównania z operatorem content_length_bytes, aby wyszukiwać dokumenty na podstawie ich rozmiaru w bajtach:

content_length_bytes < 5000

gcloud

gcloud developer-knowledge documents search-chunks \
  --query="Cloud Storage" \
  --query-filter='content_length_bytes < 5000'

REST

curl -G "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks" \
  --data-urlencode "query=Cloud Storage" \
  --data-urlencode 'filter=content_length_bytes < 5000' \
  --data-urlencode "key=$DEVELOPERKNOWLEDGE_API_KEY"

Łączenie źródła danych, sygnatury czasowej i grupowania

Połącz symbole AND, OR i nawiasy (...), aby ograniczyć wyniki do określonych źródeł zaktualizowanych po danej dacie:

(data_source = "developer.chrome.com" OR data_source = "web.dev") AND update_time >= "2025-01-01T00:00:00Z"

gcloud

gcloud developer-knowledge documents search-chunks \
  --query="service worker" \
  --query-filter='(data_source = "developer.chrome.com" OR data_source = "web.dev") AND update_time >= "2025-01-01T00:00:00Z"'

REST

curl -G "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks" \
  --data-urlencode "query=service worker" \
  --data-urlencode 'filter=(data_source = "developer.chrome.com" OR data_source = "web.dev") AND update_time >= "2025-01-01T00:00:00Z"' \
  --data-urlencode "key=$DEVELOPERKNOWLEDGE_API_KEY"

Wykluczanie źródeł danych

Użyj symbolu NOT lub !=, aby wykluczyć wyniki z określonego źródła:

data_source != "firebase.google.com"

gcloud

gcloud developer-knowledge documents search-chunks \
  --query="authentication" \
  --query-filter='data_source != "firebase.google.com"'

REST

curl -G "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks" \
  --data-urlencode "query=authentication" \
  --data-urlencode 'filter=data_source != "firebase.google.com"' \
  --data-urlencode "key=$DEVELOPERKNOWLEDGE_API_KEY"

Pobieranie dokumentu

Aby pobrać pełną treść pojedynczego dokumentu, użyj polecenia gcloud developer-knowledge documents describe lub metody REST documents.get.

W tym przykładzie dokument jest pobierany na podstawie jego nazwy zasobu:

gcloud

gcloud developer-knowledge documents describe \
  documents/docs.cloud.google.com/storage/docs/creating-buckets

REST

curl "https://developerknowledge.googleapis.com/v1/documents/docs.cloud.google.com/storage/docs/creating-buckets?key=$DEVELOPERKNOWLEDGE_API_KEY"

Odpowiedź to zasób Document zawierający metadane i pełną treść w formacie Markdown w polu content.

Nazwy zasobów a identyfikatory URI

Podczas odwoływania się do dokumentów w interfejsie Developer Knowledge API zwróć uwagę na różnicę między nazwami zasobów a identyfikatorami URI:

Nazwa zasobu (parent, name): sformatowana jako documents/{uri_without_scheme} (np. documents/docs.cloud.google.com/storage/docs/creating-buckets). Przekaż tę wartość jako argument pozycyjny w gcloud developer-knowledge documents describe, parametr ścieżki w GetDocument lub w parametrze names funkcji BatchGetDocuments.
Identyfikator URI sieci (uri): pełny adres URL, w tym schemat (np. https://docs.cloud.google.com/storage/docs/creating-buckets). Użyj tego formatu w polu uri podczas tworzenia wyrażeń --query-filter lub filter (np. uri = "https://docs.cloud.google.com/storage/docs/creating-buckets").

Pobieranie wielu dokumentów za pomocą funkcji `BatchGetDocuments`

Użyj metody documents.batchGet, aby pobrać maksymalnie 20 dokumentów według nazwy w ramach jednego wywołania interfejsu API. Jest to bardziej wydajne niż wysyłanie wielu żądań GetDocument.

W tym przykładzie pobierane są 2 dokumenty według nazwy:

curl "https://developerknowledge.googleapis.com/v1/documents:batchGet?names=documents/docs.cloud.google.com/storage/docs/creating-buckets&names=documents/firebase.google.com/docs/firestore/quickstart&key=$DEVELOPERKNOWLEDGE_API_KEY"

Odpowiedź zawiera listę żądanych zasobów Document w kolejności, w jakiej zostały one przesłane.

Optymalizowanie ładunków odpowiedzi

Treść dokumentu w formacie Markdown może być duża. Jeśli aplikacja potrzebuje tylko metadanych (takich jak tytuły stron, identyfikatory URI lub sygnatury czasowe) lub określonych pól, możesz zoptymalizować rozmiary ładunku, aby zmniejszyć przepustowość i opóźnienia.

Korzystanie z widoków dokumentów

Flaga --view w gcloud CLI lub parametr view w żądaniach REST określa, które pola są wypełniane w komunikatach Document.

Flaga --view i typ wyliczeniowy DocumentView obsługują te wartości:

--view=basic (gcloud CLI) lub DOCUMENT_VIEW_BASIC: zwraca tylko podstawowe pola metadanych (name, uri, dataSource, title, description, updateTime i view). Pole content jest pomijane.
--view=content (gcloud CLI) lub DOCUMENT_VIEW_CONTENT: zwraca pola metadanych wraz z polem Markdown content. Jest to ustawienie domyślne w przypadku usług gcloud developer-knowledge documents describe, GetDocument i BatchGetDocuments.
--view=full (gcloud CLI) lub DOCUMENT_VIEW_FULL: zwraca wszystkie pola dokumentu.

Aby pobrać tylko metadane dokumentu bez pobierania dużych treści w formacie Markdown, określ podstawowy widok dokumentu:

gcloud

gcloud developer-knowledge documents describe \
  documents/docs.cloud.google.com/storage/docs/creating-buckets \
  --view=basic

REST

curl "https://developerknowledge.googleapis.com/v1/documents/docs.cloud.google.com/storage/docs/creating-buckets?view=DOCUMENT_VIEW_BASIC&key=$DEVELOPERKNOWLEDGE_API_KEY"

Możesz też użyć view=DOCUMENT_VIEW_BASIC w sklepie BatchGetDocuments:

curl "https://developerknowledge.googleapis.com/v1/documents:batchGet?names=documents/docs.cloud.google.com/storage/docs/creating-buckets&names=documents/firebase.google.com/docs/firestore/quickstart&view=DOCUMENT_VIEW_BASIC&key=$DEVELOPERKNOWLEDGE_API_KEY"

Używanie masek pól

Aby jeszcze bardziej ograniczyć rozmiar odpowiedzi do określonych pól, użyj standardowego parametru zapytania fields interfejsów API Google (maska pola).

Filtrowanie pól w `GetDocument`

Aby pobrać tylko pola title, uri i updateTime dokumentu:

curl "https://developerknowledge.googleapis.com/v1/documents/docs.cloud.google.com/storage/docs/creating-buckets?fields=title,uri,updateTime&key=$DEVELOPERKNOWLEDGE_API_KEY"

Filtruj pola w `BatchGetDocuments`

Aby pobrać tylko określone pola każdego dokumentu w partii:

curl "https://developerknowledge.googleapis.com/v1/documents:batchGet?names=documents/docs.cloud.google.com/storage/docs/creating-buckets&fields=documents(name,title,uri)&key=$DEVELOPERKNOWLEDGE_API_KEY"

Filtruj pola w `SearchDocumentChunks`

Aby zwrócić tylko fragmenty id i content, dokument nadrzędny title i uri oraz nextPageToken z wyszukiwania:

curl "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks?query=BigQuery&fields=results(id,content,document(title,uri)),nextPageToken&key=$DEVELOPERKNOWLEDGE_API_KEY"

Obsługuj błędy

Interfejs Developer Knowledge API zwraca standardowe kody stanu HTTP. Poniższe przykłady funkcjonalne pokazują kody stanu HTTP i ich przyczyny w interfejsie Developer Knowledge API:

400 INVALID_ARGUMENT:
- Ciąg znaków wyrażenia filter przekracza 500 znaków.
- Sygnatura czasowa update_time jest nieprawidłowa (musi być zgodna z formatem RFC 3339).
- W BatchGetDocuments prośbie podano ponad 20 nazw dokumentów.
401 UNAUTHENTICATED: w żądaniu brakuje klucza interfejsu API lub użyto nieprawidłowego klucza. Zobacz Uwierzytelnianie.
404 NOT_FOUND: żądana nazwa dokumentu nie istnieje lub należy do domeny, która nie jest uwzględniona w korpusie.
429 RESOURCE_EXHAUSTED: projekt przekroczył limit. Zobacz Limity.

Co dalej?

Zapoznaj się z artykułem Generowanie odpowiedzi na podstawie dokumentacji.
Połącz się z serwerem MCP Developer Knowledge i zainstaluj retrieving-developer-knowledgeumiejętność agenta, aby pomóc asystentowi wspomagania kodowania AI w wyszukiwaniu i czytaniu oficjalnej dokumentacji.
Dowiedz się, jak używać bibliotek klienta w językach Python, Node.js, Go i Java.
Dowiedz się, jak używać interfejsu wiersza poleceń gcloud.
Przejrzyj korpus referencyjny, aby wyświetlić wszystkie obsługiwane źródła dokumentacji.
Pełne specyfikacje metod znajdziesz w dokumentacji API (typu) REST.
Sprawdź limity dotyczące interfejsu API.

Wyszukiwanie i pobieranie dokumentów Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

gcloud

REST

Wyszukiwanie dokumentów

gcloud

REST

Stronicowanie wyników wyszukiwania

gcloud

REST

Filtrowanie wyników wyszukiwania

Obsługiwane pola

Obsługiwane operatory

Przykłady filtrów

Dopasowywanie pojedynczego źródła danych

gcloud

REST

Dopasowywanie wielu źródeł danych

gcloud

REST

Filtrowanie według sygnatury czasowej

gcloud

REST

Filtrowanie według długości treści

gcloud

REST

Łączenie źródła danych, sygnatury czasowej i grupowania

gcloud

REST

Wykluczanie źródeł danych

gcloud

REST

Pobieranie dokumentu

gcloud

REST

Nazwy zasobów a identyfikatory URI

Pobieranie wielu dokumentów za pomocą funkcji BatchGetDocuments

Optymalizowanie ładunków odpowiedzi

Korzystanie z widoków dokumentów

gcloud

REST

Używanie masek pól

Filtrowanie pól w GetDocument

Filtruj pola w BatchGetDocuments

Filtruj pola w SearchDocumentChunks

Obsługuj błędy

Co dalej?

Wyszukiwanie i pobieranie dokumentów

Pobieranie wielu dokumentów za pomocą funkcji `BatchGetDocuments`

Filtrowanie pól w `GetDocument`

Filtruj pola w `BatchGetDocuments`

Filtruj pola w `SearchDocumentChunks`