Google 提供的設定參數

每個連接器都有相關聯的設定檔,其中包含連接器使用的參數,例如存放區的 ID。參數會定義為「鍵/值」組合,例如 api.sourceId=1234567890abcdef

Google Cloud Search SDK 包含由不同連接器使用的數個 Google 設定參數。在 Google 提供的設定參數中,只需要在設定檔中定義「資料來源存取權」參數,您不需要在設定檔中重新定義 Google 提供的參數,「除非」要覆寫這些參數的預設值。

本參考資料說明 Google 提供的設定參數。

設定檔範例

以下範例顯示具有參數鍵/值組合的身分設定檔。

#
# Configuration file sample
#
api.sourceId=1234567890abcdef
api.identitySourceId=0987654321lmnopq
api.serviceAccountPrivateKeyFile= ./PrivateKey.json

#
# Traversal schedules
#
schedule.traversalIntervalSecs=7200
schedule.incrementalTraversalIntervalSecs=600
#
# Default ACLs
#
defaultAcl.mode=fallback
defaultAcl.public=true
  

常用的參數

本節列出必要和選用的常用設定參數。如果未變更選用參數的值,連接器會使用 SDK 提供的預設值。

資料來源存取權

下表列出在設定檔中顯示的所有參數。您使用的參數取決於您建立的連接器類型 (內容連接器或識別資訊連接器)。

擺設 參數
資料來源 ID api.sourceId=1234567890abcdef

連接器需要這個參數,才能識別存放區位置。在搜尋中加入資料來源後,即可取得這個值。這個參數必須位於連接器設定檔中。

識別資訊來源 ID api.identitySourceId=0987654321lmnopq

識別資訊連接器需要這個參數,才能識別外部識別資訊來源的位置。您在在 Cloud Search 中對應使用者身分時,已經取得了這個值。這個參數必須放在所有識別資訊連接器設定檔中。

服務帳戶私密金鑰檔案 api.serviceAccountPrivateKeyFile=./PrivateKey.json

這個參數包含存取存放區所需的私密金鑰。您在設定 Google Cloud Search REST API 存取權時已經取得此值。這個參數必須放在所有設定檔中。

服務帳戶 ID api.serviceAccountId=123abcdef4567890

這個參數會指定服務帳戶 ID。只有在設定檔指定私密金鑰檔案參數時,才能使用預設空白字串值。如果您的私密金鑰檔案不是 JSON 金鑰,就必須提供這個參數。

Google Workspace 帳戶 ID api.customerId=123abcdef4567890

這個參數可指定企業 Google Workspace 帳戶的帳戶 ID。您在在 Cloud Search 中對應使用者身分時,已經取得了這個值。透過識別資訊連接器同步處理使用者時,必須提供這個參數。

根網址 api.rootUrl=baseURLPath

這個參數會指定索引服務基準網址路徑。

這個參數的預設值是空白字串,會轉換為 https://cloudsearch.googleapis.com

週遊排程

排程參數會決定連接器在周遊之間的等待頻率。

擺設 參數
在連接器啟動時完整週遊 schedule.performTraversalOnStart=true|false

連接器會在連接器啟動時執行完整週遊,而不會等待第一個間隔到期。預設值為 true.

在間隔後完整週遊 schedule.traversalIntervalSecs=intervalInSeconds

連接器會在指定的時間間隔後執行完整週遊。指定週遊之間的間隔時間 (以秒為單位)。預設值為 86400 (一天的秒數)。

一次週遊後離開 connector.runOnce=true|false

連接器會完整週遊一次,然後結束。只有在您使用完整週遊策略時,這個參數才應設為 true。清單和圖表策略需要多個週遊,才能偵測變更和索引內容。預設值為 false,且不要在一次週遊後結束。

在間隔後週遊增量 schedule.incrementalTraversalIntervalSecs=intervalInSeconds

連接器會在指定間隔後執行漸進式週遊。指定週遊之間的間隔時間 (以秒為單位)。預設值為 300 (5 分鐘的秒數)。

排定的意見調查佇列間隔 schedule.pollQueueIntervalSecs=interval_in_seconds

排定的意見調查佇列時間間隔 (以秒為單位)。只會用於列出週遊連接器。預設值為 10.

存取控制清單 (ACL)

連接器會使用 ACL 來控制項目的存取權。您可以運用多個參數,透過 ACL 保護使用者存取已建立索引記錄的權限。

