이 가이드에서는 문서 검색, 단일 문서 가져오기, 일괄적으로 여러 문서 가져오기 등 개발자 지식 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"
pageSize와 같은 매개변수를 사용하여 검색 결과를 상세검색하여 페이지당 결과 수를 제한하고 pageToken를 사용하여 후속 페이지를 검색할 수 있습니다.
검색결과 필터링하기
filter 매개변수를 사용하여 검색 결과에 엄격한 필터를 적용합니다. 필터는 검색 결과 청크와 연결된 문서의 메타데이터에 적용됩니다.
필터링 지원 필드:
data_source(STRING): 문서의 소스입니다(예:docs.cloud.google.com).update_time(TIMESTAMP): 문서가 마지막으로 업데이트된 시간의 타임스탬프입니다.uri(STRING): 문서 URI입니다(예:https://docs.cloud.google.com/bigquery/docs/tables).
지원되는 연산자:
- 문자열 필드는 전체 문자열에 대한 정확한 일치를 위해
=(같음) 및!=(같지 않음)를 지원합니다. - TIMESTAMP 필드는
=,<,<=,>,>=을 지원합니다. 타임스탬프는 RFC-3339 형식이어야 합니다 (예:"2025-01-01T00:00:00Z").
AND, OR, NOT (또는 -) 논리 연산자를 사용하여 표현식을 결합할 수 있습니다. OR의 우선순위가 AND보다 높습니다.
다음 예에서는 'BigQuery'와 일치하는 문서를 검색하고 결과를 docs.cloud.google.com의 결과로 제한합니다.
curl "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks?query=BigQuery&filter=data_source%3D%22docs.cloud.google.com%22&key=$DEVELOPERKNOWLEDGE_API_KEY"
GetDocument로 문서 가져오기
documents.get 메서드를 사용하여 단일 문서의 전체 콘텐츠를 검색합니다.
다음 예에서는 documents/DOCUMENT_ID이라는 이름의 문서를 가져옵니다.
curl "https://developerknowledge.googleapis.com/v1/documents:get?name=documents/DOCUMENT_ID&key=$DEVELOPERKNOWLEDGE_API_KEY"
응답은 content 필드를 포함한 전체 Document 리소스입니다.
BatchGetDocuments로 여러 문서 가져오기
documents.batchGet 메서드를 사용하여 단일 API 호출에서 이름으로 최대 100개의 문서를 검색합니다. 이는 GetDocument 요청을 여러 번 수행하는 것보다 효율적입니다.
다음 예에서는 이름으로 두 문서를 가져옵니다.
curl "https://developerknowledge.googleapis.com/v1/documents:batchGet?names=documents/DOCUMENT_ID_1&names=documents/DOCUMENT_ID_2&key=$DEVELOPERKNOWLEDGE_API_KEY"
응답에는 요청된 Document 리소스 목록이 포함됩니다.