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 formato, 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 ello, ejecuta el siguiente gcloud auth login comando y sigue las instrucciones de la CLI.

gcloud auth login --enable-gdrive-access

Agregar fuentes de datos en lote

Para agregar fuentes a un cuaderno, llama al notebooks.sources.batchCreate método.

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 región múltiple 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 región múltiple para tu almacén de datos.
  • PROJECT_NUMBER: Es el número de tu Google Cloud proyecto.
  • LOCATION: Es 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 cuaderno.
  • 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 consta de 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 documento 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 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 formato, 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 formato 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.

  • Para el 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 source objeto como respuesta, similar al siguiente JSON. Ten en cuenta el SOURCE_ID y el 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"
    }
  ]
}

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 cuaderno.
  • 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 región múltiple 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 región múltiple para tu almacén de datos.
  • PROJECT_NUMBER: Es el número de tu Google Cloud proyecto.
  • LOCATION: Es 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 cuaderno.

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

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

Tipos de contenido admitidos

El archivo que subes 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

Recuperar una fuente

Para recuperar una fuente específica que se agregó a un cuaderno, usa el notebooks.sources.get método.

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 región múltiple 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 región múltiple para tu almacén de datos.
  • PROJECT_NUMBER: Es el número de tu Google Cloud proyecto.
  • LOCATION: Es 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 cuaderno. Para obtener más información, consulta Cómo crear un cuaderno.
  • SOURCE_ID: Es el identificador de la fuente que recibiste cuando la agregaste a tu cuaderno.

Si la solicitud se realiza correctamente, deberías obtener 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 de un cuaderno, usa el notebooks.sources.batchDelete método.

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 región múltiple 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 región múltiple para tu almacén de datos.
  • PROJECT_NUMBER: Es el número de tu Google Cloud proyecto.
  • LOCATION: Es 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 cuaderno.
  • 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?