如果您的存放區有與各個項目相關聯的個別 ACL 資訊,請上傳所有 ACL 資訊,以控制 Cloud Search 中的項目存取權。如果存放區提供部分 ACL 資訊,或是完全沒有 ACL 資訊,您可以在 SDK 下列參數中提供預設 ACL 資訊,以供 SDK 提供給連接器。

擺設 參數
ACL 模式 defaultAcl.mode=mode

決定套用預設 ACL 的時機。有效值:

  • none:不使用預設 ACL (在這個模式中,除非您定義個別 ACL,否則無法搜尋記錄)
  • fallback:只在沒有 ACL 時使用預設 ACL
  • append:將預設 ACL 新增至現有的 ACL
  • override:將現有的 ACL 替換成預設 ACL

預設模式為 none

預設公開 ACL defaultAcl.public=true|false

整個存放區的預設 ACL 已設為公開網域存取權。預設值為 false.

常見的 ACL 群組讀取者 defaultAcl.readers.groups=google:group1@mydomain.com, group2
常見的 ACL 讀取者 defaultAcl.readers.users=user1, user2, google:user3@mydomain.com
常見的 ACL 拒絕群組讀取者 defaultAcl.denied.groups=group3
常見的 Acl 拒絕讀取者 defaultAcl.denied.users=user4, user5
整個網域存取權 如要指定網域中的所有使用者都能公開存取所有已建立索引的記錄,請使用下列值設定下列兩個參數:
  • defaultAcl.mode=override
  • defaultACL.public=true
一般定義的 ACL 如要為資料存放區的每筆記錄指定一個 ACL,請設定下列所有參數值:
  • defaultAcl.mode=fallback
  • defaultAcl.public=false
  • defaultAcl.readers.groups=google:group1@mydomain.com, group2 code>
  • defaultAcl.readers.users=user1@mydomain.com, user2, google:user3@mydomain.com
  • defaultAcl.denied.groups=group3
  • defaultAcl.denied.users=user4, user5

    除非加上「google:」(常值常數),否則系統會將每個指定的使用者和群組都視為當地網域定義的使用者/群組。

    預設的使用者或群組是空白字串。只有在 defaultAcl.public 設為 false 時,才提供使用者和群組參數。如要列出多個群組和使用者,請使用以逗號分隔的清單。

    如果將 defaultAcl.mode 設為 none,只要未定義個別 ACL,就無法搜尋記錄。

中繼資料設定參數

部分作品中繼資料可設定。連接器可以在建立索引時設定可設定的中繼資料欄位。如果連接器未設定欄位,系統會使用設定檔中的參數來設定欄位。

設定檔包含一系列以 .field 後置字串表示的具名中繼資料設定參數,例如 itemMetadata.title.field=movieTitle。如果這些參數有值,就會用於設定中繼資料欄位。如果沒有命名中繼資料參數的值,系統會使用含有 .defaultValue 後置字串的參數設定中繼資料。

下表為中繼資料設定參數。

