Docuents

REST 資源：corpora.documents

資源：Document

Document 是 Chunk 的集合。Corpus 最多可以有 10,000 個 Document。

JSON 表示法 
{
  "name": string,
  "displayName": string,
  "customMetadata": [
    {
      object (CustomMetadata)
    }
  ],
  "updateTime": string,
  "createTime": string
}
欄位
name string

不可變動。ID。Document 資源名稱。ID (名稱不含「corpora/*/documents/」前置字元) 最多可包含 40 個小寫英數字元或破折號 (-)。ID 的開頭或結尾不得為破折號。如果建立時未指定名稱，系統會從 displayName 衍生專屬名稱，加上 12 個字元的隨機後置字串。範例：corpora/{corpus_id}/documents/my-awesome-doc-123a456b789c

displayName string

選用設定。使用者可理解的 Document 顯示名稱。顯示名稱長度不得超過 512 個字元 (包含空格)。例如：「語意擷取說明文件」

customMetadata[] object (CustomMetadata)

選用設定。使用者提供的自訂中繼資料 (儲存為查詢用的鍵/值組合)Document 最多可以有 20 個 CustomMetadata。

updateTime string (Timestamp format)

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

RFC3339 世界標準時間「Zulu」的時間戳記格式，解析度為奈秒，且最多 9 個小數位數。範例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。

createTime string (Timestamp format)

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

RFC3339 世界標準時間「Zulu」的時間戳記格式，解析度為奈秒，且最多 9 個小數位數。範例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。

方法：corpora.documents.create

可建立空白的 Document。

端點

則貼文 https://generativelanguage.googleapis.com/v1beta/{parent=corpora/*}/documents 。

路徑參數

parent string

必要欄位。要建立這個 Document 的 Corpus 名稱。範例：corpora/my-corpus-123 的格式為 corpora/{corpora}。

要求主體

要求主體包含 Document 的例項。

回應主體

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

方法：corpora.documents.list

列出 Corpus 中的所有 Document。

端點

取得 https://generativelanguage.googleapis.com/v1beta/{parent=corpora/*}/documents 。

路徑參數

parent string

必要欄位。包含 Document 的 Corpus 名稱。範例：corpora/my-corpus-123 的格式為 corpora/{corpora}。

查詢參數

pageSize integer

選用設定。可傳回的 Document 數量上限 (每頁)。服務傳回的 Document 數量可能會減少。

如未指定，最多會傳回 10 個 Document。每頁的大小上限為 20 Document 秒。

pageToken string

選用設定。屬於接收自前一個 documents.list 呼叫的網頁權杖。

提供回應中傳回的 nextPageToken 做為引數，以便擷取下一個網頁。

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

要求主體

要求主體必須為空白。

回應主體

來自 documents.list 的回應，其中包含 Document 的分頁清單。Document 是依 document.create_time 遞增排序。

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

欄位
documents[] object (Document)

傳回的 Document。

nextPageToken string

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

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

方法：corpora.documents.query

對 Document 執行語意搜尋。

端點

則貼文 https://generativelanguage.googleapis.com/v1beta/{name=corpora/*/documents/*}:query 。

路徑參數

name string

必要欄位。要查詢的 Document 名稱。範例：corpora/my-corpus-123/documents/the-doc-abc 的格式為 corpora/{corpora}/documents/{document}。

要求主體

要求主體的資料會採用以下結構：

欄位
query string

必要欄位。用於執行語意搜尋的查詢字串。

resultsCount integer

選用設定。要傳回的 Chunk 數量上限。服務傳回的 Chunk 數量可能會減少。

如未指定，最多會傳回 10 個 Chunk。指定的結果數上限是 100。

metadataFilters[] object (MetadataFilter)

選用設定。篩選 Chunk 的中繼資料。每個 MetadataFilter 物件都應對應至不重複的索引鍵。多個 MetadataFilter 物件會以邏輯「AND」連結。

注意：您已指定 Document 名稱，因此這項要求不支援Document層級篩選功能。

查詢範例：(年份 >= 2020 OR 年份 < 2010) AND (類型 = 戲劇 OR 類型 = 動作)

MetadataFilter 物件清單：metadataFilters = [ {key = "chunk.custom_metadata.year"條件 = [{int_value = 2020，Operation = GREATER_EQUAL}, {int_value = 2010, operations = LESS}}, {key = "chunk.custom_metadata.category"條件 = [{stringValue = "drama",Operation = EQUAL}, {stringValue = "action", operations = EQUAL}}]

針對數值範圍的查詢範例：(年份 > 2015，且年份 <= 2020)

MetadataFilter 物件清單：metadataFilters = [ {key = "chunk.custom_metadata.year"conditions = [{int_value = 2015, operation = GREATER}]}, {key = &quot;chunk.custom_metadata.year&quot;條件 = [{int_value = 2020，Operation = LESS_EQUAL}]}

注意：相同鍵的「AND」僅支援數值，針對相同鍵，字串值僅支援「OR」。

回應主體

來自 documents.query 的回應，其中包含相關區塊清單。

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

欄位
relevantChunks[] object (RelevantChunk)

傳回的相關區塊。

JSON 表示法 
{
  "relevantChunks": [
    {
      object (RelevantChunk)
    }
  ]
}

方法：corpora.documents.get

取得特定 Document 的資訊。

端點

取得 https://generativelanguage.googleapis.com/v1beta/{name=corpora/*/documents/*} 。

路徑參數

name string

必要欄位。要擷取的 Document 名稱。範例：corpora/my-corpus-123/documents/the-doc-abc 的格式為 corpora/{corpora}/documents/{document}。

要求主體

要求主體必須為空白。

回應主體

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

方法：corpora.documents.patch

更新 Document。

端點

修補程式 https://generativelanguage.googleapis.com/v1beta/{document.name=corpora/*/documents/*} 。

PATCH https://generativelanguage.googleapis.com/v1beta/{document.name=corpora/*/documents/*}

路徑參數

document.name string

不可變動。ID。Document 資源名稱。ID (名稱不含「corpora/*/documents/」前置字元) 最多可包含 40 個小寫英數字元或破折號 (-)。ID 的開頭或結尾不得為破折號。如果建立時未指定名稱，系統會從 displayName 衍生專屬名稱，加上 12 個字元的隨機後置字串。範例：corpora/{corpus_id}/documents/my-awesome-doc-123a456b789c 的格式為 corpora/{corpora}/documents/{document}。

