File Search Stores

L'API File Search fornisce un servizio di risposta alle domande ospitato per la creazione di sistemi di Retrieval-Augmented Generation (RAG) utilizzando l'infrastruttura di Google.

Metodo: media.uploadToFileSearchStore

Carica i dati in un FileSearchStore, li preelabora e li suddivide in blocchi prima di archiviarli in un documento FileSearchStore.

Endpoint

  • URI di caricamento, per le richieste di caricamento dei contenuti multimediali:
 post https://generativelanguage.googleapis.com/upload/v1beta/{fileSearchStoreName=fileSearchStores/*}:uploadToFileSearchStore
  • URI dei metadati, per le richieste solo di metadati:
 post https://generativelanguage.googleapis.com/v1beta/{fileSearchStoreName=fileSearchStores/*}:uploadToFileSearchStore

Parametri del percorso

fileSearchStoreName string

Obbligatorio. Immutabile. Il nome del FileSearchStore in cui caricare il file. Esempio: fileSearchStores/my-file-search-store-123 Assume la forma fileSearchStores/{filesearchstore}.

Corpo della richiesta

Il corpo della richiesta contiene dati con la seguente struttura:

Campi
displayName string

Facoltativo. Il nome visualizzato del documento creato.

customMetadata[] object (CustomMetadata)

Metadati personalizzati da associare ai dati.

chunkingConfig object (ChunkingConfig)

Facoltativo. Configurazione per indicare al servizio come segmentare i dati. Se non vengono forniti, il servizio utilizzerà i parametri predefiniti.

mimeType string

Facoltativo. Tipo MIME dei dati. Se non viene fornito, verrà dedotto dai contenuti caricati.

Corpo della risposta

Questa è una copia di google.longrunning.Operation. Dobbiamo copiarlo perché per interagire con Scotty dobbiamo aggiungere un campo specifico di Scotty che non può essere aggiunto nel proto dell'operazione di primo livello.

In caso di esito positivo, il corpo della risposta contiene dati con la seguente struttura:

Campi
name string

Il nome assegnato dal server, che è univoco solo all'interno dello stesso servizio che lo restituisce originariamente. Se utilizzi la mappatura HTTP predefinita, name deve essere un nome di risorsa che termina con operations/{unique_id}.

metadata object

Metadati specifici del servizio associati all'operazione. In genere contengono informazioni sullo stato di avanzamento e metadati comuni come l'ora di creazione. Alcuni servizi potrebbero non fornire questi metadati. Qualsiasi metodo che restituisce un'operazione a lunga esecuzione deve documentare il tipo di metadati, se presenti.

Un oggetto contenente campi di un tipo arbitrario. Un campo aggiuntivo "@type" contiene un URI che identifica il tipo. Esempio: { "id": 1234, "@type": "types.example.com/standard/id" }

done boolean

Se il valore è false, significa che l'operazione è ancora in corso. Se true, l'operazione viene completata e sono disponibili error o response.

result Union type
Il risultato dell'operazione, che può essere un error o una response valida. Se done == false, né error né response vengono impostati. Se done == true, è possibile impostare esattamente uno dei valori error o response. Alcuni servizi potrebbero non fornire il risultato. result può essere solo uno dei seguenti:
error object (Status)

Il risultato di errore dell'operazione in caso di errore o annullamento.

response object

La risposta normale e con esito positivo dell'operazione. Se il metodo originale non restituisce dati in caso di esito positivo, ad esempio Delete, la risposta è google.protobuf.Empty. Se il metodo originale è Get/Create/Update standard, la risposta deve essere la risorsa. Per gli altri metodi, la risposta deve avere il tipo XxxResponse, dove Xxx è il nome del metodo originale. Ad esempio, se il nome del metodo originale è TakeSnapshot(), il tipo di risposta dedotto è TakeSnapshotResponse.

Un oggetto contenente campi di un tipo arbitrario. Un campo aggiuntivo "@type" contiene un URI che identifica il tipo. Esempio: { "id": 1234, "@type": "types.example.com/standard/id" }

Rappresentazione JSON 
{
  "name": string,
  "metadata": {
    "@type": string,
    field1: ...,
    ...
  },
  "done": boolean,

  // result
  "error": {
    object (Status)
  },
  "response": {
    "@type": string,
    field1: ...,
    ...
  }
  // Union type
}

Metodo: fileSearchStores.create

Crea un FileSearchStore vuoto.

Endpoint

post https://generativelanguage.googleapis.com/v1beta/fileSearchStores

