Creare e gestire notebook (API)

Gemini Notebook Enterprise è un potente strumento per generare insight generati e riepiloghi dai tuoi documenti. Questa pagina descrive le API che ti consentono di eseguire le seguenti attività di gestione dei notebook in modo programmatico:

Prima di iniziare

Prima di iniziare a lavorare con i notebook, segui questi passaggi:

Utilizza l'endpoint multiregionale Stati Uniti

Se il tuo abbonamento a Gemini Notebook Enterprise si trova nella multi-regione degli Stati Uniti, puoi inviare le richieste in questa pagina all'endpoint multi-regionale degli 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 della richiesta rimangano negli Stati Uniti mentre sono in transito. L'utilizzo di questo endpoint non modifica la posizione di archiviazione dei 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 della tua sottoscrizione, consulta Crea una sottoscrizione. Per l'elenco degli endpoint di servizio regionali e multiregionali, consulta Endpoint di servizio regionali e multiregionali nella guida di Virtual Private Cloud.

Crea un notebook

Per creare un nuovo notebook, utilizza il metodo notebooks.create.

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" \
  -d '{
  "title": "NOTEBOOK_TITLE",
  }'

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_TITLE: una stringa con codifica UTF-8 utilizzata come titolo per il notebook che vuoi creare.

Se la richiesta va a buon fine, dovresti ricevere un JSON simile al seguente.

{
"title": "NOTEBOOK_TITLE",
"notebookId": "NOTEBOOK_ID",
"emoji": "",
"metadata": {
  "userRole": "PROJECT_ROLE_OWNER",
  "isShared": false,
  "isShareable": true
},
"name": "NOTEBOOK_NAME"
}

Tieni presente quanto segue:

  • NOTEBOOK_ID: un ID univoco per identificare il notebook creato. L'ID del notebook è necessario per altre attività di gestione del notebook, come la condivisione o il recupero.
  • NOTEBOOK_NAME: il nome completo della risorsa del notebook. Questo campo ha il seguente pattern: projects/PROJECT_NUMBER/locations/LOCATION/notebooks/NOTEBOOK_ID

Accedi al notebook creato e ottieni il suo ID in un browser

Per accedere al notebook creato e ottenere il relativo ID utilizzando un browser, segui questi passaggi.

  1. Vai alla home page di Gemini Notebook Enterprise disponibile in uno dei seguenti URL:

    1. Se utilizzi un'identità Google, vai a:

      https://notebook.cloud.google.com/LOCATION/?project=PROJECT_NUMBER
      
    2. Se utilizzi un'identità di terze parti, vai a:

      https://notebook.cloud.google/LOCATION/?project=PROJECT_NUMBER
      
  2. Seleziona il notebook creato. L'URL del notebook selezionato ha il seguente pattern:

    1. Se utilizzi un'identità Google:

      https://notebook.cloud.google.com/LOCATION/notebook/NOTEBOOK_ID?project=PROJECT_NUMBER
      
    2. Se utilizzi un'identità di terze parti:

      https://notebook.cloud.google/LOCATION/notebook/NOTEBOOK_ID?project=PROJECT_NUMBER
      
  3. Prendi nota dell'URL e dell'ID del notebook, che sono utili per altre attività di gestione dei notebook, come la condivisione.

Recupera un notebook

Per recuperare un notebook specifico utilizzando il relativo ID, utilizza il metodo notebooks.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"

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 che hai ricevuto quando hai creato il notebook.

Se la richiesta ha esito positivo, dovresti ricevere una risposta JSON simile alla seguente per un blocco note vuoto. Se chiami questo metodo dopo aver aggiunto fonti al tuo notebook, riceverai i dettagli su tutte le fonti aggiunte al notebook recuperato. Se hai configurato i dettagli CMEK, riceverai anche informazioni relative a CMEK per il notebook.

{
"title": "NOTEBOOK_TITLE",
"notebookId": "NOTEBOOK_ID",
"emoji": "",
"metadata": {
  "userRole": "PROJECT_ROLE_OWNER",
  "isShared": false,
  "isShareable": true,
  "lastViewed": "LAST_VIEWED_TIME",
  "createTime": "LAST_CREATED_TIME"
},
"name": "NOTEBOOK_NAME"
}

Elenca i notebook visualizzati di recente

