Aggiungere e gestire origini dati in un notebook (API)

Dopo aver creato il notebook, puoi aggiungere vari tipi di contenuti come origini dati. Puoi farlo in batch o come singoli file. Alcune delle fonti includono Documenti Google, Presentazioni Google, testo non elaborato, contenuti web e video di YouTube.

Questa pagina descrive come eseguire le seguenti attività:

Prima di iniziare

Se prevedi di aggiungere Documenti Google o Presentazioni Google come origine dati, devi autorizzare l'accesso a Google Drive utilizzando le credenziali utente di Google. Per farlo, esegui il seguente comando gcloud auth login e segui le istruzioni nell'interfaccia a riga di comando.

gcloud auth login --enable-gdrive-access

Utilizza l'endpoint multiregionale Stati Uniti

Se il tuo abbonamento a Gemini Notebook Enterprise si trova nella multi-regione Stati Uniti, puoi inviare le richieste in questa pagina all'endpoint multi-regionale Stati Uniti, discoveryengine.us.rep.googleapis.com. Un endpoint multiregionale elabora le tue richieste e termina TLS all'interno della multi-regione, in modo che i dati delle richieste rimangano negli Stati Uniti mentre sono in transito. L'utilizzo di questo endpoint non modifica la posizione in cui sono archiviati i tuoi notebook. Per saperne di più, consulta la panoramica degli endpoint API regionali e multiregionali nella guida alla sicurezza di Google Cloud.

Per utilizzare l'endpoint multiregionale degli Stati Uniti, apporta le seguenti modifiche a ogni URL di richiesta in questa pagina:

  1. Sostituisci l'host ENDPOINT_LOCATION-discoveryengine.googleapis.com con discoveryengine.us.rep.googleapis.com.

  2. Imposta LOCATION su us.

Il resto di ogni richiesta rimane invariato. Per scoprire come scegliere la località multiregionale dell'abbonamento, consulta Ottieni un abbonamento. Per l'elenco degli endpoint di servizio regionali e multiregionali, consulta Endpoint di servizio regionali e multiregionali nella guida di Virtual Private Cloud.

Aggiungi origini dati in un batch

Per aggiungere fonti a un notebook, chiama il metodo 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
    }
   ]
  }'

Sostituisci quanto segue:

  • ENDPOINT_LOCATION: la località multiregionale per la richiesta API. Specifica uno dei seguenti valori:
    • us per la multi-regione Stati Uniti
    • eu per la multi-regione UE
    • global per la località globale
    Per saperne di più, consulta Specifica una multi-regione per il datastore.
  • PROJECT_NUMBER: il numero del tuo progetto Google Cloud .
  • LOCATION: la posizione geografica del datastore, ad esempio global. Per saperne di più, consulta Località.
  • NOTEBOOK_ID: l'identificatore univoco del notebook.
  • USER_CONTENT: i contenuti dell'origine dati.

Puoi aggiungere solo una delle seguenti origini dati come contenuto:

  • Per i contenuti di Google Drive costituiti da Documenti Google o Presentazioni Google, aggiungi:

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

    Sostituisci quanto segue:

    • DOCUMENT_ID_GOOGLE: l'ID del file che si trova su Google Drive. Questo ID viene visualizzato nell'URL del file. Per ottenere l'ID documento di un file, apri il file. Il suo URL ha il pattern: https://docs.google.com/FILE_TYPE/d/DOCUMENT_ID_GOOGLE/edit?resourcekey=RESOURCE_KEY.
    • MIME_TYPE: il tipo MIME del documento selezionato. Utilizza application/vnd.google-apps.document per Documenti Google o application/vnd.google-apps.presentation per Presentazioni Google.
    • DISPLAY_NAME_GOOGLE: il nome visualizzato dell'origine dati.

  • Per l'input di testo non elaborato, aggiungi:

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

    Sostituisci quanto segue:

    • DISPLAY_NAME_TEXT: il nome visualizzato dell'origine dati.
    • TEXT_CONTENT: i contenuti di testo non elaborati che vuoi caricare come origine dati.

  • Per i contenuti web, aggiungi:

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

    Sostituisci quanto segue:

    • URL_WEBCONTENT: l'URL dei contenuti che vuoi caricare come origine dati.
    • DISPLAY_NAME_WEB: il nome visualizzato dell'origine dati.

  • Per i contenuti video, aggiungi:

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

    Sostituisci URL_YOUTUBE con l'URL del video di YouTube che vuoi caricare come origine dati.

