Wyszukiwanie i pobieranie dokumentów

Z tego przewodnika dowiesz się, jak programowo wyszukiwać i pobierać publiczną dokumentację dla deweloperów Google za pomocą interfejsu Developer Knowledge API. Zamiast ręcznie przeszukiwać 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óźnienia.

Zanim zaczniesz, upewnij się, że masz włączony interfejs API i wygenerowany klucz Developer Knowledge API. Następnie zapisz klucz w zmiennej środowiskowej:

export DEVELOPERKNOWLEDGE_API_KEY="YOUR_API_KEY"

Wyszukiwanie dokumentów za pomocą SearchDocumentChunks

Użyj metody documents.searchDocumentChunks , aby znaleźć fragmenty dokumentów pasujące do ciągu zapytania. Wyniki zawierają fragmenty treści z pasujących dokumentów oraz odwołanie 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”:

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:

  • pageSize (liczba całkowita): określa maksymalną liczbę wyników zwracanych na stronie. Jeśli nie zostanie określony, interfejs API domyślnie zwraca 5 wyników. Maksymalna dozwolona wartość to 100. Wartości większe niż 100 są zaokrąglane do 100.
  • pageToken (ciąg znaków): określa token otrzymany w poprzedniej odpowiedzi, aby pobrać następną stronę wyników.

Wysyłanie prośby o pierwszą stronę

Aby ustawić rozmiar strony, 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"
}

Pobieranie kolejnych stron

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

Użyj parametru filter, aby zastosować ścisły filtr do wyników wyszukiwania. Wyrażenie filtra jest stosowane do metadanych dokumentu nadrzędnego każdego fragmentu.

Wyrażenie filter 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ć w formacie 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ę) do 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 liczb całkowitych (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 wywołujesz interfejs REST API za pomocą curl, pamiętaj, aby zakodować parametr filtra w formacie URL lub użyć --data-urlencode.

Dopasowywanie wielu źródeł danych

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

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

Żądanie curl:

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"

Żądanie curl:

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żyj operatorów porównania z content_length_bytes, aby znaleźć dokumenty na podstawie ich rozmiaru w bajtach:

content_length_bytes < 5000

Żądanie curl:

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"

Żądanie curl:

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 operatora NOT lub !=, aby wykluczyć wyniki z określonego źródła:

data_source != "firebase.google.com"

Żądanie curl:

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 za pomocą GetDocument

Użyj documents.get metody, aby pobrać pełną treść pojedynczego dokumentu.

Nazwy zasobów a identyfikatory URI

Odwołując 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): formatowana jako documents/{uri_without_scheme} (np. documents/docs.cloud.google.com/storage/docs/creating-buckets). Przekaż tę wartość jako 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 wyrażeń filter (np. uri = "https://docs.cloud.google.com/storage/docs/creating-buckets").

Ten przykład pobiera dokument według jego nazwy zasobu:

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.

Pobieranie wielu dokumentów za pomocą BatchGetDocuments

Użyj metody documents.batchGet , aby pobrać maksymalnie 20 dokumentów według nazwy w jednym wywołaniu interfejsu API. 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 wysł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) albo określonych pól, możesz zoptymalizować rozmiary ładunków, aby zmniejszyć zużycie przepustowości i opóźnienie.

Korzystanie z widoków dokumentów

Parametr view określa, które pola są wypełniane w Document wiadomościach.

Wyliczenie DocumentView obsługuje te wartości:

  • DOCUMENT_VIEW_BASIC: zwraca tylko podstawowe pola metadanych (name, uri, data_source, title, description, update_time i view). Pole content jest pomijane.
  • DOCUMENT_VIEW_CONTENT: zwraca pola metadanych wraz z polem content w formacie Markdown. Jest to wartość domyślna w przypadku GetDocument i BatchGetDocuments.
  • DOCUMENT_VIEW_FULL: zwraca wszystkie pola dokumentu.

Aby pobrać tylko metadane dokumentu bez pobierania dużych treści w formacie Markdown, ustaw view=DOCUMENT_VIEW_BASIC:

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 dodatkowo ograniczyć ładunki odpowiedzi do określonych pól, użyj standardowego Google APIs fields parametru zapytania (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"

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"

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ługiwanie błędów

Interfejs Developer Knowledge API zwraca standardowe kody stanu HTTP. Poniższe przykłady funkcjonalne mapują 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ć w formacie RFC 3339).
    • W żądaniu BatchGetDocuments podano więcej niż 20 nazw dokumentów.
  • 401 UNAUTHENTICATED: w żądaniu brakuje klucza API lub użyto nieprawidłowego klucza. Więcej informacji znajdziesz w artykule 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. Więcej informacji znajdziesz w artykule Limity.

Co dalej?