Per ottenere un elenco di tutti i notebook di un progetto visualizzati di recente, utilizza il metodo notebooks.listRecentlyViewed. Per impostazione predefinita, la risposta elenca gli ultimi 500 notebook. Puoi scegliere di impaginare le risposte con il parametro di query pageSize.

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:listRecentlyViewed"

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à.

Se la richiesta ha esito positivo, dovresti ricevere una risposta JSON simile alla seguente. La risposta contiene fino agli ultimi 500 notebook a cui un utente ha eseguito l'accesso di recente.

{
  "notebooks": [
    {
      "title": "NOTEBOOK_TITLE_1",
      "notebookId": "NOTEBOOK_ID_1",
      "emoji": "",
      "metadata": {
        "userRole": "PROJECT_ROLE_OWNER",
        "isShared": false,
        "isShareable": true,
        "lastViewed": "LAST_VIEWED_TIME",
        "createTime": "LAST_CREATED_TIME"
      },
      "name": "NOTEBOOK_NAME_1"
    },
    {
      "title": "NOTEBOOK_TITLE_2",
      "notebookId": "NOTEBOOK_ID_2",
      "emoji": "",
      "metadata": {
        "userRole": "PROJECT_ROLE_OWNER",
        "isShared": false,
        "isShareable": true,
        "lastViewed": "LAST_VIEWED_TIME",
        "createTime": "LAST_CREATED_TIME"
      },
      "name": "NOTEBOOK_NAME_2"
    }
  ]
}

Elimina un notebook

Per eliminare un notebook, utilizza il metodo notebooks.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:batchDelete" \
  -d '{
    "names": [
      "NOTEBOOK_NAME"
    ]
  }'

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_NAME: il nome completo della risorsa del notebook da eliminare. Questo campo ha il pattern: projects/PROJECT_NUMBER/locations/LOCATION/notebooks/NOTEBOOK_ID.

    Se la richiesta va a buon fine, ricevi un oggetto JSON vuoto. Se il notebook non esiste, riceverai anche un oggetto JSON vuoto, quindi assicurati di specificare correttamente il nome del notebook.

Condividi un notebook

Per condividere un nuovo notebook, utilizza il metodo notebooks.share.

All'utente con cui vuoi condividere il notebook deve essere concesso il ruolo Cloud NotebookLM User.

REST

  1. Nel tuo progetto Google Cloud , assegna il ruolo IAM (Identity and Access Management) Cloud NotebookLM User agli utenti con cui vuoi condividere il notebook.

  2. Chiama il seguente metodo.

    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:share" \
      -d '{
        "accountAndRoles": [
         {
            "email":"USER_EMAIL_1",
            "role":"USER_ROLE_1",
         },
         {
            "email":"USER_EMAIL_2",
            "role":"USER_ROLE_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: un ID univoco per identificare il notebook che vuoi condividere. L'ID del notebook è necessario per altre attività di gestione del notebook, come la condivisione o il recupero.
    • USER_EMAIL: l'indirizzo email dell'utente con cui vuoi condividere il notebook.
    • USER_ROLE: un ruolo che vuoi assegnare all'utente. Può essere uno dei seguenti:

      • PROJECT_ROLE_WRITER: l'utente dispone delle autorizzazioni in scrittura per il progetto.
      • PROJECT_ROLE_READER: l'utente dispone delle autorizzazioni in lettura per il progetto.
      • PROJECT_ROLE_NOT_SHARED:l'utente non ha accesso al progetto.

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

Verifica gli utenti utilizzando un browser

Per verificare se hai condiviso il notebook con gli utenti corretti e se hai assegnato loro i ruoli corretti, segui questi passaggi:

  1. Apri il notebook nel browser. Un notebook ha il seguente pattern URL:

    1. Se utilizzi un'identità Google:

      https://notebook.cloud.google.com/LOCATION/notebook/NOTEBOOK_ID?project=PROJECT_NUMBER
      
    2. Se utilizzi un'identità di terze parti:

      https://notebook.cloud.google/LOCATION/notebook/NOTEBOOK_ID?project=PROJECT_NUMBER
      
  2. Fai clic su Condividi.

  3. Verifica gli utenti elencati in Persone con accesso e i ruoli assegnati.

Passaggi successivi