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 programowo wyszukiwać i pobierać publiczną dokumentację dla deweloperów Google za pomocą interfejsu Developer Knowledge API. Zamiast ręcznie analizować strony internetowe, 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.
Stronicowanie wyników wyszukiwania.
Stosowanie złożonych filtrów do wyszukiwania.
Pobieranie pełnej treści dokumentu.
Optymalizowanie ładunków odpowiedzi w celu zmniejszenia opóźnień.

Zanim zaczniesz, skonfiguruj środowisko dla preferowanego 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 Developer Knowledge API.

Przeszukiwanie dokumentów

Aby znaleźć fragmenty dokumentów pasujące do ciągu zapytania, użyj gcloud developer-knowledge documents search-chunks polecenia lub documents.searchDocumentChunks metody REST. Wyniki zawierają fragmenty treści z pasujących dokumentów oraz odniesienie parent, którego możesz użyć do pobrania pełnej treści tych dokumentów.

Ten 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: pasujący fragment tekstu z dokumentu.
document: metadane dokumentu źródłowego, takie jak title, uri, dataSource i updateTime.
relevanceScore: wynik trafności fragmentu w stosunku do zapytania 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 wyników, 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 tej 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 gcloud CLI użyj --limit, aby określić łączną liczbę wyników zwracanych na stronach. W żądaniach REST przekaż wartość pageToken otrzymaną w poprzedniej odpowiedzi, aby pobrać następną stronę wyników.

gcloud

Przekaż flagi --page-size i --limit, aby określić 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ę, przekaż parametr pageSize w żądaniu:

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 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ść 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, nextPageToken zostanie pominięty w odpowiedzi.

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 każdego fragmentu.

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

Obsługiwane pola

Wyniki wyszukiwania możesz filtrować za pomocą 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 (ciąg znaków): 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 celu dokładnego dopasowania ciągu znaków. Dopasowania częściowe, prefiksowe i wyrażeń regularnych nie są obsługiwane.
Pola sygnatury czasowej (update_time): obsługują operatory =, <, <=, >, i >=.
Pola liczbowe (content_length_bytes): obsługują operatory =, !=, <, <=, >, i >=.
Operatory logiczne: łącz warunki za pomocą operatorów AND, OR, i NOT (lub -).

Przykłady filtrów

Z przykładów poniżej dowiesz się, jak tworzyć wyrażenia filtra. Gdy używasz gcloud CLI, przekaż wyrażenie do flagi --query-filter. Gdy wywołujesz interfejs REST API za pomocą curl, pamiętaj, aby zakodować parametr filter w formacie URL 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

Aby uwzględnić dokumenty z wielu źródeł, użyj operatora OR:

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

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

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

Aby znaleźć dokumenty na podstawie ich rozmiaru w bajtach, użyj operatorów porównania z parametrem content_length_bytes:

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 operatory 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

Aby wykluczyć wyniki z określonego źródła, użyj operatora NOT lub !=:

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 gcloud developer-knowledge documents describe polecenia lub metody REST documents.get, aby ją pobrać.

Ten przykład pobiera dokument według 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 Document zasób zawierający metadane i pełną treść w formacie Markdown w polu content.

Nazwy zasobów a identyfikatory URI

Odwołując się do dokumentów w Developer Knowledge API, zwróć uwagę na różnicę między nazwami zasobów a identyfikatorami URI:

Nazwa zasobu (parent, name): formatowana 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 w BatchGetDocuments.
Identyfikator URI (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 --query-filter lub filter wyrażeń (np. uri = "https://docs.cloud.google.com/storage/docs/creating-buckets").

Pobieranie wielu dokumentów za pomocą `BatchGetDocuments`

Aby pobrać maksymalnie 20 dokumentów według nazwy w jednym wywołaniu interfejsu API, użyj metody documents.batchGet. Jest to bardziej wydajne niż wysyłanie wielu żądań GetDocument.

Ten przykład pobiera 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 Document zasobów w kolejności, w jakiej zostały one zażądane.

Optymalizowanie ładunków odpowiedzi

Treść dokumentu w formacie Markdown może być duża. Jeśli Twoja aplikacja potrzebuje tylko metadanych (takich jak tytuły stron, identyfikatory URI lub sygnatury czasowe) albo określonych pól, możesz zoptymalizować rozmiary ładunków, aby zmniejszyć zużycie przepustowości 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 Document wiadomościach.

Flaga --view i DocumentView typ wyliczeniowy 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 content w formacie Markdown. Jest to wartość domyślna w przypadku 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żej 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 z 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"

Korzystanie z masek pól

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

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"

Filtrowanie pól w `BatchGetDocuments`

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

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"

Filtrowanie pól w `SearchDocumentChunks`

Aby zwrócić tylko id i content fragmentu, title i uri dokumentu nadrzędnego 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ługa błędów

Developer Knowledge API zwraca standardowe kody stanu HTTP. Poniższe przykłady funkcjonalne przedstawiają kody stanu HTTP i ich przyczyny w 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 żądaniu BatchGetDocuments podano więcej niż 20 nazw dokumentów.
401 UNAUTHENTICATED: w żądaniu brakuje klucza interfejsu API lub tokena Bearer albo użyto nieprawidłowych danych logowania. Zapoznaj się z artykułem 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. Zapoznaj się z artykułem 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-knowledge umiejętność agenta, aby pomóc asystentowi wspomagania kodowania AI w wyszukiwaniu i odczytywaniu oficjalnej dokumentacji.
Dowiedz się, jak używać bibliotek klienta w językach Python, Node.js, Go lub Java.
Dowiedz się, jak używać gcloud CLI.
Przejrzyj dokumentację korpusu, aby zobaczyć wszystkie obsługiwane źródła dokumentacji.
Zapoznaj się z dokumentacją interfejsu REST API, aby poznać pełne specyfikacje metod.
Sprawdź limity i ograniczenia dotyczące limitów i limitów 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

Przeszukiwanie 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ą BatchGetDocuments

Optymalizowanie ładunków odpowiedzi

Korzystanie z widoków dokumentów

gcloud

REST

Korzystanie z masek pól

Filtrowanie pól w GetDocument

Filtrowanie pól w BatchGetDocuments

Filtrowanie pól w SearchDocumentChunks

Obsługa błędów

Co dalej?

Wyszukiwanie i pobieranie dokumentów

Pobieranie wielu dokumentów za pomocą `BatchGetDocuments`

Filtrowanie pól w `GetDocument`

Filtrowanie pól w `BatchGetDocuments`

Filtrowanie pól w `SearchDocumentChunks`