빠른 시작: 개발자 지식 API와 함께 gcloud CLI 사용

이 빠른 시작에서는 Google Cloud CLI를 사용하여 Developer Knowledge API로 질문에 답변하고 개발자 문서를 검색하고 가져오는 방법을 보여줍니다.

시작하기 전에

gcloud CLI로 Developer Knowledge API를 사용하기 전에 다음 단계를 완료하세요.

gcloud CLI 설치 및 구성

gcloud CLI를 설치하고 구성하려면 다음 단계를 완료하세요.

  1. gcloud CLI를 설치하지 않은 경우 gcloud CLI를 설치합니다.

  2. gcloud components update 명령어를 실행하여 최신 버전이 있는지 확인합니다.

    gcloud components update

  3. gcloud auth login 명령어를 실행하여 Google Cloud 계정에 로그인합니다.

    gcloud auth login

  4. gcloud config set 명령어를 실행하여 활성 Google Cloud 프로젝트를 설정합니다.

    gcloud config set project PROJECT_ID

    PROJECT_ID를 Google Cloud 프로젝트의 ID로 바꿉니다.

API 사용 설정

Developer Knowledge API를 사용 설정하려면 다음 단계를 완료하세요.

  1. gcloud services enable 명령어를 실행하여 Google Cloud 프로젝트에서 Developer Knowledge API를 사용 설정합니다.

    gcloud services enable developerknowledge.googleapis.com

    API를 사용 설정하거나 사용하는 데 특정 Identity and Access Management (IAM) 역할이 필요하지 않습니다.

  2. gcloud services list 명령어를 실행하여 프로젝트에 API가 사용 설정되어 있는지 확인합니다.

    gcloud services list --enabled \
    --filter="name:developerknowledge.googleapis.com"

    출력에 API 이름과 제목이 나열됩니다.

    NAME                                     TITLE
developerknowledge.googleapis.com  Developer Knowledge API

문서에서 답변 생성

gcloud developer-knowledge answer-query 명령어를 사용하면 Google 제품에 관해 질문하고 자연어로 된 직접적인 답변을 받을 수 있습니다. 이 명령어는 공식 문서 소스에서 정보를 가져오고 참조된 페이지에 대한 인용을 제공합니다.