Corpo della richiesta

Il corpo della richiesta contiene un'istanza di FileSearchStore.

Campi
displayName string

Facoltativo. Il nome visualizzato leggibile per FileSearchStore. Il nome visualizzato non deve contenere più di 512 caratteri, spazi inclusi. Esempio: "Documenti su Semantic Retriever"

Corpo della risposta

In caso di esito positivo, il corpo della risposta contiene un'istanza appena creata di FileSearchStore.

Metodo: fileSearchStores.delete

Elimina un FileSearchStore.

Endpoint

delete https://generativelanguage.googleapis.com/v1beta/{name=fileSearchStores/*}

Parametri del percorso

name string

Obbligatorio. Il nome della risorsa di FileSearchStore. Esempio: fileSearchStores/my-file-search-store-123 Assume la forma fileSearchStores/{filesearchstore}.

Parametri di query

force boolean

Facoltativo. Se è impostata su true, verranno eliminati anche tutti gli Document e gli oggetti correlati a questo FileSearchStore.

Se è false (impostazione predefinita), verrà restituito un errore FAILED_PRECONDITION se FileSearchStore contiene Document.

Corpo della richiesta

Il corpo della richiesta deve essere vuoto.

Corpo della risposta

In caso di esito positivo, il corpo della risposta è un oggetto JSON vuoto.

Metodo: fileSearchStores.get

Recupera informazioni su un FileSearchStore specifico.

Endpoint

get https://generativelanguage.googleapis.com/v1beta/{name=fileSearchStores/*}

Parametri del percorso

name string

Obbligatorio. Il nome del FileSearchStore. Esempio: fileSearchStores/my-file-search-store-123 Assume la forma fileSearchStores/{filesearchstore}.

Corpo della richiesta

Il corpo della richiesta deve essere vuoto.

Corpo della risposta

In caso di esito positivo, il corpo della risposta contiene un'istanza di FileSearchStore.

Metodo: fileSearchStores.list

Elenca tutti i FileSearchStores di proprietà dell'utente.

Endpoint

get https://generativelanguage.googleapis.com/v1beta/fileSearchStores

Parametri di query

pageSize integer

Facoltativo. Il numero massimo di FileSearchStores da restituire (per pagina). Il servizio potrebbe restituire meno FileSearchStores.

Se non specificato, verranno restituiti al massimo 10 FileSearchStores. Il limite massimo di dimensioni è di 20 FileSearchStores per pagina.

pageToken string

Facoltativo. Un token di pagina ricevuto da una precedente chiamata fileSearchStores.list.

Fornisci il valore nextPageToken restituito nella risposta come argomento della richiesta successiva per recuperare la pagina successiva.

Durante la paginazione, tutti gli altri parametri forniti a fileSearchStores.list devono corrispondere alla chiamata che ha fornito il token di pagina.

Corpo della richiesta

Il corpo della richiesta deve essere vuoto.

Corpo della risposta

Risposta da fileSearchStores.list contenente un elenco paginato di FileSearchStores. I risultati sono ordinati in base al valore crescente di fileSearchStore.create_time.

In caso di esito positivo, il corpo della risposta contiene dati con la seguente struttura:

Campi
fileSearchStores[] object (FileSearchStore)

ragStores restituito.

nextPageToken string

Un token, che può essere inviato come pageToken per recuperare la pagina successiva. Se questo campo viene omesso, non verranno visualizzate altre pagine.

Rappresentazione JSON 
{
  "fileSearchStores": [
    {
      object (FileSearchStore)
    }
  ],
  "nextPageToken": string
}

Metodo: fileSearchStores.importFile

Importa un File dal servizio file in un FileSearchStore.

Endpoint

post https://generativelanguage.googleapis.com/v1beta/{fileSearchStoreName=fileSearchStores/*}:importFile

Parametri del percorso

fileSearchStoreName string

Obbligatorio. Immutabile. Il nome del FileSearchStore in cui importare il file. Esempio: fileSearchStores/my-file-search-store-123 Assume la forma fileSearchStores/{filesearchstore}.

Corpo della richiesta

Il corpo della richiesta contiene dati con la seguente struttura:

Campi
fileName string

Obbligatorio. Il nome del File da importare. Esempio: files/abc-123

customMetadata[] object (CustomMetadata)

Metadati personalizzati da associare al file.

chunkingConfig object (ChunkingConfig)

Facoltativo. Configurazione per indicare al servizio come segmentare il file. Se non vengono forniti, il servizio utilizzerà i parametri predefiniti.

