Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

문서 검색 및 가져오기

이 문서에서는 Developer Knowledge API를 사용하여 Google의 공개 개발자 문서를 프로그래매틱 방식으로 검색하고 가져오는 방법을 보여줍니다. API를 사용하면 웹페이지를 수동으로 스크레이핑하는 대신 애플리케이션에서 관련 텍스트 스니펫을 찾거나 전체 마크다운 문서를 가져올 수 있습니다.

이 문서에서는 다음 작업의 예를 확인할 수 있습니다.

문서 코퍼스 검색
검색 결과 페이지로 나누기
검색에 복잡한 필터 적용
전체 문서 콘텐츠 가져오기
지연 시간을 줄이기 위해 응답 페이로드 최적화

시작하기 전에 선호하는 도구의 환경을 설정하세요.

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: 문서 내 청크 식별자 (예: 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"

응답은 메타데이터와 content 필드의 전체 마크다운 콘텐츠가 포함된 Document 리소스입니다.

리소스 이름과 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 메서드를 사용하여 단일 API 호출에서 이름으로 최대 20개의 문서를 가져옵니다. 이는 여러 GetDocument 요청을 하는 것보다 더 효율적입니다.

다음 예에서는 이름으로 두 문서를 가져옵니다.

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 enum은 다음 값을 지원합니다.

--view=basic (gcloud CLI) 또는 DOCUMENT_VIEW_BASIC: 기본 메타데이터 필드 (name, uri, dataSource, title, description, updateTime, view)만 반환합니다. content 필드는 생략됩니다.
--view=content (gcloud CLI) 또는 DOCUMENT_VIEW_CONTENT: 마크다운 content 필드와 함께 메타데이터 필드를 반환합니다. 이는 gcloud developer-knowledge documents describe, GetDocument, 및 BatchGetDocuments의 기본값입니다.
--view=full (gcloud CLI) 또는 DOCUMENT_VIEW_FULL: 모든 문서 필드를 반환합니다.

큰 마크다운 콘텐츠를 다운로드하지 않고 문서 메타데이터만 가져오려면 기본 문서 뷰를 지정합니다.

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`의 필터 필드