Se la richiesta ha esito positivo, dovresti ricevere un'istanza dell'oggetto source come risposta, simile al seguente JSON. Prendi nota di SOURCE_ID e SOURCE_RESOURCE_NAME, che sono necessari per eseguire altre attività, come il recupero o l'eliminazione dell'origine dati.

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

Carica un file come fonte

Oltre ad aggiungere origini dati in batch, puoi caricare singoli file che possono essere utilizzati come origini dati nel tuo notebook. Per caricare un singolo file, chiama il metodo 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" \

Sostituisci quanto segue:

  • PATH/TO/FILE: il percorso del file che vuoi caricare.
  • FILE_DISPLAY_NAME: una stringa che indica il nome visualizzato del file nel notebook.
  • CONTENT_TYPE: il tipo di contenuti che vuoi caricare. Per un elenco dei tipi di contenuti supportati, consulta Tipi di contenuti supportati.
  • ENDPOINT_LOCATION: la località multiregionale per la richiesta API. Specifica uno dei seguenti valori:
    • us per la multi-regione Stati Uniti
    • eu per la multi-regione UE
    • global per la località globale
    Per saperne di più, consulta Specifica una multi-regione per il datastore.
  • PROJECT_NUMBER: il numero del tuo progetto Google Cloud .
  • LOCATION: la posizione geografica del datastore, ad esempio global. Per saperne di più, consulta Località.
  • NOTEBOOK_ID: l'identificatore univoco del notebook.

Se la richiesta ha esito positivo, dovresti ricevere una risposta JSON simile alla seguente.

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

Tipi di contenuti supportati

Il file che carichi come fonte deve essere supportato.

Sono supportati i seguenti tipi di contenuti dei documenti:

File extension (Estensione del file) Tipo di contenuti
.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

Sono supportati i seguenti tipi di contenuti audio:

File extension (Estensione del file) Tipo di contenuti
.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

Sono supportati i seguenti tipi di contenuti immagine:

File extension (Estensione del file) Tipo di contenuti
.png image/png
.jpg image/jpg
.jpeg image/jpeg

Recupera una fonte

Per recuperare una fonte specifica aggiunta a un notebook, utilizza il metodo 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"

Sostituisci quanto segue:

  • ENDPOINT_LOCATION: la località multiregionale per la richiesta API. Specifica uno dei seguenti valori:
    • us per la multi-regione Stati Uniti
    • eu per la multi-regione UE
    • global per la località globale
    Per saperne di più, consulta Specifica una multi-regione per il datastore.
  • PROJECT_NUMBER: il numero del tuo progetto Google Cloud .
  • LOCATION: la posizione geografica del datastore, ad esempio global. Per saperne di più, consulta Località.
  • NOTEBOOK_ID: l'identificatore univoco che hai ricevuto quando hai creato il notebook. Per saperne di più, consulta Crea un blocco note.
  • SOURCE_ID: l'identificatore della fonte che hai ricevuto quando l'hai aggiunta al notebook.

Se la richiesta ha esito positivo, dovresti ricevere una risposta JSON simile alla seguente.

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

    }
  ]
}

Elimina le origini dati da un notebook

Per eliminare collettivamente le origini dati da un blocco note, utilizza il metodo 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"
      ]
    }'

Sostituisci quanto segue:

  • ENDPOINT_LOCATION: la località multiregionale per la richiesta API. Specifica uno dei seguenti valori:
    • us per la multi-regione Stati Uniti
    • eu per la multi-regione UE
    • global per la località globale
    Per saperne di più, consulta Specifica una multi-regione per il datastore.
  • PROJECT_NUMBER: il numero del tuo progetto Google Cloud .
  • LOCATION: la posizione geografica del datastore, ad esempio global. Per saperne di più, consulta Località.
  • NOTEBOOK_ID: l'identificatore univoco del notebook.
  • SOURCE_RESOURCE_NAME: il nome completo della risorsa dell'origine dati da eliminare. Questo campo ha il pattern: projects/PROJECT_NUMBER/locations/LOCATION/notebooks/NOTEBOOK_ID/source/SOURCE_ID.

Se la richiesta va a buon fine, dovresti ricevere un oggetto JSON vuoto.

Passaggi successivi