Dokumente suchen und abrufen

In diesem Dokument erfahren Sie, wie Sie mit der Developer Knowledge API programmatisch in der öffentlichen Entwicklerdokumentation von Google suchen und diese abrufen können. Anstatt Webseiten manuell zu scrapen, können Sie mit der API relevante Textausschnitte finden oder vollständige Markdown-Dokumente abrufen.

In diesem Dokument finden Sie Beispiele für die folgenden Aufgaben:

• Suche im Dokumentationskorpus.
• Durchblättern von Suchergebnissen.
• Sie haben komplexe Filter auf Ihre Suche angewendet.
• Abrufen des vollständigen Dokumentinhalts.
• Antwortnutzlasten optimieren, um die Latenz zu verringern.

Richten Sie zuerst Ihre Umgebung für das gewünschte Tool ein:

gcloud

gcloud CLI installieren und konfigurieren und die Developer Knowledge API aktivieren

REST

Aktivieren Sie die API und generieren Sie einen API-Schlüssel für die Developer Knowledge API. Speichern Sie den Schlüssel dann in einer Umgebungsvariablen:

export DEVELOPERKNOWLEDGE_API_KEY="YOUR_API_KEY"

Ersetzen Sie YOUR_API_KEY durch Ihren Developer Knowledge API-Schlüssel.

Tipp :Wenn Sie Antworten in natürlicher Sprache benötigen, die aus der Dokumentation generiert werden, anstatt rohe Auszüge, lesen Sie den Hilfeartikel Antworten aus der Dokumentation generieren.

Nach Dokumenten suchen

Verwenden Sie den gcloud developer-knowledge documents search-chunks-Befehl oder die documents.searchDocumentChunks-REST-Methode, um Dokument-Chunks zu finden, die mit einem Abfragestring übereinstimmen. Die Ergebnisse enthalten Inhaltsblöcke aus übereinstimmenden Dokumenten sowie eine parent-Referenz, mit der Sie den vollständigen Inhalt dieser Dokumente abrufen können.

Im folgenden Beispiel wird nach Dokumenten gesucht, die „BigQuery“ enthalten:

gcloud

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

REST

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

Die Ausgabe sieht etwa so aus:

{
  "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
    }
  ]
}

Jedes Ergebnis in der results-Liste enthält Folgendes:

• parent: Der Name der Dokumentressource (z. B. documents/docs.cloud.google.com/bigquery/docs/introduction).
• id: die Blockkennung innerhalb des Dokuments (z. B. chunk_0).
• content: Das übereinstimmende Text-Snippet aus dem Dokument.
• document: Metadaten zum Quelldokument, z. B. title, uri, dataSource und updateTime.
• relevanceScore: Der Relevanzwert des Chunks für die Suchanfrage im Bereich [0.0, 1.0].

Weitere Informationen zum Antwortschema und zu allen verfügbaren Metadatenfeldern finden Sie in der API-Referenz zu „documents.searchDocumentChunks“.

Suchergebnisse paginieren

Wenn eine Suchanfrage mehrere Treffer zurückgibt, können Sie mithilfe von Paginierungsparametern durch die Ergebnismenge navigieren:

• --page-size (gcloud CLI) oder pageSize (Ganzzahl): Gibt die maximale Anzahl der Ergebnisse an, die pro Seite zurückgegeben werden sollen. Wenn nichts angegeben ist, werden standardmäßig fünf Ergebnisse zurückgegeben. Der maximal zulässige Wert ist 100. Werte über 100 werden auf 100 gesetzt.

• --limit (gcloud CLI) oder pageToken (String): Verwenden Sie in der gcloud CLI --limit, um die Gesamtzahl der Ergebnisse zu steuern, die seitenübergreifend zurückgegeben werden. Übergeben Sie in REST-Anfragen den Wert pageToken, der in einer vorherigen Antwort empfangen wurde, um die nächste Ergebnisseite abzurufen.

gcloud

Mit den Flags --page-size und --limit können Sie die Anzahl der Ergebnisse pro Seite und die Gesamtzahl der zurückgegebenen Ergebnisse festlegen:

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

REST

1. Wenn Sie die erste Seite anfordern möchten, übergeben Sie den Parameter pageSize in Ihrer Anfrage:

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

   Wenn zusätzliche Ergebnisse verfügbar sind, enthält die Antwort ein 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"
   }
   

2. Wenn Sie nachfolgende Seiten abrufen möchten, übergeben Sie den Wert von nextPageToken in Ihrer nächsten Anfrage an den Parameter pageToken:

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

   Wenn Sie die letzte Ergebnisseite erreichen, wird nextPageToken aus der Antwort entfernt.

Suchergebnisse filtern