設定 參數
標題 itemMetadata.title.field=movieTitle
itemMetadata.title.defaultValue=Gone with the Wind
商品名稱。如未設定 title.field 值,系統會使用 title.defaultValue 的值。
來源存放區網址 itemMetadata.sourceRepositoryUrl.field=url
itemMetadata.sourceRepositoryUrl.defaultValue=https://www.imdb.com/title/tt0031381/
搜尋結果中使用的項目網址。您只需要設定 defaultValue,以保留整個存放區的網址,例如您的部署作業為 CSV 檔案,且每個項目只有一個網址。如果 sourceRepositoryUrl.field 未設定值,系統會使用 sourceRepositoryUrl.defaultValue 的值。
容器名稱 itemMetadata.containerName.field=containerName
itemMetadata.containerName.defaultValue=myDefaultContainerName
項目的容器名稱,例如檔案系統目錄或資料夾的名稱。如未設定 containerName.field 值,系統會使用 containerName.defaultValue 的值。
物件類型 itemMetadata.objectType.field=type
itemMetadata.objectType.defaultValue=movie
連接器使用的物件類型,如結構定義所定義。如未指定這個屬性,連接器就不會為任何結構化資料建立索引。
如未設定 objectType.field 值,系統會使用 objectType.defaultValue 的值。
建立時間 itemMetadata.createTime.field=releaseDate
itemMetadata.createTime.defaultValue=1940-01-17
文件建立時間戳記。如未設定 createTime.field 值,系統會使用 createTime.defaultValue 的值。
更新時間 itemMetadata.updateTime.field=releaseDate
itemMetadata.updateTime.defaultValue=1940-01-17
商品上次修改時間戳記。如未設定 updateTime.field 值,系統會使用 updateTime.defaultValue 的值。
內容語言 itemMetadata.contentLanguage.field=languageCode
itemMetadata.contentLanguage.defaultValue=en-US
已建立索引文件的內容語言。如未設定 contentLanguage.field 值,系統會使用 contentLanguage.defaultValue 的值。
Mime 類型 itemMetadata.mimeType.field=mimeType
itemMetadata.mimeType.defaultValue=image/bmp
來源存放區中 ItemContent.content 的原始 MIME 類型。長度上限為 256 個半形字元。如未設定 mimeType.field 值,系統會使用 mimeType.defaultValue 的值。
搜尋品質中繼資料 itemMetadata.searchQualityMetadata.quality.field=quality
itemMetadata.searchQualityMetadata.quality.defaultValue=1
指出商品品質的標示,用於影響搜尋品質。值應介於 0.0 (最低品質) 到 1.0 (最高品質) 之間。預設值為 0.0。如未設定 quality.field 值,系統會使用 quality.defaultValue 的值。
雜湊 itemMetadata.hash.field=hash
itemMetadata.hash.defaultValue=f0fda58630310a6dd91a7d8f0a4ceda2
API 呼叫端提供的雜湊值。這可與 items.push 方法搭配使用,計算修改後的狀態。長度上限為 2,048 個字元。如未設定 hash.field 值,系統會使用 hash.defaultValue 的值。

日期時間格式

日期時間格式會指定中繼資料屬性應採用的格式。如果設定檔不包含這個參數,系統會使用預設值。下表顯示了此參數。

設定 參數
其他日期時間格式 structuredData.dateTimePatterns=MM/dd/uuuu HH:mm:ssXXX
以半形分號分隔的其他 java.time.format.DateTimeFormatter 模式清單。這些模式用於剖析中繼資料或結構定義中任何日期或日期時間欄位的字串值。預設值為空白清單,但系統一律支援 RFC 3339 和 RFC 1123 格式。

結構化資料

Cloud Search Indexing API 提供的結構定義服務可讓您自訂 Cloud Search 索引與提供資料的方式。如果您使用的是本機存放區結構定義,則必須指定結構化資料本機結構定義名稱。

擺設 參數
本機結構定義名稱 structuredData.localSchema=mySchemaName

結構定義名稱會從資料來源讀取資料,並用於存放區結構化資料。

預設值為空字串。

內容和搜尋品質

如果存放區含有記錄或欄位型內容 (例如 CRM、CVS 或資料庫),SDK 允許自動為資料欄位設定 HTML 格式。連接器會在連接器執行開始時定義資料欄位,然後使用內容範本設定每筆資料記錄的格式,然後再將記錄上傳至 Cloud Search。

內容範本定義了每個欄位值搜尋的重要性。HTML <title> 為必要欄位,且定義為最高優先順序。您可以為所有其他內容欄位指定搜尋品質等級等級:高、中或低。凡是未在特定類別中定義的內容欄位,都會預設為低優先順序。

擺設 參數
內容 HTML 標題 contentTemplate.templateName.title=myTitleField

內容 HTML 標題和最高的搜尋品質欄位。只有在您使用的是 HTML 內容範本時,才需要這個參數。預設值為空字串。

內容欄位的高品質搜尋品質 contentTemplate.templateName.quality.high=hField1,hField2

搜尋優先順序較高的內容欄位。預設值為空字串。

內容欄位的搜尋品質中等 contentTemplate.templateName.quality.medium=mField1,mField2

指定中等搜尋優先順序的內容欄位。預設值為空字串。

內容欄位的搜尋品質不佳 contentTemplate.templateName.quality.low=lField1,lField2

搜尋優先順序較低的內容欄位。預設值為空字串。

未指定的內容欄位 contentTemplate.templateName.unmappedColumnsMode=value

連接器如何處理未指定的內容欄位。有效的值包括:

  • APPEND:將未指定的內容欄位附加至範本
  • IGNORE:忽略未指定的內容欄位

    預設值為 APPEND

在 HTML 範本中加入欄位名稱 contentTemplate.templateName.includeFieldName=true|false

指定是否要在 HTML 範本中一併加入欄位名稱與欄位資料。預設值為 true,會讓使用者搜尋欄位名稱做為內容資料的一部分。

