Cómo agregar y administrar fuentes de datos en un notebook (API)

Después de crear tu cuaderno, puedes agregarle varios tipos de contenido como fuentes de datos. Puedes hacerlo por lotes o como archivos individuales. Algunas de las fuentes incluyen Documentos de Google, Presentaciones de Google, texto sin procesar, contenido web y videos de YouTube.

En esta página, se describe cómo realizar las siguientes tareas:

Antes de comenzar

Si planeas agregar Documentos de Google o Presentaciones de Google como fuente de datos, debes autorizar el acceso a Google Drive con las credenciales de usuario de Google. Para hacerlo, ejecuta el siguiente comando gcloud auth login y sigue las instrucciones en la CLI.

gcloud auth login --enable-gdrive-access

Usa el extremo multirregional de EE.UU.

Si tu suscripción a Gemini Notebook Enterprise se encuentra en la multirregión de EE.UU., puedes enviar las solicitudes de esta página al extremo multirregional de EE.UU., discoveryengine.us.rep.googleapis.com. Un extremo multirregional procesa tus solicitudes y finaliza TLS dentro de la multirregión, por lo que los datos de tu solicitud permanecen en EE.UU. mientras están en tránsito. El uso de este extremo no cambia la ubicación en la que se almacenan tus notebooks. Para obtener más información, consulta Descripción general de los extremos de API regionales y multirregionales en la guía de seguridad de Google Cloud.

Para usar el extremo multirregional de EE.UU., realiza los siguientes cambios en cada URL de solicitud de esta página:

  1. Reemplaza el host ENDPOINT_LOCATION-discoveryengine.googleapis.com por discoveryengine.us.rep.googleapis.com.

  2. Establece LOCATION en us.

El resto de cada solicitud permanece igual. Para obtener información sobre cómo elegir la multirregión de tu suscripción, consulta Obtén una suscripción. Para obtener la lista de extremos de servicio regionales y multirregionales, consulta Extremos de servicio regionales y multirregionales en la guía de la nube privada virtual.

Cómo agregar fuentes de datos en un lote

Para agregar fuentes a un cuaderno, llama al método 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
    }
   ]
  }'

Reemplaza lo siguiente:

  • ENDPOINT_LOCATION: Es la multirregión para tu solicitud a la API. Especifica uno de los siguientes valores:
    • us para la multirregión de EE.UU.
    • eu para la multirregión de la UE
    • global para la ubicación global
    Para obtener más información, consulta Cómo especificar una multirregión para tu almacén de datos.
  • PROJECT_NUMBER: Es el número de tu proyecto de Google Cloud .
  • LOCATION: la ubicación geográfica de tu almacén de datos, como global. Para obtener más información, consulta Ubicaciones.
  • NOTEBOOK_ID: Es el identificador único del notebook.
  • USER_CONTENT: Es el contenido de la fuente de datos.

Solo puedes agregar una de las siguientes fuentes de datos como contenido:

  • Para el contenido de Google Drive que consiste en Documentos de Google o Presentaciones de Google, agrega lo siguiente:

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

    Reemplaza lo siguiente:

    • DOCUMENT_ID_GOOGLE: Es el ID del archivo que se encuentra en Google Drive. Este ID aparece en la URL del archivo. Para obtener el ID de un archivo, ábrelo. Su URL tiene el siguiente patrón: https://docs.google.com/FILE_TYPE/d/DOCUMENT_ID_GOOGLE/edit?resourcekey=RESOURCE_KEY.
    • MIME_TYPE: Es el tipo de MIME del documento seleccionado. Usa application/vnd.google-apps.document para Documentos de Google o application/vnd.google-apps.presentation para Presentaciones de Google.
    • DISPLAY_NAME_GOOGLE: Es el nombre visible de la fuente de datos.

  • Para la entrada de texto sin procesar, agrega lo siguiente:

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

    Reemplaza lo siguiente:

    • DISPLAY_NAME_TEXT: Es el nombre visible de la fuente de datos.
    • TEXT_CONTENT: Es el contenido de texto sin procesar que deseas subir como fuente de datos.

  • Para el contenido web, agrega lo siguiente:

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

    Reemplaza lo siguiente:

    • URL_WEBCONTENT: Es la URL del contenido que deseas subir como fuente de datos.
    • DISPLAY_NAME_WEB: Es el nombre visible de la fuente de datos.

  • En el caso del contenido de video, agrega lo siguiente:

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

    Reemplaza URL_YOUTUBE por la URL del video de YouTube que deseas subir como fuente de datos.