질문하고 답변을 생성하려면 다음 단계를 완료하세요.

  1. 다음 명령어를 실행하여 Cloud Storage 버킷을 만드는 방법을 질문합니다.

    gcloud developer-knowledge answer-query \
    --query="How do I create a Cloud Storage bucket?"

  2. 명령어가 생성된 답변과 소스 참조를 YAML 형식으로 반환하는지 확인합니다.

    answer:
  answerText: |-
    To create a Cloud Storage bucket, you can use the Google Cloud console,
    the gcloud CLI (`gcloud storage buckets create`), client libraries, or
    the REST API...
  citations:
  - endIndex: 158
    sources:
    - referenceIndex: 0
    startIndex: 0
  references:
  - documentReference:
      documentChunk:
        content: |-
          This document shows you how to create a Cloud Storage
          [bucket](https://docs.cloud.google.com/storage/docs/buckets)...
        document:
          dataSource: docs.cloud.google.com
          name: documents/docs.cloud.google.com/storage/docs/creating-buckets
          title: Create a bucket
          uri: https://docs.cloud.google.com/storage/docs/creating-buckets
        parent: documents/docs.cloud.google.com/storage/docs/creating-buckets

    출력의 answer 객체에는 다음 필드가 포함됩니다.

    • answerText: 질문에 대해 생성된 자연어 답변입니다.
    • citations: referenceIndex에 의해 references의 지원 항목에 매핑되는 answerText의 바이트 오프셋 범위 startIndex 및 endIndex입니다.
    • references: 답변을 생성하는 데 사용된 소스 문서 청크 및 메타데이터(document, parent 포함)

문서 청크 검색

생성된 답변이 아닌 Google 개발자 문서에서 특정 텍스트 발췌문을 찾으려면 gcloud developer-knowledge documents search-chunks 명령어를 사용하세요. 이 명령어는 문서 코퍼스를 검색하고 일치하는 콘텐츠 청크를 상위 문서의 리소스 이름과 함께 반환합니다.

문서 청크를 검색하려면 다음 단계를 완료하세요.

  1. 다음 명령어를 실행하여 Cloud Storage 버킷 생성에 관한 문서를 검색합니다.

    gcloud developer-knowledge documents search-chunks \
    --query="How do I create a Cloud Storage bucket?"

  2. 명령어가 일치하는 문서 청크 목록을 YAML 형식으로 반환하는지 확인합니다.

    ---
content: |-
  This document shows you how to create a Cloud Storage
  [bucket](https://docs.cloud.google.com/storage/docs/buckets). If not otherwise
  specified in your request, buckets are created in the
  [US multi-region](https://docs.cloud.google.com/storage/docs/locations)...
document:
  contentLengthBytes: 31842
  dataSource: docs.cloud.google.com
  description: World-wide storage and retrieval of data in Google Cloud.
  name: documents/docs.cloud.google.com/storage/docs/creating-buckets
  title: Create a bucket
  updateTime: '2026-09-10T20:05:41Z'
  uri: https://docs.cloud.google.com/storage/docs/creating-buckets
  view: DOCUMENT_VIEW_BASIC
id: c1
parent: documents/docs.cloud.google.com/storage/docs/creating-buckets
relevanceScore: 0.856608

    출력의 각 청크에는 다음 필드가 포함됩니다.

    • content: 문서에서 일치하는 텍스트 스니펫입니다.
    • document: 소스 문서에 관한 메타데이터입니다(title, description, uri, dataSource, updateTime 포함).
    • id: 문서 내 청크의 식별자입니다.
    • parent: 상위 문서의 리소스 이름입니다. 이 값을 describe 명령어에 전달하여 전체 문서를 가져올 수 있습니다.
    • relevanceScore: 청크와 검색어의 관련성 점수입니다.

문서 가져오기

관련 문서 청크를 찾은 후 검색 결과의 parent 필드를 사용하여 문서의 전체 마크다운 콘텐츠를 가져옵니다.

문서의 리소스 이름과 함께 gcloud developer-knowledge documents describe 명령어를 실행합니다. 예를 들어 Cloud Storage 버킷 생성에 관한 문서를 가져오려면 다음 단계를 완료하세요.

  1. 다음 명령어를 실행합니다.

    gcloud developer-knowledge documents describe \
  documents/docs.cloud.google.com/storage/docs/creating-buckets

  2. 명령어가 문서의 메타데이터와 전체 마크다운 콘텐츠를 반환하는지 확인합니다.

    content: |
  This document shows you how to create a Cloud Storage [bucket](https://docs.cloud.google.com/storage/docs/buckets). If not otherwise specified in your request, buckets are
  created in the [`US` multi-region](https://docs.cloud.google.com/storage/docs/locations)
  with a default storage class of [Standard storage](https://docs.cloud.google.com/storage/docs/storage-classes)
  and have a seven-day [soft delete](https://docs.cloud.google.com/storage/docs/soft-delete)
  retention duration...
contentLengthBytes: 31842
dataSource: docs.cloud.google.com
description: World-wide storage and retrieval of data in Google Cloud.
name: documents/docs.cloud.google.com/storage/docs/creating-buckets
title: Create a bucket
updateTime: '2026-09-10T20:05:41Z'
uri: https://docs.cloud.google.com/storage/docs/creating-buckets
view: DOCUMENT_VIEW_CONTENT

    출력에는 다음 필드가 포함됩니다.

    • content: 문서의 전체 마크다운 텍스트입니다.
    • contentLengthBytes: 문서 콘텐츠의 총 크기(바이트)입니다.
    • dataSource: 문서를 호스팅하는 문서 도메인입니다.
    • description: 문서의 간단한 요약입니다.
    • name: 문서의 고유한 리소스 이름입니다.
    • title: 문서의 제목입니다.
    • updateTime: 문서가 마지막으로 업데이트된 타임스탬프입니다.
    • uri: 문서 페이지의 공개 URL입니다.
    • view: 반환된 문서 뷰 (DOCUMENT_VIEW_CONTENT, DOCUMENT_VIEW_BASIC, DOCUMENT_VIEW_FULL)입니다.

다음 단계