不常見的參數設定

其實不太需要設定這個部分列出的參數。參數的預設值是設定最佳效能。如果存放區沒有特定要求,Google 不建議將這些參數設為與預設值不同的值。

Proxy 配置

SDK 可讓您將連接器設定為使用 Proxy 處理傳出連線。

需要 transport.proxy.hostnametransport.proxy.port 參數才可透過 Proxy 進行傳輸。如果您的 Proxy 需要驗證,或是透過 SOCKS 通訊協定 (而非 HTTP) 運作,則可能需要其他參數。如未設定 transport.proxy.hostname,SDK 就不會使用 Proxy。

擺設 參數
主機名稱 transport.proxy.hostname=hostname

Proxy 伺服器的主機名稱。使用 Proxy 時必須提供這個參數。

通訊埠 transport.proxy.port=port

Proxy 伺服器的通訊埠編號。使用 Proxy 時必須提供這個參數。

Proxy 類型 transport.proxy.type=type

Proxy 的類型。有效的值包括:

  • HTTP:Proxy 會透過 HTTP 接受及轉送要求。
  • SOCKS:Proxy 會透過 SOCKS 通訊協定接受及轉送封包。

預設值為 HTTP

使用者名稱 transport.proxy.username=username

建構 Proxy 授權權杖時使用的使用者名稱。這是選用參數,只有在您的 Proxy 需要驗證時才需要設定。

密碼 transport.proxy.password=password

建構 Proxy 授權權杖時使用的密碼,這是選用參數,只有在您的 Proxy 需要驗證時才需要設定。

穿越者

這個 SDK 可讓您指定多個個別週遊,以允許資料存放區的平行週遊。SDK 範本連接器會使用這項功能。

擺設 參數
執行緒集區大小 traverse.threadPoolSize=size

連接器為了平行處理而建立的執行緒數量。單一疊代器會依序擷取作業 (通常是 RepositoryDoc 物件),但 API 會透過這個數量的執行緒平行處理。

預設值為 5

分區大小 traverse.partitionSize=batchSize

在擷取其他 APIOperation 前,批次處理的 ApiOperation() 數量。

預設值為 50

遍歷者輪詢要求

Cloud Search 索引佇列的核心是優先順序佇列,內含每個已知存在的項目。清單連接器可要求輪詢索引 API 中的項目。輪詢要求會從索引佇列中取得優先順序最高的項目。

SDK 清單連接器範本會使用下列參數來定義輪詢參數。

擺設 參數
存放區穿越工具 repository.traversers=t1, t2, t3, ...

建立一或多個個別週遊,其中 t1t2t3... 是每個工具的唯一名稱。每個命名的周遊都有自己的一組設定,系統會使用周遊者的專屬名稱 (例如 traversers.t1.hostloadtraversers.t2.hostload) 來識別這些設定。

待輪詢的佇列 traverser.pollRequest.queue=mySpecialQueue

這個週遊工具輪詢的佇列名稱。預設值為空白字串 (暗示「default」)。

traverser.t1.pollRequest.queue=mySpecialQueue

如果你有多個週遊,請為各個週遊設定項目狀態 (其中 t1 代表特定週遊)。

輪詢行為 traverser.pollRequest.limit=maxItems

輪詢要求傳回的項目數量上限。預設值為 0 (表示 API 上限)。

traverser.t1.pollRequest.limit=limit

如果你有多個週遊,請為各個週遊設定項目狀態 (其中 t1 代表特定週遊)。

項目狀態 traverser.pollRequest.statuses=statuses

這個週遊工具輪詢的特定項目狀態,其中 statuses 可以是任何 MODIFIED, NEW_ITEM 的組合 (以半形逗號分隔),預設值為空白字串 (表示所有狀態值)。

traverser.t1.pollRequest.statuses=statusesForThisTraverser

如果你有多個週遊,請為各個週遊設定項目狀態 (其中 t1 代表特定週遊)。

主機負載 traverser.hostload=threads

輪詢作業的有效平行執行緒數量上限。預設值為 5.

traverser.t1.hostload=threadsForThisTraverser

如果你有多個週遊,請為各個週遊設定項目狀態 (其中 t1 代表特定週遊)。

逾時 traverser.timeout=timeout

幹擾此週遊調查嘗試的逾時值。

預設值為 60

traverser.t1.timeout=timeoutForThisTraverser

如果你有多個週遊,請為各個週遊設定項目狀態 (其中 t1 代表特定週遊)。

