Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

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

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

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

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

始める前に、使用するツールに合わせて環境を設定します。

gcloud

gcloud CLI をインストールして構成し、Developer Knowledge API を有効にします。

REST

API を有効にして、Developer Knowledge API キーを生成します。次に、キーを環境変数に保存します。

export DEVELOPERKNOWLEDGE_API_KEY="YOUR_API_KEY"

YOUR_API_KEY は、Developer Knowledge API キーに置き換えます。

ドキュメントを検索する

gcloud developer-knowledge documents search-chunks コマンドまたは documents.searchDocumentChunks REST メソッドを使用して、クエリ文字列に一致するドキュメントチャンクを見つけます。結果には、一致するドキュメントのコンテンツのチャンクと、これらのドキュメントのコンテンツ全体を取得するために使用できる parent リファレンスが含まれます。

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

gcloud

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

REST

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: ドキュメント内のチャンク ID（例: chunk_0）。
content: ドキュメントから一致したテキストスニペット。
document: ソースドキュメントに関するメタデータ（title、uri、dataSource、updateTime など）。
relevanceScore: 検索クエリに対するチャンクの関連性スコア（[0.0, 1.0] の範囲内）。

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

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

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

--page-size（gcloud CLI）または pageSize（整数）: ページごとに返す結果の最大数を指定します。指定しない場合、API はデフォルトで 5 件の結果を返します。最大許容値は 100 です。100 を超える値は 100 に強制変換されます。
--limit（gcloud CLI）または pageToken（文字列）: gcloud CLI で --limit を使用して、ページ間で返される結果の合計数を制御します。REST リクエストでは、前のレスポンスで受け取った pageToken 値を渡して、結果の次のページを取得します。

gcloud

--page-size フラグと --limit フラグを渡して、ページあたりの結果数と返される結果の合計数を制御します。

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

REST

最初のページをリクエストするには、リクエストで 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 が省略されます。

検索結果を絞り込む

gcloud CLI の --query-filter フラグまたは REST リクエストの 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（または -）を使用して条件を結合します。

フィルタの例

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

単一のデータソースを照合する

検索結果を単一のドキュメントドメインに制限します。

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"

複数のデータソースを照合する

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

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"

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

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

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"

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

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

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"

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

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

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

データソースを除外する

NOT または != を使用して、特定の結果を検索結果から除外します。

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"

ドキュメントを取得する

gcloud developer-knowledge documents describe コマンドまたは documents.get REST メソッドを使用して、単一のドキュメントのコンテンツ全体を取得します。

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

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"

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

リソース名と URI

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

リソース名（parent、name）: documents/{uri_without_scheme} 形式（例: documents/docs.cloud.google.com/storage/docs/creating-buckets）。この値は、gcloud developer-knowledge documents describe の位置引数、GetDocument のパスパラメータ、または BatchGetDocuments の names パラメータとして渡します。
ウェブ URI（uri）: スキームを含む完全なウェブ URL（例: https://docs.cloud.google.com/storage/docs/creating-buckets）。--query-filter 式または filter 式を構築するときに、uri フィールドにこの形式を使用します（例: uri = "https://docs.cloud.google.com/storage/docs/creating-buckets"）。

`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 リソースのリストがリクエストした順序で含まれます。

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

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

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

gcloud CLI の --view フラグまたは REST リクエストの view パラメータは、Document メッセージでどのフィールドが入力されるかを制御します。

--view フラグと DocumentView 列挙型は、次の値をサポートしています。

--view=basic（gcloud CLI）または DOCUMENT_VIEW_BASIC: 基本メタデータフィールド（name、uri、dataSource、title、description、updateTime、view）のみを返します。content フィールドは省略されます。
--view=content（gcloud CLI）または DOCUMENT_VIEW_CONTENT: Markdown の content フィールドとともにメタデータフィールドを返します。これは、gcloud developer-knowledge documents describe、GetDocument、BatchGetDocuments のデフォルトです。
--view=full（gcloud CLI）または DOCUMENT_VIEW_FULL: すべてのドキュメントフィールドを返します。

大きな Markdown コンテンツをダウンロードせずにドキュメントのメタデータのみを取得するには、基本ドキュメントビューを指定します。

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"

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 API の 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: プロジェクトが割り当てを超過しました。割り当てと上限をご覧ください。

次のステップ

ドキュメントから回答を生成するをご覧ください。
Developer Knowledge MCP サーバーに接続し、retrieving-developer-knowledge エージェントスキルをインストールして、AI コーディングアシスタントが公式ドキュメントを検索して読み取れるようにします。
Python、Node.js、Go、Java でクライアントライブラリを使用する方法を確認する。
gcloud CLI を使用する方法を確認する。
コーパスリファレンスを参照して、サポートされているすべてのドキュメントソースを表示します。
メソッドの完全な仕様については、REST API リファレンスをご覧ください。
API レート制限と割り当てについては、割り当てと上限を確認してください。

ドキュメントの検索と取得 コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

gcloud

REST

ドキュメントを検索する

gcloud

REST

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

gcloud

REST

検索結果を絞り込む

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

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

フィルタの例

単一のデータソースを照合する

gcloud

REST

複数のデータソースを照合する

gcloud

REST

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

gcloud

REST

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

gcloud

REST

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

gcloud

REST

データソースを除外する

gcloud

REST

ドキュメントを取得する

gcloud

REST

リソース名と URI

BatchGetDocuments を使用して複数のドキュメントを取得する

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

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

gcloud

REST

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

GetDocument のフィルタ フィールド

BatchGetDocuments のフィルタ フィールド

SearchDocumentChunks のフィルタ フィールド

エラーを処理する

次のステップ

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

`BatchGetDocuments` を使用して複数のドキュメントを取得する

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

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

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

`GetDocument` のフィルタフィールド

`BatchGetDocuments` のフィルタフィールド

`SearchDocumentChunks` のフィルタフィールド