Dokumente suchen und abrufen

In diesem Leitfaden erfahren Sie, 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 Dokumentationskorpus suchen
  • Suchergebnisse paginieren
  • Komplexe Filter auf die Suche anwenden
  • Vollständigen Dokumentinhalt abrufen
  • Antwortnutzlasten optimieren, um die Latenz zu verringern

Bevor Sie beginnen, müssen Sie die API aktiviert und einen Developer Knowledge API-Schlüssel generiert haben. Speichern Sie dann den Schlüssel in einer Umgebungsvariablen:

export DEVELOPERKNOWLEDGE_API_KEY="YOUR_API_KEY"

Mit SearchDocumentChunks nach Dokumenten suchen

Verwenden Sie die documents.searchDocumentChunks Methode, um Dokumentblöcke zu finden, die mit einem Abfragestring übereinstimmen. Die Ergebnisse enthalten Inhaltsblöcke 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:

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:

  • pageSize (Ganzzahl): Gibt die maximale Anzahl der Ergebnisse an, die pro Seite zurückgegeben werden sollen. Wenn nichts angegeben ist, verwendet die API standardmäßig fünf Ergebnisse. Der maximal zulässige Wert ist 100. Werte über 100 werden auf 100 gesetzt.
  • pageToken (String): Gibt das Token an, das in einer vorherigen Antwort empfangen wurde, um die nächste Ergebnisseite abzurufen.

Erste Seite anfordern

Übergeben Sie den Parameter pageSize in Ihrer Anfrage, um die Seitengröße festzulegen:

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

Nachfolgende Seiten abrufen

Ü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 erreicht haben, wird nextPageToken aus der Antwort entfernt.

Suchergebnisse filtern

Verwenden Sie den Parameter filter, um einen strengen Filter auf die Suchergebnisse anzuwenden. Der Filterausdruck wird auf die Metadaten des übergeordneten Dokuments für jeden Block angewendet.

Der filter-Ausdruck 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 Korpusreferenz.
  • 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 genauen 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 -).

Beispiele für Filter

Die folgenden Beispiele zeigen, wie Filterausdrücke erstellt werden. Wenn Sie die REST API mit curl aufrufen, müssen Sie den Filterparameter URL-codieren oder --data-urlencode verwenden.

Mehrere Datenquellen abgleichen

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

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

curl-Anfrage:

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"

curl-Anfrage:

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

curl-Anfrage:

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"

curl-Anfrage:

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"

curl-Anfrage:

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 mit GetDocument abrufen

Verwenden Sie die documents.get Methode, um den vollständigen Inhalt eines einzelnen Dokuments abzurufen.

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): Im Format documents/{uri_without_scheme}, z. B. documents/docs.cloud.google.com/storage/docs/creating-buckets. Übergeben Sie diesen Wert 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 filter-Ausdrücke erstellen (z. B. uri = "https://docs.cloud.google.com/storage/docs/creating-buckets").

Im folgenden Beispiel wird ein Dokument anhand seines Ressourcennamens abgerufen:

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.

Mehrere Dokumente mit BatchGetDocuments abrufen

Verwenden Sie die documents.batchGet Methode, um mit einem einzigen API-Aufruf bis zu 20 Dokumente anhand des Namens 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

Mit dem view Parameter wird gesteuert, welche Felder in Document Nachrichten ausgefüllt werden.

Die DocumentView Enumeration unterstützt die folgenden Werte:

  • DOCUMENT_VIEW_BASIC: Gibt nur grundlegende Metadatenfelder zurück (name, uri, data_source, title, description, update_time und view). Das Feld content wird weggelassen.
  • DOCUMENT_VIEW_CONTENT: Gibt Metadatenfelder zusammen mit dem Markdown-Feld content zurück. Dies ist die Standardeinstellung für GetDocument und BatchGetDocuments.
  • DOCUMENT_VIEW_FULL: Gibt alle Dokumentfelder zurück.

Wenn Sie nur Dokumentmetadaten abrufen möchten, ohne große Markdown-Inhalte herunterzuladen, legen Sie view=DOCUMENT_VIEW_BASIC fest:

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"

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 ist länger als 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 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 Projekt hat sein Kontingent überschritten. Weitere Informationen finden Sie unter Kontingente und Limits.

Nächste Schritte