Si la solicitud se realiza correctamente, deberías obtener una instancia del objeto source como respuesta, similar al siguiente JSON. Toma nota de los valores de SOURCE_ID y SOURCE_RESOURCE_NAME, que son necesarios para realizar otras tareas, como recuperar o borrar la fuente de datos.

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

Cómo subir un archivo como fuente

Además de agregar fuentes de datos en lotes, puedes subir archivos individuales que se pueden usar como fuentes de datos en tu cuaderno. Para subir un solo archivo, llama al método 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" \

Reemplaza lo siguiente:

  • PATH/TO/FILE: Es la ruta de acceso al archivo que deseas subir.
  • FILE_DISPLAY_NAME: Es una cadena que indica el nombre visible del archivo en el notebook.
  • CONTENT_TYPE: Es el tipo de contenido que deseas subir. Para obtener una lista de los tipos de contenido admitidos, consulta Tipos de contenido admitidos.
  • ENDPOINT_LOCATION: Es la multirregión para tu solicitud a la API. Especifica uno de los siguientes valores:
    • us para la multirregión de EE.UU.
    • eu para la multirregión de la UE
    • global para la ubicación global
    Para obtener más información, consulta Cómo especificar una multirregión para tu almacén de datos.
  • PROJECT_NUMBER: Es el número de tu proyecto de Google Cloud .
  • LOCATION: la ubicación geográfica de tu almacén de datos, como global. Para obtener más información, consulta Ubicaciones.
  • NOTEBOOK_ID: Es el identificador único del notebook.

Si la solicitud se realiza correctamente, deberías recibir una respuesta JSON similar a la siguiente.

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

Tipos de contenido admitidos

El archivo que subas como fuente debe ser compatible.

Se admiten los siguientes tipos de contenido de documentos:

Extensión de archivo Tipo de contenido
.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

Se admiten los siguientes tipos de contenido de audio:

Extensión de archivo Tipo de contenido
.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

Se admiten los siguientes tipos de contenido de imagen:

Extensión de archivo Tipo de contenido
.png image/png
.jpg image/jpg
.jpeg image/jpeg

Recupera una fuente

Para recuperar una fuente específica que se agregó a un notebook, usa el método 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"

Reemplaza lo siguiente:

  • ENDPOINT_LOCATION: Es la multirregión para tu solicitud a la API. Especifica uno de los siguientes valores:
    • us para la multirregión de EE.UU.
    • eu para la multirregión de la UE
    • global para la ubicación global
    Para obtener más información, consulta Cómo especificar una multirregión para tu almacén de datos.
  • PROJECT_NUMBER: Es el número de tu proyecto de Google Cloud .
  • LOCATION: la ubicación geográfica de tu almacén de datos, como global. Para obtener más información, consulta Ubicaciones.
  • NOTEBOOK_ID: Es el identificador único que recibiste cuando creaste el notebook. Para obtener más información, consulta Crea un notebook.
  • SOURCE_ID: Es el identificador de la fuente que recibiste cuando la agregaste a tu cuaderno.

Si la solicitud se realiza correctamente, deberías recibir una respuesta JSON similar a la siguiente.

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

    }
  ]
}

Borrar fuentes de datos de un cuaderno

Para borrar fuentes de datos de forma masiva desde un notebook, usa el método 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"
      ]
    }'

Reemplaza lo siguiente:

  • ENDPOINT_LOCATION: Es la multirregión para tu solicitud a la API. Especifica uno de los siguientes valores:
    • us para la multirregión de EE.UU.
    • eu para la multirregión de la UE
    • global para la ubicación global
    Para obtener más información, consulta Cómo especificar una multirregión para tu almacén de datos.
  • PROJECT_NUMBER: Es el número de tu proyecto de Google Cloud .
  • LOCATION: la ubicación geográfica de tu almacén de datos, como global. Para obtener más información, consulta Ubicaciones.
  • NOTEBOOK_ID: Es el identificador único del notebook.
  • SOURCE_RESOURCE_NAME: Es el nombre completo del recurso de la fuente de datos que se borrará. Este campo tiene el siguiente patrón: projects/PROJECT_NUMBER/locations/LOCATION/notebooks/NOTEBOOK_ID/source/SOURCE_ID.

Si la solicitud se realiza correctamente, deberías recibir un objeto JSON vacío.

¿Qué sigue?