노트북에서 데이터 소스 추가 및 관리 (API)

노트북을 만든 후에는 다양한 콘텐츠 유형을 데이터 소스로 추가할 수 있습니다. 일괄적으로 또는 단일 파일로 업로드할 수 있습니다. 소스에는 Google Docs, Google Slides, 원시 텍스트, 웹 콘텐츠, YouTube 동영상 등이 포함됩니다.

이 페이지에서는 다음 작업을 수행하는 방법을 설명합니다.

시작하기 전에

Google Docs 또는 Google Slides를 데이터 소스로 추가하려면 Google 사용자 인증 정보를 사용하여 Google Drive에 대한 액세스를 승인해야 합니다. 이렇게 하려면 다음 gcloud auth login 명령어를 실행하고 CLI의 안내를 따릅니다.

gcloud auth login --enable-gdrive-access

미국 멀티 리전 엔드포인트 사용

Gemini Notebook Enterprise 구독이 미국 멀티 리전에 있는 경우 이 페이지의 요청을 미국 멀티 리전 엔드포인트인 discoveryengine.us.rep.googleapis.com로 전송할 수 있습니다. 멀티 리전 엔드포인트는 요청을 처리하고 멀티 리전 내에서 TLS를 종료하므로 요청 데이터는 전송 중에 미국에 유지됩니다. 이 엔드포인트를 사용해도 노트북이 저장되는 위치는 변경되지 않습니다. 자세한 내용은 Google Cloud보안 가이드의 리전 및 멀티 리전 API 엔드포인트 개요를 참조하세요.

미국 멀티 리전 엔드포인트를 사용하려면 이 페이지의 각 요청 URL을 다음과 같이 변경합니다.

  1. ENDPOINT_LOCATION-discoveryengine.googleapis.com 호스트를 discoveryengine.us.rep.googleapis.com로 바꿉니다.

  2. LOCATION을 us로 설정합니다.

각 요청의 나머지 부분은 동일하게 유지됩니다. 구독의 멀티 리전을 선택하는 방법은 구독 가져오기를 참조하세요. 리전 및 멀티 리전 서비스 엔드포인트 목록은 가상 프라이빗 클라우드 가이드의 리전 및 멀티 리전 서비스 엔드포인트를 참조하세요.

일괄적으로 데이터 소스 추가

노트북에 소스를 추가하려면 notebooks.sources.batchCreate 메서드를 호출합니다.

REST

curl -X POST \
  -H "Authorization:Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
     "https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_NUMBER/locations/LOCATION/notebooks/NOTEBOOK_ID/sources:batchCreate" \
  -d '{
  "userContents": [
    {
    USER_CONTENT
    }
   ]
  }'

다음을 바꿉니다.

  • ENDPOINT_LOCATION: API 요청의 멀티 리전입니다. 다음 값 중 하나를 지정합니다.
    • 미국 멀티 리전의 경우 us
    • EU 멀티 리전의 경우 eu
    • 전역 위치의 경우 global
    자세한 내용은 데이터 스토어의 멀티 리전 지정을 참조하세요.
  • PROJECT_NUMBER: Google Cloud 프로젝트 수
  • LOCATION: 데이터 스토어의 지리적 위치입니다(예: global). 자세한 내용은 위치를 참조하세요.
  • NOTEBOOK_ID: 노트북의 고유 식별자입니다.
  • USER_CONTENT: 데이터 소스 콘텐츠입니다.