查詢參數

updateMask string (FieldMask format)

必要欄位。要更新的欄位清單。目前僅支援更新 displayName 和 customMetadata。

這是以半形逗號分隔的完整欄位名稱清單。範例："user.displayName,photo"。

要求主體

要求主體包含 Document 的例項。

回應主體

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

方法：corpora.documents.delete

刪除 Document。

端點

刪除 https://generativelanguage.googleapis.com/v1beta/{name=corpora/*/documents/*} 。

路徑參數

name string

必要欄位。要刪除的 Document 資源名稱。範例：corpora/my-corpus-123/documents/the-doc-abc 的格式為 corpora/{corpora}/documents/{document}。

查詢參數

force boolean

選用設定。如果設為 true，與這個 Document 相關的所有 Chunk 和物件也會一併刪除。

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

要求主體

要求主體必須為空白。

回應主體

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

CustomMetadata

使用者提供的中繼資料是以鍵/值組合的形式儲存。

JSON 表示法 
{
  "key": string,

  // Union field value can be only one of the following:
  "stringValue": string,
  "stringListValue": {
    object (StringList)
  },
  "numericValue": number
  // End of list of possible types for union field value.
}
欄位
key string

必要欄位。要儲存的中繼資料鍵。

聯集欄位 value。

value 只能採用下列其中一種設定：

stringValue string

要儲存的中繼資料字串值。

stringListValue object (StringList)

要儲存的中繼資料的 StringList 值。

numericValue number

要儲存的中繼資料的數值。

StringList

使用者提供的字串值會指派給單一中繼資料鍵。

JSON 表示法 
{
  "values": [
    string
  ]
}
欄位
values[] string

要儲存的中繼資料字串值。