ドキュメントの検索と取得

このガイドでは、Developer Knowledge API を使用して、Google の公開デベロッパー ドキュメントをプログラムで検索して取得する方法について説明します。この API を使用すると、ウェブページを手動でスクレイピングするのではなく、関連するテキスト スニペットを検索したり、完全な Markdown ドキュメントを取得したりできます。

このドキュメントでは、次のタスクの例を示します。

• ドキュメント コーパスの検索。
• 検索結果のページ分割。
• 検索に複雑なフィルタを適用する。
• ドキュメントのコンテンツ全体を取得する。
• レスポンス ペイロードを最適化してレイテンシを短縮する。

始める前に、API を 有効にして、 Developer Knowledge API キーを生成していることを確認してください。次に、キーを環境変数に保存します。

export DEVELOPERKNOWLEDGE_API_KEY="YOUR_API_KEY"

ヒント: 生の抜粋ではなく、ドキュメントに基づいた自然言語の回答を生成する必要がある場合は、 根拠に基づいた生成でクエリに回答する をご覧ください。

SearchDocumentChunks でドキュメントを検索する

documents.searchDocumentChunks メソッドを使用して、クエリ文字列に一致するドキュメント チャンクを検索します。結果には、一致するドキュメントのコンテンツのチャンクと、ドキュメントのコンテンツ全体を取得するために使用できる parent 参照が含まれます。

次の例では、「BigQuery」に一致するドキュメントを検索します。

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

出力は次のようになります。

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

results リストの各結果には、次のものが含まれます。

• parent: ドキュメントのリソース名（documents/docs.cloud.google.com/bigquery/docs/introduction など）。
• id: ドキュメント内のチャンク識別子（chunk_0 など）。
• content: ドキュメントから一致したテキスト スニペット。
• document: ソース ドキュメントに関するメタデータ（title、uri、dataSource、updateTime など）。
• relevanceScore: 検索クエリに対するチャンクの関連性スコア（[0.0, 1.0] の範囲）。

レスポンス スキーマと使用可能なすべてのメタデータ フィールドの詳細については、 documents.searchDocumentChunks API リファレンスをご覧ください。

検索結果をページ分けする

検索クエリで複数の一致が返された場合は、ページ分割パラメータを使用して結果セットを移動できます。

• pageSize （整数）: 1 ページあたりの最大結果数を指定します。指定しない場合、API はデフォルトで 5 件の結果を返します。許容される最大値は 100 です。100 を超える値は 100 に強制変換されます。
• pageToken （文字列）: 前のレスポンスで受信したトークンを指定して、結果の次のページを取得します。

最初のページをリクエストする

ページサイズを設定するには、リクエストで pageSize パラメータを渡します。

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

追加の結果がある場合、レスポンスには 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"
}

後続のページを取得する

次のリクエストで nextPageToken の値を pageToken パラメータに渡します。

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

結果の最後のページに到達すると、レスポンスから nextPageToken が省略されます。

検索結果を絞り込む

filter パラメータを使用して、検索結果に厳密なフィルタを適用します。フィルタ式は、各チャンクの親ドキュメントのメタデータに適用されます。

filter 式は 500 文字以内に制限されています。

サポートされるフィールド

検索結果は、次の親ドキュメント フィールドを使用してフィルタできます。

• content_length_bytes（整数）: ドキュメントの content フィールドの長さ（バイト単位）。
• data_source （文字列）: ドキュメントのソース ドメイン（docs.cloud.google.com、firebase.google.com など）。サポートされているすべての データソースについては、 コーパス リファレンスをご覧ください。
• update_time （タイムスタンプ）: ドキュメントが最後に更新されたときのタイムスタンプ。値は RFC 3339 形式（ "2025-01-01T00:00:00Z"など）を使用する必要があります。
• uri （文字列）: ドキュメントの完全な URI（https://docs.cloud.google.com/bigquery/docs/tables など）。

サポートされている演算子

フィルタ式パーサーは、フィールドのデータ型に応じて異なる演算子をサポートしています。

• 文字列フィールド（data_source、uri）: 完全な文字列一致の場合は=（等しい）と!= （等しくない）をサポートします。部分一致、接頭辞一致、正規表現一致はサポートされていません。
• タイムスタンプ フィールド (update_time): =、<、<=、>、>= をサポートします。
• 整数フィールド (content_length_bytes): =、!=、<、<=、 >、>= をサポートします。
• 論理演算子: AND、OR、NOT（または -）を使用して条件を組み合わせます。

注釈: OR は AND よりも優先されます。明示的なグループ化には括弧 (...) を使用して、条件が意図した順序で評価されるようにします。

フィルタの例

次の例は、フィルタ式を作成する方法を示しています。curl で REST API を呼び出す場合は、フィルタ パラメータを URL エンコードするか、--data-urlencode を使用してください。

複数のデータソースに一致させる

OR を使用して、複数のソースのドキュメントを含めます。

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

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"

タイムスタンプでフィルタする

比較演算子と RFC 3339 タイムスタンプを使用して、特定の日付以降に更新されたコンテンツを検索します。

update_time >= "2025-01-01T00:00:00Z"

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"

コンテンツの長さでフィルタする