다음 데이터 소스 중 하나만 콘텐츠로 추가할 수 있습니다.

  • Google Docs 또는 Google Slides로 구성된 Google Drive 콘텐츠의 경우 다음을 추가합니다.

     "googleDriveContent": {
   "documentId": "DOCUMENT_ID_GOOGLE",
   "mimeType": "MIME_TYPE",
   "sourceName": "DISPLAY_NAME_GOOGLE"
 }

    다음을 바꿉니다.

    • DOCUMENT_ID_GOOGLE: Google Drive에 있는 파일의 ID입니다. 이 ID는 파일의 URL에 표시됩니다. 파일의 문서 ID를 가져오려면 파일을 엽니다. URL의 패턴은 https://docs.google.com/FILE_TYPE/d/DOCUMENT_ID_GOOGLE/edit?resourcekey=RESOURCE_KEY입니다.
    • MIME_TYPE: 선택한 문서의 MIME 유형입니다. Google Docs의 경우 application/vnd.google-apps.document, Google Slides의 경우 application/vnd.google-apps.presentation를 사용합니다.
    • DISPLAY_NAME_GOOGLE: 데이터 소스의 표시 이름입니다.

  • 원시 텍스트 입력의 경우 다음을 추가합니다.

      "textContent": {
    "sourceName": "DISPLAY_NAME_TEXT",
    "content": "TEXT_CONTENT"
  }

    다음을 바꿉니다.

    • DISPLAY_NAME_TEXT: 데이터 소스의 표시 이름입니다.
    • TEXT_CONTENT: 데이터 소스로 업로드하려는 원시 텍스트 콘텐츠입니다.

  • 웹 콘텐츠의 경우 다음을 추가합니다.

     "webContent": {
   "url": "URL_WEBCONTENT",
   "sourceName": "DISPLAY_NAME_WEB"
 }

    다음을 바꿉니다.

    • URL_WEBCONTENT: 데이터 소스로 업로드하려는 콘텐츠의 URL입니다.
    • DISPLAY_NAME_WEB: 데이터 소스의 표시 이름입니다.

  • 동영상 콘텐츠의 경우 다음을 추가합니다.

     "videoContent": {
   "youtubeUrl": "URL_YOUTUBE"
 }

    URL_YOUTUBE를 데이터 소스로 업로드하려는 YouTube 동영상의 URL로 바꿉니다.

요청이 성공하면 다음 JSON과 유사한 source 객체의 인스턴스를 응답으로 가져옵니다. 데이터 소스 검색 또는 삭제와 같은 다른 작업을 수행하는 데 필요한 SOURCE_ID 및 SOURCE_RESOURCE_NAME를 기록해 둡니다.

{
  "sources": [
    {
      "sourceId": {
        "id": "SOURCE_ID"
      },
      "title": "DISPLAY_NAME",
      "metadata": {
        "xyz": "abc"
      },
      "settings": {
        "status": "SOURCE_STATUS_COMPLETE"
      },
      "name": "SOURCE_RESOURCE_NAME"
    }
  ]
}

파일을 소스로 업로드하기

데이터 소스를 일괄적으로 추가하는 것 외에도 노트북에서 데이터 소스로 사용할 수 있는 단일 파일을 업로드할 수 있습니다. 단일 파일을 업로드하려면 notebooks.sources.uploadFile 메서드를 호출합니다.

REST

curl -X POST --data-binary "@PATH/TO/FILE" \
  -H "Authorization:Bearer $(gcloud auth print-access-token)" \
  -H "X-Goog-Upload-File-Name: FILE_DISPLAY_NAME" \
  -H "X-Goog-Upload-Protocol: raw" \
  -H "Content-Type: CONTENT_TYPE" \
  "https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/upload/v1alpha/projects/PROJECT_NUMBER/locations/LOCATION/notebooks/NOTEBOOK_ID/sources:uploadFile" \

다음을 바꿉니다.

  • PATH/TO/FILE: 업로드하려는 파일의 경로입니다.
  • FILE_DISPLAY_NAME: 노트북에 있는 파일의 표시 이름을 나타내는 문자열입니다.
  • CONTENT_TYPE: 업로드하려는 콘텐츠 유형입니다. 지원되는 콘텐츠 유형 목록은 지원되는 콘텐츠 유형을 참조하세요.
  • ENDPOINT_LOCATION: API 요청의 멀티 리전입니다. 다음 값 중 하나를 지정합니다.
    • 미국 멀티 리전의 경우 us
    • EU 멀티 리전의 경우 eu
    • 전역 위치의 경우 global
    자세한 내용은 데이터 스토어의 멀티 리전 지정을 참조하세요.
  • PROJECT_NUMBER: Google Cloud 프로젝트 수
  • LOCATION: 데이터 스토어의 지리적 위치입니다(예: global). 자세한 내용은 위치를 참조하세요.
  • NOTEBOOK_ID: 노트북의 고유 식별자입니다.

요청이 성공하면 다음과 비슷한 JSON 응답이 표시됩니다.

{
  "sourceId": {
    "id": "SOURCE_ID"
  }
}

지원되는 콘텐츠 유형

소스로 업로드하는 파일은 지원되는 파일이어야 합니다.

지원되는 문서 콘텐츠 유형은 다음과 같습니다.