Corpo della risposta

In caso di esito positivo, il corpo della risposta contiene un'istanza di Operation.

Risorsa REST: fileSearchStores.operations

Risorsa: Operation

Questa risorsa rappresenta un'operazione a lunga esecuzione che è il risultato di una chiamata API di rete.

Campi
name string

Il nome assegnato dal server, che è univoco solo all'interno dello stesso servizio che lo restituisce originariamente. Se utilizzi la mappatura HTTP predefinita, name deve essere un nome di risorsa che termina con operations/{unique_id}.

metadata object

Metadati specifici del servizio associati all'operazione. In genere contengono informazioni sullo stato di avanzamento e metadati comuni come l'ora di creazione. Alcuni servizi potrebbero non fornire questi metadati. Qualsiasi metodo che restituisce un'operazione a lunga esecuzione deve documentare il tipo di metadati, se presenti.

Un oggetto contenente campi di un tipo arbitrario. Un campo aggiuntivo "@type" contiene un URI che identifica il tipo. Esempio: { "id": 1234, "@type": "types.example.com/standard/id" }

done boolean

Se il valore è false, significa che l'operazione è ancora in corso. Se true, l'operazione viene completata e sono disponibili error o response.

result Union type
Il risultato dell'operazione, che può essere un error o una response valida. Se done == false, né error né response vengono impostati. Se done == true, è possibile impostare esattamente uno dei valori error o response. Alcuni servizi potrebbero non fornire il risultato. result può essere solo uno dei seguenti:
error object (Status)

Il risultato di errore dell'operazione in caso di errore o annullamento.

response object

La risposta normale e con esito positivo dell'operazione. Se il metodo originale non restituisce dati in caso di esito positivo, ad esempio Delete, la risposta è google.protobuf.Empty. Se il metodo originale è Get/Create/Update standard, la risposta deve essere la risorsa. Per gli altri metodi, la risposta deve avere il tipo XxxResponse, dove Xxx è il nome del metodo originale. Ad esempio, se il nome del metodo originale è TakeSnapshot(), il tipo di risposta dedotto è TakeSnapshotResponse.

Un oggetto contenente campi di un tipo arbitrario. Un campo aggiuntivo "@type" contiene un URI che identifica il tipo. Esempio: { "id": 1234, "@type": "types.example.com/standard/id" }

Rappresentazione JSON 
{
  "name": string,
  "metadata": {
    "@type": string,
    field1: ...,
    ...
  },
  "done": boolean,

  // result
  "error": {
    object (Status)
  },
  "response": {
    "@type": string,
    field1: ...,
    ...
  }
  // Union type
}

Metodo: fileSearchStores.operations.get

Recupera lo stato più recente di un'operazione a lunga esecuzione. I client possono utilizzare questo metodo per eseguire il polling del risultato dell'operazione a intervalli come consigliato dal servizio API.

Endpoint

get https://generativelanguage.googleapis.com/v1beta/{name=fileSearchStores/*/operations/*}

Parametri del percorso

name string

Il nome della risorsa dell'operazione. Assume la forma fileSearchStores/{filesearchstore}/operations/{operation}.

Corpo della richiesta

Il corpo della richiesta deve essere vuoto.

Corpo della risposta

In caso di esito positivo, il corpo della risposta contiene un'istanza di Operation.

Risorsa REST: fileSearchStores.upload.operations

Risorsa: Operation

Questa risorsa rappresenta un'operazione a lunga esecuzione che è il risultato di una chiamata API di rete.

Campi
name string

Il nome assegnato dal server, che è univoco solo all'interno dello stesso servizio che lo restituisce originariamente. Se utilizzi la mappatura HTTP predefinita, name deve essere un nome di risorsa che termina con operations/{unique_id}.

metadata object

Metadati specifici del servizio associati all'operazione. In genere contengono informazioni sullo stato di avanzamento e metadati comuni come l'ora di creazione. Alcuni servizi potrebbero non fornire questi metadati. Qualsiasi metodo che restituisce un'operazione a lunga esecuzione deve documentare il tipo di metadati, se presenti.

Un oggetto contenente campi di un tipo arbitrario. Un campo aggiuntivo "@type" contiene un URI che identifica il tipo. Esempio: { "id": 1234, "@type": "types.example.com/standard/id" }

done boolean

Se il valore è false, significa che l'operazione è ancora in corso. Se true, l'operazione viene completata e sono disponibili error o response.