traverser.timeunit=timeoutUunit

逾時單位。有效值為「SECONDS, MINUTES,

traverser.t1.timeunit=timeoutUnit

如果你有多個週遊,請為各個週遊設定項目狀態 (其中 t1 代表特定週遊)。

在大多數情況下,使用 SDK 清單連接器範本的連接器只需要一組用於輪詢的參數。在某些情況下,如果週遊演算法需要使用不同的佇列來區隔項目處理作業,您可能需要定義多個輪詢條件。

在這種情況下,您可以選擇定義多組輪詢參數。請先使用 repository.traversers 指定參數組合的名稱。請為每個已定義的周遊名稱提供設定檔,並提供上表中的參數,將 t1 替換為週遊名稱。這會為每個已定義的周遊建立一組輪詢參數。

查核點

查核點適合用於追蹤漸進式遍歷的狀態。

擺設 參數
查核點目錄 connector.checkpointDirectory=/path/to/checkpoint

指定本機目錄路徑,用於增量和完整週遊檢查點。

上傳內容

項目內容會在大小未超過指定門檻時以該項目上傳至 Cloud Search。如果內容大小超過門檻,內容就會與商品的中繼資料和結構化資料分開上傳。

擺設 參數
內容門檻 api.contentUploadThresholdBytes=bytes

這項門檻可判斷內容是否「內嵌」隨商品上傳,還是透過單獨上傳。

預設值為 100000 (約 100 KB)。

容器

完整連接器範本採用的演算法涉及臨時資料來源佇列切換功能的概念,可用來偵測資料庫中已刪除的記錄。這表示每次完整週遊時,擷取的記錄 (位於新佇列) 都會取代從先前週遊編入索引且位於舊佇列中的現有 Cloud Search 記錄。

擺設 參數
容器名稱標記 traverse.queueTag=instance

如要同時執行連接器的多個執行個體,為共用的資料存放區建立索引 (無論是在不同的資料存放區,或是一般資料存放區的獨立部分),且不干擾彼此,請為連接器每次執行指派專屬的容器名稱標記。不重複的名稱標記可避免連接器執行個體刪除其他的記錄。

系統會將名稱標記附加至完整週遊連接器切換佇列 ID。

停用刪除偵測功能 traverse.useQueues=true|false

指出連接器是否使用佇列切換邏輯來執行刪除偵測作業。

預設值為 true,表示應使用佇列。

注意:這個設定參數僅適用於實作 FullTraversalConnector 範本的連接器。

批次政策

SDK 支援可讓您執行下列動作的批次政策:

  • 批次處理要求
  • 指定批次佇列中的要求數量
  • 管理並行執行批次作業
  • 清除批次要求

SDK 會將連接器的要求批次在一起,以在上傳期間加速處理量。上傳批次要求的 SDK 觸發條件,其依據為要求數量或逾時時間 (兩者取其先)。舉例來說,如果批次延遲時間已過期,但未達到批次大小,或是項目批次大小在延遲到期前已到達,則會觸發批次上傳作業。

擺設 參數
批次處理要求 batch.batchSize=batchSize

批次處理要求。預設值為 10

批次佇列中的要求數量 batch.maxQueueLength=maxQueueLength

批次佇列中要執行的要求數量上限。預設值為 1000.

同時執行批次作業 batch.maxActiveBatches=maxActiveBatches

可並行執行的批次作業數量。預設值為 20

自動清除批次要求 batch.maxBatchDelaySeconds=maxBatchDelay

自動清除批次要求前的等待秒數。預設值為 5

在關機時清除批次要求 batch.flushOnShutdown=true|false

在服務關閉期間清除批次要求。預設值為 true

例外狀況處理常式

例外狀況處理常式參數會決定週遊在發生例外狀況後如何執行。

擺設 參數
發生錯誤時週遊的周遊指示 traverse.exceptionHandler=exceptions

擲回例外狀況後,遍歷工具應如何繼續。有效的值包括:

  • 0:遇到例外狀況後一律取消週遊
  • num_exceptions (例如 10):在周遊器遇到指定的 num_exceptions 後取消。

    預設值為 0 (錯誤時一律會取消)。

  • ignore--請忽略錯誤
例外狀況之間的等待時間 abortExceptionHander.backoffMilliSeconds=backoff

從偵測到的處理常式例外狀況之間等待的輪詢時間,以毫秒為單位 (通常在周遊存放區時使用)。預設值為 10