Dokumente suchen und abrufen

In diesem Dokument wird beschrieben, wie Sie mit der Developer Knowledge API programmatisch in der öffentlichen Entwicklerdokumentation von Google suchen und diese abrufen. Anstatt Webseiten manuell zu crawlen, können Ihre Anwendungen mit der API relevante Text-Snippets finden oder vollständige Markdown-Dokumente abrufen.

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

• Im Dokumentationscorpus suchen.
• Suchergebnisse paginieren.
• Komplexe Filter auf Ihre Suche anwenden.
• Vollständigen Dokumentinhalt abrufen.
• Antwortnutzlasten optimieren, um die Latenz zu reduzieren.

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

gcloud

Installieren und konfigurieren Sie die gcloud CLI und aktivieren Sie die Developer Knowledge API.

REST

Aktivieren Sie die API und generieren Sie einen Developer Knowledge API-Schlüssel. 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 generierte Antworten in natürlicher Sprache aus der Dokumentation anstelle von Rohauszügen benötigen, lesen Sie 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 Dokumentblöcke zu finden, die mit einem Abfragestring übereinstimmen. Die Ergebnisse enthalten Blöcke mit Inhalten aus übereinstimmenden Dokumenten sowie einen parent-Verweis, mit dem Sie den vollständigen Inhalt dieser Dokumente abrufen können.

Im folgenden Beispiel wird nach Dokumenten gesucht, die mit „BigQuery“ übereinstimmen:

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 Liste results enthält Folgendes:

• parent: Der Ressourcenname des Dokuments, z. B. documents/docs.cloud.google.com/bigquery/docs/introduction.
• id: Die Block-ID im Dokument, 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 Blocks für die Suchanfrage im Bereich [0.0, 1.0].

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

Suchergebnisse paginieren

Wenn eine Suchanfrage mehrere Treffer zurückgibt, können Sie mit Paginierungsparametern durch die Ergebnisse navigieren:

• --page-size (gcloud CLI) oder pageSize (Ganzzahl): Gibt die maximale Anzahl der Ergebnisse an, die pro Seite zurückgegeben werden sollen. Wenn nicht angegeben, verwendet die API standardmäßig fünf Ergebnisse. 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 auf allen Seiten 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

Übergeben Sie die Flags --page-size und --limit, um die Anzahl der Ergebnisse pro Seite und die Gesamtzahl der zurückgegebenen Ergebnisse zu steuern:

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

REST

1. Übergeben Sie den Parameter pageSize in Ihrer Anfrage, um die erste Seite anzufordern:

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

   Wenn weitere 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. Übergeben Sie den Wert von nextPageToken in Ihrer nächsten Anfrage an den Parameter pageToken, um nachfolgende Seiten abzurufen:

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

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

Suchergebnisse filtern

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

Der Filterausdruck ist auf 500 Zeichen begrenzt.

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. Alle unterstützten Datenquellen finden Sie in der Corpus-Referenz.
• update_time (Zeitstempel): Der Zeitstempel, der angibt, wann das Dokument zuletzt aktualisiert wurde. Werte müssen das RFC 3339-Format verwenden, 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 unterschiedliche Operatoren:

• Stringfelder (data_source, uri): Unterstützen = (gleich) und != (ungleich) für den exakten Stringabgleich. Teilweise Übereinstimmungen, Präfixübereinstimmungen und Übereinstimmungen mit regulären Ausdrücken 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 -).

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

Beispiele für Filter

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

Mit einer einzelnen Datenquelle übereinstimmen

Beschränken Sie die Suchergebnisse auf eine einzelne Dokumentationsdomain:

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"

Mit mehreren Datenquellen übereinstimmen

Verwenden Sie OR, um Dokumente aus mehreren Quellen einzuschließen:

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 Inhalte zu finden, 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 Inhaltlänge filtern

Verwenden Sie Vergleichsoperatoren mit content_length_bytes, um Dokumente anhand ihrer Größe in Byte zu 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 gcloud developer-knowledge documents describe Befehl oder die documents.get REST-Methode, 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 content Feld enthält.

Ressourcennamen im Vergleich zu URIs

Beachten Sie beim Verweisen auf Dokumente in der Developer Knowledge API den Unterschied zwischen Ressourcennamen und Web-URIs:

• Ressourcenname (parent, name): Im Format documents/{uri_without_scheme}, z. B. documents/docs.cloud.google.com/storage/docs/creating-buckets. Übergeben Sie diesen Wert als Positionsparameter in gcloud developer-knowledge documents describe, als Pfadparameter 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 documents.batchGet Methode, um bis zu 20 Dokumente anhand des Namens in einem einzigen API-Aufruf abzurufen. Das ist effizienter als mehrere GetDocument-Anfragen.

Im folgenden Beispiel werden zwei Dokumente anhand des Namens 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 Reihenfolge, in der Sie sie angefordert haben.

Antwortnutzlasten optimieren

Dokumentinhalte im Markdown-Format können groß 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 --view Flag und die DocumentView Enum 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 content Feld 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 grundlegende 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 Standard Abfrageparameter fieldsder Google APIs (Feldmaske).

Felder in GetDocument filtern

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"

Felder in BatchGetDocuments filtern

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"

Felder in SearchDocumentChunks filtern

So geben Sie nur die Block-id und den content, den title und den uri des übergeordneten Dokuments sowie das 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 Standard-HTTP-Statuscodes zurück. In den folgenden Beispielen werden HTTP-Statuscodes und ihre Ursachen in der Developer Knowledge API zugeordnet:

• 400 INVALID_ARGUMENT:
  • Der String des filter-Ausdrucks überschreitet 500 Zeichen.
  • Der Zeitstempel update_time ist ungültig (muss das RFC 3339-Format verwenden).
  • In einer BatchGetDocuments-Anfrage wurden mehr als 20 Dokumentnamen angegeben.
• 401 UNAUTHENTICATED: In der Anfrage fehlt ein API-Schlüssel oder ein Bearertoken oder es werden ungültige Anmeldedaten 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 Corpus enthalten ist.
• 429 RESOURCE_EXHAUSTED: Das Projekt hat sein Kontingent überschritten. Weitere Informationen finden Sie unter Kontingente und Limits.

Nächste Schritte

• Weitere Informationen finden Sie unter Antworten aus der Dokumentation generieren.
• Verbinden Sie sich mit dem Developer Knowledge MCP-Server und installieren Sie die retrieving-developer-knowledge KI-Agenten-Skills, damit Ihre KI-Unterstützung beim Programmieren in der offiziellen Dokumentation suchen und diese lesen kann.
• Informationen zur Verwendung von Clientbibliotheken in Python, Node.js, Go oder Java.
• Informationen zur Verwendung der gcloud CLI.
• In der Corpus-Referenz finden Sie alle unterstützten Dokumentationsquellen.
• In der REST API-Referenz finden Sie vollständige Methodenspezifikationen.
• Unter Kontingente und Limits finden Sie Informationen zu API-Ratenbegrenzungen und Kontingenten.