Verwenden Sie das Flag --query-filter in der gcloud CLI oder den Parameter filter in REST-Anfragen, um einen strengen Filter auf Suchergebnisse anzuwenden. Der Filterausdruck wird für jeden Chunk auf die Metadaten des übergeordneten Dokuments angewendet.

Der Filterausdruck darf maximal 500 Zeichen lang sein.

Unterstützte Felder

Sie können Ihre Suchergebnisse mit den folgenden Feldern des übergeordneten Dokuments filtern:

• content_length_bytes (Ganzzahl): Die Länge des Felds content des Dokuments in Byte.
• data_source (String): Die Quelldomain des Dokuments, z. B. docs.cloud.google.com oder firebase.google.com. Eine Liste aller unterstützten Datenquellen finden Sie in der Korpusreferenz.
• update_time (Zeitstempel): Der Zeitstempel, der angibt, wann das Dokument zuletzt aktualisiert wurde. Werte müssen im RFC 3339-Format angegeben werden (z. B. "2025-01-01T00:00:00Z").
• uri (String): Der vollständige URI des Dokuments (z. B. https://docs.cloud.google.com/bigquery/docs/tables).

Unterstützte Operatoren

Der Parser für Filterausdrücke unterstützt je nach Datentyp des Felds verschiedene Operatoren:

• Stringfelder (data_source, uri): unterstützen = (gleich) und != (ungleich) für den genauen Stringabgleich. Teil-, Präfix- und reguläre Ausdrucksübereinstimmungen werden nicht unterstützt.
• Zeitstempelfelder (update_time): Unterstützen =, <, <=, > und >=.
• Ganzzahlfelder (content_length_bytes): Unterstützen =, !=, <, <=, > und >=.
• Logische Operatoren: Kombinieren Sie Bedingungen mit AND, OR und NOT (oder -).

Community-Anmerkung :OR hat eine höhere Priorität als AND. Verwenden Sie Klammern (...) für die explizite Gruppierung, damit die Bedingungen in der gewünschten Reihenfolge ausgewertet werden.

Beispiele für Filter

Die folgenden Beispiele zeigen, wie Filterausdrücke erstellt werden. Wenn Sie die gcloud CLI verwenden, übergeben Sie den Ausdruck an das Flag --query-filter. Wenn Sie die REST API mit curl aufrufen, müssen Sie den Parameter filter URL-codieren oder --data-urlencode verwenden.

Eine einzelne Datenquelle abgleichen

Suchergebnisse auf eine einzelne Dokumentationsdomain beschränken:

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"

Mehrere Datenquellen abgleichen

Mit OR können Sie Dokumente aus mehreren Quellen einfügen:

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"

Nach Zeitstempel filtern

Verwenden Sie Vergleichsoperatoren mit RFC 3339-Zeitstempeln, um nach Inhalten zu suchen, die nach einem bestimmten Datum aktualisiert wurden:

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"

Nach Länge filtern

Mit Vergleichsoperatoren und content_length_bytes können Sie Dokumente anhand ihrer Bytegröße finden:

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"

Datenquelle, Zeitstempel und Gruppierung kombinieren

Kombinieren Sie AND, OR und Klammern (...), um die Ergebnisse auf bestimmte Quellen zu beschränken, die nach einem bestimmten Datum aktualisiert wurden:

(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"

Datenquellen ausschließen

Verwenden Sie NOT oder !=, um Ergebnisse aus einer bestimmten Quelle auszuschließen:

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"

Dokument abrufen

Verwenden Sie den Befehl gcloud developer-knowledge documents describe oder die REST-Methode documents.get, um den vollständigen Inhalt eines einzelnen Dokuments abzurufen.

Im folgenden Beispiel wird ein Dokument anhand seines Ressourcennamens abgerufen:

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"

Die Antwort ist eine Document-Ressource, die Metadaten und den vollständigen Markdown-Inhalt im Feld content enthält.

Ressourcennamen im Vergleich zu URIs

Wenn Sie in der Developer Knowledge API auf Dokumente verweisen, beachten Sie den Unterschied zwischen Ressourcennamen und Web-URIs:

• Ressourcenname (parent, name): formatiert als documents/{uri_without_scheme} (z. B. documents/docs.cloud.google.com/storage/docs/creating-buckets). Übergeben Sie diesen Wert als Positionsargument in gcloud developer-knowledge documents describe, als Pfad-Parameter in GetDocument oder im Parameter names von BatchGetDocuments.
• Web-URI (uri): Vollständige Web-URL einschließlich des Schemas (z. B. https://docs.cloud.google.com/storage/docs/creating-buckets). Verwenden Sie dieses Format für das Feld uri, wenn Sie --query-filter- oder filter-Ausdrücke erstellen (z. B. uri = "https://docs.cloud.google.com/storage/docs/creating-buckets").

Mehrere Dokumente mit BatchGetDocuments abrufen

Verwenden Sie die Methode documents.batchGet, um bis zu 20 Dokumente in einem einzigen API-Aufruf anhand des Namens abzurufen. Das ist effizienter, als mehrere GetDocument-Anfragen zu senden.

Im folgenden Beispiel werden zwei Dokumente nach Namen abgerufen:

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"

Die Antwort enthält eine Liste der angeforderten Document-Ressourcen in der von Ihnen angeforderten Reihenfolge.

Antwortnutzlasten optimieren

Dokumentinhalte im Markdown-Format können sehr umfangreich sein. Wenn Ihre Anwendung nur Metadaten (z. B. Seitentitel, URIs oder Zeitstempel) oder bestimmte Felder benötigt, können Sie die Nutzlastgrößen optimieren, um Bandbreite und Latenz zu reduzieren.

Dokumentansichten verwenden

Das Flag --view in der gcloud CLI oder der Parameter view in REST-Anfragen steuert, welche Felder in Document-Nachrichten ausgefüllt werden.

Das Flag --view und das Enum DocumentView unterstützen die folgenden Werte:

• --view=basic (gcloud CLI) oder DOCUMENT_VIEW_BASIC: Gibt nur grundlegende Metadatenfelder zurück (name, uri, dataSource, title, description, updateTime und view). Das Feld content wird ausgelassen.
• --view=content (gcloud CLI) oder DOCUMENT_VIEW_CONTENT: Gibt Metadatenfelder zusammen mit dem Markdown-Feld content zurück. Dies ist die Standardeinstellung für gcloud developer-knowledge documents describe, GetDocument und BatchGetDocuments.
• --view=full (gcloud CLI) oder DOCUMENT_VIEW_FULL: Gibt alle Dokumentfelder zurück.

Wenn Sie nur Dokumentmetadaten abrufen möchten, ohne große Markdown-Inhalte herunterzuladen, geben Sie die einfache Dokumentansicht an:

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"

Sie können view=DOCUMENT_VIEW_BASIC auch mit BatchGetDocuments verwenden:

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"

Feldmasken verwenden

Wenn Sie die Antwortnutzlasten weiter auf bestimmte Felder beschränken möchten, verwenden Sie den Standardparameter fields (Feldmaske) für Google APIs.

Filterfelder in GetDocument

So rufen Sie nur die Felder title, uri und updateTime eines Dokuments ab:

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

Filterfelder in BatchGetDocuments

So rufen Sie nur bestimmte Felder für jedes Dokument in einem Batch ab:

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"

Filterfelder in SearchDocumentChunks

So geben Sie nur die Chunks id und content, die übergeordneten Dokumente title und uri sowie die nextPageToken aus einer Suche zurück:

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

Fehler verarbeiten

Die Developer Knowledge API gibt standardmäßige HTTP-Statuscodes zurück. Die folgenden funktionalen Beispiele zeigen die Zuordnung von HTTP-Statuscodes und ihren Ursachen in der Developer Knowledge API:

• 400 INVALID_ARGUMENT:
  • Der Ausdrucksstring filter ist länger als 500 Zeichen.
  • Der Zeitstempel update_time ist ungültig (er muss das RFC 3339-Format haben).
  • In einem BatchGetDocuments-Antrag wurden mehr als 20 Dokumentnamen angegeben.
• 401 UNAUTHENTICATED: In der Anfrage fehlt ein API-Schlüssel oder es wird ein ungültiger Schlüssel verwendet. Weitere Informationen finden Sie unter Authentifizierung.
• 404 NOT_FOUND: Der angeforderte Dokumentname ist nicht vorhanden oder gehört zu einer Domain, die nicht im Korpus enthalten ist.
• 429 RESOURCE_EXHAUSTED: Das Kontingent des Projekts wurde überschritten. Weitere Informationen finden Sie unter Kontingente und Limits.

Nächste Schritte

• Weitere Informationen finden Sie unter Antworten aus Dokumentation generieren.
• Verbindung mit dem MCP-Server (Model Context Protocol) von Developer Knowledge herstellen und den retrieving-developer-knowledge KI-Agenten-Skill installieren, damit Ihre Unterstützung beim Programmieren offizielle Dokumentation durchsuchen und lesen kann.
• Clientbibliotheken in Python, Node.js, Go oder Java verwenden
• Informationen zur Verwendung der gcloud CLI
• In der Korpusreferenz finden Sie alle unterstützten Dokumentationsquellen.
• Die vollständigen Methodenspezifikationen finden Sie in der REST API-Referenz.
• Informationen zu API-Ratenbegrenzungen und ‑kontingenten finden Sie unter Kontingente und Limits.