File Search Stores

File Search API 提供代管問答服務，可使用 Google 的基礎架構建構檢索增強生成 (RAG) 系統。

方法：media.uploadToFileSearchStore

將資料上傳至 FileSearchStore，並在預先處理和分塊後，儲存在 FileSearchStore 文件中。

端點

  • 上傳 URI，適用於媒體上傳要求：
 post https://generativelanguage.googleapis.com/upload/v1beta/{fileSearchStoreName=fileSearchStores/*}:uploadToFileSearchStore
  • 中繼資料 URI，適用於僅限中繼資料的要求：
 post https://generativelanguage.googleapis.com/v1beta/{fileSearchStoreName=fileSearchStores/*}:uploadToFileSearchStore

路徑參數

fileSearchStoreName string

必要欄位。不可變更。要上傳檔案的 FileSearchStore 名稱。範例：fileSearchStores/my-file-search-store-123 採用 fileSearchStores/{filesearchstore} 形式。

要求主體

要求主體會包含結構如下的資料：

欄位
displayName string

(選用步驟) 所建立文件的顯示名稱。

customMetadata[] object (CustomMetadata)

要與資料建立關聯的自訂中繼資料。

chunkingConfig object (ChunkingConfig)

(選用步驟) 設定，用於告知服務如何將資料分塊。如未提供，服務會使用預設參數。

mimeType string

(選用步驟) 資料的 MIME 類型。如未提供，系統會從上傳的內容推斷。

回應主體

這是 google.longrunning.Operation 的副本。我們需要複製這個欄位，因為與 Scotty 互動時，必須新增 Scotty 專屬欄位，但無法在頂層的 Operation proto 中新增。

如果成功，回應主體會含有以下結構的資料：

欄位
name string

伺服器指派的名稱，而且只在當初傳回這個名稱的服務中是唯一的。如果您使用預設的 HTTP 對應，則 name 應該是以 operations/{unique_id} 結尾的資源名稱。

metadata object

服務專屬，且與該作業相關聯的中繼資料，通常包含進度資訊和常用中繼資料 (例如建立時間)。部分服務可能不會提供這類中繼資料。凡是會傳回長時間執行作業的方法，都應記錄中繼資料類型 (如果有的話)。

包含任意類型欄位的物件。額外的 "@type" 欄位則包含能辨識類型的 URI。例如：{ "id": 1234, "@type": "types.example.com/standard/id" }。

done boolean

如果值為 false，代表作業仍在執行中。如果值為 true，代表作業已執行完畢，系統會顯示 error 或 response 的執行結果。

result Union type
這是作業的執行結果，可能為 error，或是有效的 response。如果 done == false，系統不會將結果設定為 error，也不會設定為 response。如果 done == true，系統只能將結果設定為 error 或 response 其中之一。部分服務可能不會提供結果。result 只能是下列其中一項：
error object (Status)

作業執行失敗或遭到取消時，所顯示的錯誤結果。

response object

作業執行成功時的一般回應。如果原始方法在執行成功時沒有傳回資料 (例如 Delete)，則回應為 google.protobuf.Empty。如果原始方法是標準的 Get/Create/Update，回應則應該為資源。如果是其他方法，回應必須包含類型 XxxResponse，其中 Xxx 是原始方法的名稱。舉例來說，如果原始方法的名稱為 TakeSnapshot()，您就能推測出回應類型應該是 TakeSnapshotResponse。

包含任意類型欄位的物件。額外的 "@type" 欄位則包含能辨識類型的 URI。範例：{ "id": 1234, "@type": "types.example.com/standard/id" }。