比較演算子と content_length_bytes を使用して、バイトサイズに基づいてドキュメントを検索します。

content_length_bytes < 5000

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"

データソース、タイムスタンプ、グループ化を組み合わせる

AND、OR、括弧 (...) を組み合わせて、特定の日付以降に更新された特定のソースに結果を制限します。

(data_source = "developer.chrome.com" OR data_source = "web.dev") AND update_time >= "2025-01-01T00:00:00Z"

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"

データソースを除外する

NOT または != を使用して、特定のソースの結果を除外します。

data_source != "firebase.google.com"

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"

GetDocument でドキュメントを取得する

documents.get メソッドを使用して、1 つのドキュメントのコンテンツ全体を取得します。

リソース名と URI

Developer Knowledge API でドキュメントを参照する場合は、リソース名とウェブ URI の違いに注意してください。

• リソース名（parent、name）: documents/{uri_without_scheme} の形式（例: documents/docs.cloud.google.com/storage/docs/creating-buckets）。この 値を GetDocument のパスパラメータまたは BatchGetDocuments の names パラメータとして渡します。
• ウェブ URI（uri）: スキームを含む完全なウェブ URL（たとえば、 https://docs.cloud.google.com/storage/docs/creating-buckets）。 filter 式を作成する場合は、uri フィールドにこの 形式を使用します（たとえば、 uri = "https://docs.cloud.google.com/storage/docs/creating-buckets"）。

次の例では、リソース名でドキュメントを取得します。

curl "https://developerknowledge.googleapis.com/v1/documents/docs.cloud.google.com/storage/docs/creating-buckets?key=$DEVELOPERKNOWLEDGE_API_KEY"

レスポンスは Document リソースで、メタデータと完全な Markdown コンテンツが content フィールドに含まれています。

BatchGetDocuments で複数のドキュメントを取得する

documents.batchGet メソッドを使用すると、1 回の API 呼び出しで最大 20 個のドキュメントを名前で取得できます。これは、GetDocument リクエストを複数回行うよりも効率的です。

次の例では、名前で 2 つのドキュメントを取得します。

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"

レスポンスには、リクエストした順にリクエストされた Document リソースのリストが含まれます。

レスポンス ペイロードを最適化する

Markdown 形式のドキュメント コンテンツは大きくなる可能性があります。アプリケーションでメタデータ（ページタイトル、URI、タイムスタンプなど）または特定のフィールドのみが必要な場合は、ペイロード サイズを最適化して帯域幅とレイテンシを削減できます。

ドキュメント ビューを使用する

view パラメータは、 Document メッセージに入力されるフィールドを制御します。

DocumentView 列挙型 は次の値をサポートしています。

• DOCUMENT_VIEW_BASIC: 基本的なメタデータ フィールド（name、uri、data_source、title、description、update_time、view）のみを返します。content フィールドは省略されます。
• DOCUMENT_VIEW_CONTENT: Markdown の content フィールドとともにメタデータ フィールドを返します。これは、GetDocument と BatchGetDocuments のデフォルトです。
• DOCUMENT_VIEW_FULL: すべてのドキュメント フィールドを返します。

大きな Markdown コンテンツをダウンロードせずにドキュメント メタデータのみを取得するには、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"

BatchGetDocuments で view=DOCUMENT_VIEW_BASIC を使用することもできます。

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"

フィールド マスクを使用する

レスポンス ペイロードを特定のフィールドにさらに制限するには、標準の Google APIs fields クエリ パラメータ （フィールド マスク）を使用します。

GetDocument のフィールドをフィルタする

ドキュメントの title、uri、updateTime フィールドのみを取得するには:

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

BatchGetDocuments のフィールドをフィルタする

バッチ内の各ドキュメントの特定のフィールドのみを取得するには:

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"

SearchDocumentChunks のフィールドをフィルタする

検索からチャンクの id と content、親ドキュメントの title と uri、nextPageToken のみを返すには:

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

エラーを処理する

Developer Knowledge API は標準の HTTP ステータス コードを返します。次の機能例は、Developer Knowledge API の HTTP ステータス コードとその原因をマッピングしています。

• 400 INVALID_ARGUMENT:
  • filter 式の文字列が 500 文字を超えています。
  • update_time タイムスタンプが無効です（RFC 3339 形式を使用する必要があります）。
  • BatchGetDocuments リクエストで 20 個を超えるドキュメント名が指定されました。
• 401 UNAUTHENTICATED: リクエストに API キーがないか、無効なキーを使用しています。認証をご覧ください。
• 404 NOT_FOUND: リクエストされたドキュメント名が存在しないか、コーパスに含まれていないドメインに属しています。
• 429 RESOURCE_EXHAUSTED: プロジェクトが割り当てを超過しました。 割り当てと上限をご覧ください。

次のステップ

• 根拠に基づいた生成でクエリに回答するをご覧ください。
• Python、 Node.js, Go, Java で クライアント ライブラリを使用する方法を確認する。
• コーパス リファレンスを参照して サポートされているすべてのドキュメント ソースを確認する。
• 完全な メソッド仕様については、REST API リファレンスを確認する。
• API レート制限と割り当ての割り当てと上限を確認する。