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 類型。如未提供，系統會從上傳的內容推斷。

回應主體

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

Fields
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 排序。

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

Fields
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 呼叫所造成的長時間執行作業。

Fields
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 呼叫所造成的長時間執行作業。

Fields
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 的集合。

Fields
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
}