JSON 表示法 
{
  "name": string,
  "metadata": {
    "@type": string,
    field1: ...,
    ...
  },
  "done": boolean,

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

方法：fileSearchStores.create

建立空白的 FileSearchStore。

端點

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

要求主體

要求主體包含 FileSearchStore 的例項。

欄位
displayName string

(選用步驟) FileSearchStore 的使用者可讀顯示名稱。顯示名稱長度不得超過 512 個半形字元 (包括空格)。範例：「Docs on Semantic Retriever」(有關語意擷取器的文件)

回應主體

如果成功，回應主體會包含新建立的 FileSearchStore 例項。

方法：fileSearchStores.delete

刪除 FileSearchStore。

端點

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

路徑參數

name string

必要欄位。FileSearchStore 的資源名稱。範例：fileSearchStores/my-file-search-store-123 採用 fileSearchStores/{filesearchstore} 形式。

查詢參數

force boolean

(選用步驟) 如果設為 true，系統也會刪除與這個 FileSearchStore 相關的任何 Document 和物件。

如果為 false (預設值)，且 FileSearchStore 包含任何 Document，系統就會傳回 FAILED_PRECONDITION 錯誤。

要求主體

要求主體必須為空白。

回應主體

如果成功，回應主體會是空白的 JSON 物件。

方法：fileSearchStores.get

取得特定 FileSearchStore 的相關資訊。

端點

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

路徑參數

name string

必要欄位。FileSearchStore 的名稱。範例：fileSearchStores/my-file-search-store-123 採用 fileSearchStores/{filesearchstore} 形式。

要求主體

要求主體必須為空白。

回應主體

如果成功，回應主體會包含 FileSearchStore 的執行例項。

方法：fileSearchStores.list

列出使用者擁有的所有 FileSearchStores。

端點

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

查詢參數

pageSize integer

(選用步驟) 要傳回的 FileSearchStores 數量上限 (每頁)。服務傳回的 FileSearchStores 數量可能會少於這個值。

如未指定，最多將傳回 10 個 FileSearchStores。每頁最多可顯示 20 FileSearchStores。

pageToken string

(選用步驟) 屬於接收自前一個 fileSearchStores.list 呼叫的網頁權杖。

將回應中傳回的 nextPageToken 做為下一個要求的引數，即可擷取下一頁。

進行分頁時，提供至 fileSearchStores.list 的所有其他參數須與提供網頁權杖的呼叫相符。

要求主體

要求主體必須為空白。

回應主體

來自 fileSearchStores.list 的回應，內含分頁的 FileSearchStores 清單。結果會按遞增順序排序 fileSearchStore.create_time。

如果成功，回應主體會含有以下結構的資料：

欄位
fileSearchStores[] object (FileSearchStore)

傳回的 ragStores。

nextPageToken string

可做為 pageToken 傳送的權杖，用於擷取後續網頁。如果省略這個欄位，就不會有後續頁面。

JSON 表示法 
{
  "fileSearchStores": [
    {
      object (FileSearchStore)
    }
  ],
  "nextPageToken": string
}

方法：fileSearchStores.importFile

將檔案服務中的 File 匯入 FileSearchStore。

端點

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

路徑參數

fileSearchStoreName string

必要欄位。不可變更。要匯入檔案的 FileSearchStore 名稱。範例：fileSearchStores/my-file-search-store-123 採用 fileSearchStores/{filesearchstore} 形式。

要求主體

要求主體會包含結構如下的資料：

欄位
fileName string

必要欄位。要匯入的 File 名稱。範例：files/abc-123

customMetadata[] object (CustomMetadata)

要與檔案建立關聯的自訂中繼資料。

chunkingConfig object (ChunkingConfig)

(選用步驟) 設定，用於告知服務如何將檔案分塊。如未提供，服務會使用預設參數。

回應主體

如果成功，回應主體會包含 Operation 的執行例項。

REST 資源：fileSearchStores.operations

資源：Operation

這個資源代表某個網路 API 呼叫所造成的長時間執行作業。

欄位
name string

伺服器指派的名稱，而且只在當初傳回這個名稱的服務中是唯一的。如果您使用預設的 HTTP 對應，則 name 應該是以 operations/{unique_id} 結尾的資源名稱。

metadata object

服務專屬，且與該作業相關聯的中繼資料，通常包含進度資訊和常用中繼資料 (例如建立時間)。部分服務可能不會提供這類中繼資料。凡是會傳回長時間執行作業的方法，都應記錄中繼資料類型 (如果有的話)。

包含任意類型欄位的物件。額外的 "@type" 欄位則包含能辨識類型的 URI。例如：{ "id": 1234, "@type": "types.example.com/standard/id" }。

done boolean

如果值為 false，代表作業仍在執行中。如果值為 true，代表作業已執行完畢，系統會顯示 error 或 response 的執行結果。

result Union type
這是作業的執行結果，可能為 error，或是有效的 response。如果 done == false，系統不會將結果設定為 error，也不會設定為 response。如果 done == true，系統只能將結果設定為 error 或 response 其中之一。部分服務可能不會提供結果。result 只能是下列其中一項：
error object (Status)

作業執行失敗或遭到取消時，所顯示的錯誤結果。

response object

作業執行成功時的一般回應。如果原始方法在執行成功時沒有傳回資料 (例如 Delete)，則回應為 google.protobuf.Empty。如果原始方法是標準的 Get/Create/Update，回應則應該為資源。如果是其他方法，回應必須包含類型 XxxResponse，其中 Xxx 是原始方法的名稱。舉例來說，如果原始方法的名稱為 TakeSnapshot()，您就能推測出回應類型應該是 TakeSnapshotResponse。

包含任意類型欄位的物件。額外的 "@type" 欄位則包含能辨識類型的 URI。範例：{ "id": 1234, "@type": "types.example.com/standard/id" }。

JSON 表示法 
{
  "name": string,
  "metadata": {
    "@type": string,
    field1: ...,
    ...
  },
  "done": boolean,

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

方法：fileSearchStores.operations.get

取得長時間執行作業的最新狀態。用戶端可以使用這個方法按照 API 服務建議的間隔查詢作業結果。

端點

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

路徑參數

name string

作業資源名稱。格式為 fileSearchStores/{filesearchstore}/operations/{operation}。

要求主體

要求主體必須為空白。

回應主體

如果成功，回應主體會包含 Operation 的執行例項。

REST 資源：fileSearchStores.upload.operations

資源：Operation

這個資源代表某個網路 API 呼叫所造成的長時間執行作業。

欄位
name string

伺服器指派的名稱，而且只在當初傳回這個名稱的服務中是唯一的。如果您使用預設的 HTTP 對應，則 name 應該是以 operations/{unique_id} 結尾的資源名稱。

metadata object

服務專屬，且與該作業相關聯的中繼資料，通常包含進度資訊和常用中繼資料 (例如建立時間)。部分服務可能不會提供這類中繼資料。凡是會傳回長時間執行作業的方法，都應記錄中繼資料類型 (如果有的話)。

包含任意類型欄位的物件。額外的 "@type" 欄位則包含能辨識類型的 URI。例如：{ "id": 1234, "@type": "types.example.com/standard/id" }。

done boolean

如果值為 false，代表作業仍在執行中。如果值為 true，代表作業已執行完畢，系統會顯示 error 或 response 的執行結果。

result Union type
這是作業的執行結果，可能為 error，或是有效的 response。如果 done == false，系統不會將結果設定為 error，也不會設定為 response。如果 done == true，系統只能將結果設定為 error 或 response 其中之一。部分服務可能不會提供結果。result 只能是下列其中一項：
error object (Status)

作業執行失敗或遭到取消時，所顯示的錯誤結果。

response object

作業執行成功時的一般回應。如果原始方法在執行成功時沒有傳回資料 (例如 Delete)，則回應為 google.protobuf.Empty。如果原始方法是標準的 Get/Create/Update，回應則應該為資源。如果是其他方法，回應必須包含類型 XxxResponse，其中 Xxx 是原始方法的名稱。舉例來說，如果原始方法的名稱為 TakeSnapshot()，您就能推測出回應類型應該是 TakeSnapshotResponse。

包含任意類型欄位的物件。額外的 "@type" 欄位則包含能辨識類型的 URI。範例：{ "id": 1234, "@type": "types.example.com/standard/id" }。

JSON 表示法 
{
  "name": string,
  "metadata": {
    "@type": string,
    field1: ...,
    ...
  },
  "done": boolean,

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

方法：fileSearchStores.upload.operations.get

取得長時間執行作業的最新狀態。用戶端可以使用這個方法按照 API 服務建議的間隔查詢作業結果。

端點

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

路徑參數

name string

作業資源名稱。格式為 fileSearchStores/{filesearchstore}/upload/operations/{operation}。

要求主體

要求主體必須為空白。

回應主體

如果成功，回應主體會包含 Operation 的執行例項。

REST 資源：fileSearchStores

資源：FileSearchStore

FileSearchStore 是 Document 的集合。

欄位
name string

僅供輸出。不可變更。ID。FileSearchStore 資源名稱。這是 ID (名稱不含「fileSearchStores/」前置字串)，最多可包含 40 個半形字元，且只能是小寫英數字元或破折號 (-)。這個 ID 僅供輸出。專屬名稱會衍生自 displayName，並加上 12 個字元的隨機後置字串。範例：fileSearchStores/my-awesome-file-search-store-123a456b789c 如果未提供 displayName，系統會隨機產生名稱。

displayName string

(選用步驟) FileSearchStore 的使用者可讀顯示名稱。顯示名稱長度不得超過 512 個半形字元 (包括空格)。範例：「Docs on Semantic Retriever」(有關語意擷取器的文件)

createTime string (Timestamp format)

僅供輸出。FileSearchStore 的建立時間戳記。

使用 RFC 3339，產生的輸出內容一律會經過 Z 標準化，並使用 0、3、6 或 9 個小數點後位數。系統也接受「Z」以外的偏移量。例如："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。

updateTime string (Timestamp format)

僅供輸出。上次更新 FileSearchStore 的時間戳記。

使用 RFC 3339，產生的輸出內容一律會經過 Z 標準化，並使用 0、3、6 或 9 個小數點後位數。系統也接受「Z」以外的偏移量。例如："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。

activeDocumentsCount string (int64 format)

僅供輸出。FileSearchStore 中可供擷取的有效文件數量。

pendingDocumentsCount string (int64 format)

僅供輸出。正在處理的 FileSearchStore 文件數量。

failedDocumentsCount string (int64 format)

僅供輸出。無法處理的 FileSearchStore 文件數量。

sizeBytes string (int64 format)

僅供輸出。擷取到 FileSearchStore 的原始位元組大小。這是 FileSearchStore 中所有文件的總大小。

JSON 表示法 
{
  "name": string,
  "displayName": string,
  "createTime": string,
  "updateTime": string,
  "activeDocumentsCount": string,
  "pendingDocumentsCount": string,
  "failedDocumentsCount": string,
  "sizeBytes": string
}