문서 검색 및 가져오기

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

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

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

시작하기 전에 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 (정수): 페이지당 반환할 최대 결과 수를 지정합니다. 지정하지 않으면 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 (또는 -)를 사용하여 조건을 결합합니다.

필터 예시

다음 예에서는 필터 표현식을 구성하는 방법을 보여줍니다. 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 메서드를 사용하여 단일 문서의 전체 콘텐츠를 가져옵니다.

리소스 이름과 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"

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

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, 타임스탬프) 또는 특정 필드만 필요한 경우 페이로드 크기를 최적화하여 대역폭과 지연 시간을 줄일 수 있습니다.

문서 뷰 사용

view 매개변수는 Document 메시지에 채워지는 필드를 제어합니다.

DocumentView enum 은 다음 값을 지원합니다.

  • DOCUMENT_VIEW_BASIC: 기본 메타데이터 필드 (name, uri, data_source, title, description, update_time, view)만 반환합니다. content 필드는 생략됩니다.
  • DOCUMENT_VIEW_CONTENT: 마크다운 content 필드와 함께 메타데이터 필드를 반환합니다. 이는 GetDocument 및 BatchGetDocuments의 기본값입니다.
  • DOCUMENT_VIEW_FULL: 모든 문서 필드를 반환합니다.

큰 마크다운 콘텐츠를 다운로드하지 않고 문서 메타데이터만 가져오려면 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 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"

검색에서 청크 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 또는 자바에서 클라이언트 라이브러리를 사용하는 방법을 알아보세요.
  • 코퍼스 참조를 탐색하여 지원되는 모든 문서 소스를 확인하세요.
  • 전체 메서드 사양은 REST API 참조를 검토하세요.
  • API 비율 제한 및 할당량의 할당량 및 한도를 확인하세요.