result Union type
Il risultato dell'operazione, che può essere un error o una response valida. Se done == false, né error né response vengono impostati. Se done == true, è possibile impostare esattamente uno dei valori error o response. Alcuni servizi potrebbero non fornire il risultato. result può essere solo uno dei seguenti:
error object (Status)

Il risultato di errore dell'operazione in caso di errore o annullamento.

response object

La risposta normale e con esito positivo dell'operazione. Se il metodo originale non restituisce dati in caso di esito positivo, ad esempio Delete, la risposta è google.protobuf.Empty. Se il metodo originale è Get/Create/Update standard, la risposta deve essere la risorsa. Per gli altri metodi, la risposta deve avere il tipo XxxResponse, dove Xxx è il nome del metodo originale. Ad esempio, se il nome del metodo originale è TakeSnapshot(), il tipo di risposta dedotto è TakeSnapshotResponse.

Un oggetto contenente campi di un tipo arbitrario. Un campo aggiuntivo "@type" contiene un URI che identifica il tipo. Esempio: { "id": 1234, "@type": "types.example.com/standard/id" }

Rappresentazione JSON 
{
  "name": string,
  "metadata": {
    "@type": string,
    field1: ...,
    ...
  },
  "done": boolean,

  // result
  "error": {
    object (Status)
  },
  "response": {
    "@type": string,
    field1: ...,
    ...
  }
  // Union type
}

Metodo: fileSearchStores.upload.operations.get

Recupera lo stato più recente di un'operazione a lunga esecuzione. I client possono utilizzare questo metodo per eseguire il polling del risultato dell'operazione a intervalli come consigliato dal servizio API.

Endpoint

get https://generativelanguage.googleapis.com/v1beta/{name=fileSearchStores/*/upload/operations/*}

Parametri del percorso

name string

Il nome della risorsa dell'operazione. Assume la forma fileSearchStores/{filesearchstore}/upload/operations/{operation}.

Corpo della richiesta

Il corpo della richiesta deve essere vuoto.

Corpo della risposta

In caso di esito positivo, il corpo della risposta contiene un'istanza di Operation.

Risorsa REST: fileSearchStores

Risorsa: FileSearchStore

Un FileSearchStore è una raccolta di Document.

Campi
name string

Solo output. Immutabile. Identificatore. Il nome della risorsa FileSearchStore. È un ID (nome escluso il prefisso "fileSearchStores/") che può contenere fino a 40 caratteri alfanumerici minuscoli o trattini (-). È solo output. Il nome univoco verrà derivato da displayName insieme a un suffisso casuale di 12 caratteri. Esempio: fileSearchStores/my-awesome-file-search-store-123a456b789c Se displayName non viene fornito, il nome verrà generato in modo casuale.

displayName string

Facoltativo. Il nome visualizzato leggibile per FileSearchStore. Il nome visualizzato non deve contenere più di 512 caratteri, spazi inclusi. Esempio: "Documenti su Semantic Retriever"

createTime string (Timestamp format)

Solo output. Il timestamp della creazione di FileSearchStore.

Utilizza RFC 3339, in cui l'output generato è sempre normalizzato in base al fuso orario UTC e utilizza 0, 3, 6 o 9 cifre frazionarie. Sono accettati anche offset diversi da "Z". Esempi: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" o "2014-10-02T15:01:23+05:30".

updateTime string (Timestamp format)

Solo output. Il timestamp dell'ultimo aggiornamento di FileSearchStore.

Utilizza RFC 3339, in cui l'output generato è sempre normalizzato in base al fuso orario UTC e utilizza 0, 3, 6 o 9 cifre frazionarie. Sono accettati anche offset diversi da "Z". Esempi: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" o "2014-10-02T15:01:23+05:30".

activeDocumentsCount string (int64 format)

Solo output. Il numero di documenti nel FileSearchStore attivi e pronti per il recupero.

pendingDocumentsCount string (int64 format)

Solo output. Il numero di documenti in FileSearchStore in fase di elaborazione.

failedDocumentsCount string (int64 format)

Solo output. Il numero di documenti in FileSearchStore la cui elaborazione non è riuscita.

sizeBytes string (int64 format)

Solo output. Le dimensioni dei byte non elaborati inseriti in FileSearchStore. Si tratta della dimensione totale di tutti i documenti nel FileSearchStore.

Rappresentazione JSON 
{
  "name": string,
  "displayName": string,
  "createTime": string,
  "updateTime": string,
  "activeDocumentsCount": string,
  "pendingDocumentsCount": string,
  "failedDocumentsCount": string,
  "sizeBytes": string
}