파일 확장자 콘텐츠 유형
.pdf application/pdf
.txt text/plain
.md text/markdown
.docx application/vnd.openxmlformats-officedocument.wordprocessingml.document
.pptx application/vnd.openxmlformats-officedocument.presentationml.presentation
.xlsx application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

지원되는 오디오 콘텐츠 유형은 다음과 같습니다.

파일 확장자 콘텐츠 유형
.3g2 audio/3gpp2
.3gp audio/3gpp
.aac audio/aac
.aif audio/aiff
.aifc audio/aiff
.aiff audio/aiff
.amr audio/amr
.au audio/basic
.avi video/x-msvideo
.cda application/x-cdf
.m4a audio/m4a
.mid audio/midi
.midi audio/midi
.mp3 audio/mpeg
.mp4 video/mp4
.mpeg audio/mpeg
.ogg audio/ogg
.opus audio/ogg
.ra audio/vnd.rn-realaudio
.ram audio/vnd.rn-realaudio
.snd audio/basic
.wav audio/wav
.weba audio/webm
.wma audio/x-ms-wma

지원되는 이미지 콘텐츠 유형은 다음과 같습니다.

파일 확장자 콘텐츠 유형
.png image/png
.jpg image/jpg
.jpeg image/jpeg

소스 가져오기

노트북에 추가된 특정 소스를 가져오려면 notebooks.sources.get 메서드를 사용합니다.

REST

curl -X GET \
  -H "Authorization:Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_NUMBER/locations/LOCATION/notebooks/NOTEBOOK_ID/sources/SOURCE_ID"

다음을 바꿉니다.

  • ENDPOINT_LOCATION: API 요청의 멀티 리전입니다. 다음 값 중 하나를 지정합니다.
    • 미국 멀티 리전의 경우 us
    • EU 멀티 리전의 경우 eu
    • 전역 위치의 경우 global
    자세한 내용은 데이터 스토어의 멀티 리전 지정을 참조하세요.
  • PROJECT_NUMBER: Google Cloud 프로젝트 수
  • LOCATION: 데이터 스토어의 지리적 위치입니다(예: global). 자세한 내용은 위치를 참조하세요.
  • NOTEBOOK_ID: 노트북을 만들 때 받은 고유 식별자입니다. 자세한 내용은 노트북 만들기를 참조하세요.
  • SOURCE_ID: 노트북에 소스를 추가할 때 받은 소스 식별자입니다.

요청이 성공하면 다음과 비슷한 JSON 응답이 표시됩니다.

{
  "sources": [
    {
      "sourceId": {
        "id": "SOURCE_ID"
      },
      "title": "DISPLAY_NAME",
      "metadata": {
        "wordCount": 148,
        "tokenCount": 160
      },
      "settings": {
        "status": "SOURCE_STATUS_COMPLETE"
      },
     "name": "SOURCE_RESOURCE_NAME"

    }
  ]
}

노트북에서 데이터 소스 삭제

노트북에서 데이터 소스를 일괄 삭제하려면 notebooks.sources.batchDelete 메서드를 사용합니다.

REST

  curl -X POST \
    -H "Authorization:Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    "https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_NUMBER/locations/LOCATION/notebooks/NOTEBOOK_ID/sources:batchDelete" \
    -d '{
      "names": [
        "SOURCE_RESOURCE_NAME_1",
        "SOURCE_RESOURCE_NAME_2"
      ]
    }'

다음을 바꿉니다.

  • ENDPOINT_LOCATION: API 요청의 멀티 리전입니다. 다음 값 중 하나를 지정합니다.
    • 미국 멀티 리전의 경우 us
    • EU 멀티 리전의 경우 eu
    • 전역 위치의 경우 global
    자세한 내용은 데이터 스토어의 멀티 리전 지정을 참조하세요.
  • PROJECT_NUMBER: Google Cloud 프로젝트 수
  • LOCATION: 데이터 스토어의 지리적 위치입니다(예: global). 자세한 내용은 위치를 참조하세요.
  • NOTEBOOK_ID: 노트북의 고유 식별자입니다.
  • SOURCE_RESOURCE_NAME: 삭제할 데이터 소스의 전체 리소스 이름입니다. 이 필드의 패턴은 projects/PROJECT_NUMBER/locations/LOCATION/notebooks/NOTEBOOK_ID/source/SOURCE_ID입니다.

요청이 성공하면 빈 JSON 객체가 반환됩니다.

다음 단계