每個連接器都有相關聯的設定檔,其中包含連接器使用的參數,例如存放區的 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
這個參數會指定索引服務基準網址路徑。 這個參數的預設值是空白字串,會轉換為 |
週遊排程
排程參數會決定連接器在周遊之間的等待頻率。
擺設 | 參數 |
---|---|
在連接器啟動時完整週遊 | schedule.performTraversalOnStart=true|false
連接器會在連接器啟動時執行完整週遊,而不會等待第一個間隔到期。預設值為 |
在間隔後完整週遊 | schedule.traversalIntervalSecs=intervalInSeconds
連接器會在指定的時間間隔後執行完整週遊。指定週遊之間的間隔時間 (以秒為單位)。預設值為 |
一次週遊後離開 | connector.runOnce=true|false
連接器會完整週遊一次,然後結束。只有在您使用完整週遊策略時,這個參數才應設為 |
在間隔後週遊增量 | schedule.incrementalTraversalIntervalSecs=intervalInSeconds
連接器會在指定間隔後執行漸進式週遊。指定週遊之間的間隔時間 (以秒為單位)。預設值為 |
排定的意見調查佇列間隔 | schedule.pollQueueIntervalSecs=interval_in_seconds
排定的意見調查佇列時間間隔 (以秒為單位)。只會用於列出週遊連接器。預設值為 |
存取控制清單 (ACL)
連接器會使用 ACL 來控制項目的存取權。您可以運用多個參數,透過 ACL 保護使用者存取已建立索引記錄的權限。
如果您的存放區有與各個項目相關聯的個別 ACL 資訊,請上傳所有 ACL 資訊,以控制 Cloud Search 中的項目存取權。如果存放區提供部分 ACL 資訊,或是完全沒有 ACL 資訊,您可以在 SDK 下列參數中提供預設 ACL 資訊,以供 SDK 提供給連接器。
擺設 | 參數 |
---|---|
ACL 模式 | defaultAcl.mode=mode
決定套用預設 ACL 的時機。有效值:
預設模式為 |
預設公開 ACL | defaultAcl.public=true|false
整個存放區的預設 ACL 已設為公開網域存取權。預設值為 |
常見的 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 |
整個網域存取權 | 如要指定網域中的所有使用者都能公開存取所有已建立索引的記錄,請使用下列值設定下列兩個參數:
|
一般定義的 ACL | 如要為資料存放區的每筆記錄指定一個 ACL,請設定下列所有參數值:
|
中繼資料設定參數
部分作品中繼資料可設定。連接器可以在建立索引時設定可設定的中繼資料欄位。如果連接器未設定欄位,系統會使用設定檔中的參數來設定欄位。
設定檔包含一系列以 .field
後置字串表示的具名中繼資料設定參數,例如 itemMetadata.title.field=movieTitle
。如果這些參數有值,就會用於設定中繼資料欄位。如果沒有命名中繼資料參數的值,系統會使用含有 .defaultValue
後置字串的參數設定中繼資料。
下表為中繼資料設定參數。
設定 | 參數 |
標題 | itemMetadata.title.field=movieTitle
itemMetadata.title.defaultValue=
商品名稱。如未設定 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=
連接器使用的物件類型,如結構定義所定義。如未指定這個屬性,連接器就不會為任何結構化資料建立索引。 如未設定 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=
已建立索引文件的內容語言。如未設定 contentLanguage.field 值,系統會使用 contentLanguage.defaultValue 的值。
|
Mime 類型 | itemMetadata.mimeType.field=mimeType
itemMetadata.mimeType.defaultValue=
來源存放區中 ItemContent.content 的原始 MIME 類型。長度上限為 256 個半形字元。如未設定 mimeType.field 值,系統會使用 mimeType.defaultValue 的值。 |
搜尋品質中繼資料 | itemMetadata.searchQualityMetadata.quality.field=quality
itemMetadata.searchQualityMetadata.quality.defaultValue=
指出商品品質的標示,用於影響搜尋品質。值應介於 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
連接器如何處理未指定的內容欄位。有效的值包括:
|
在 HTML 範本中加入欄位名稱 | contentTemplate.templateName.includeFieldName=true|false
指定是否要在 HTML 範本中一併加入欄位名稱與欄位資料。預設值為 |
不常見的參數設定
其實不太需要設定這個部分列出的參數。參數的預設值是設定最佳效能。如果存放區沒有特定要求,Google 不建議將這些參數設為與預設值不同的值。
Proxy 配置
SDK 可讓您將連接器設定為使用 Proxy 處理傳出連線。
需要 transport.proxy.hostname
和 transport.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 的類型。有效的值包括:
預設值為 |
使用者名稱 | transport.proxy.username=username
建構 Proxy 授權權杖時使用的使用者名稱。這是選用參數,只有在您的 Proxy 需要驗證時才需要設定。 |
密碼 | transport.proxy.password=password
建構 Proxy 授權權杖時使用的密碼,這是選用參數,只有在您的 Proxy 需要驗證時才需要設定。 |
穿越者
這個 SDK 可讓您指定多個個別週遊,以允許資料存放區的平行週遊。SDK 範本連接器會使用這項功能。
擺設 | 參數 |
---|---|
執行緒集區大小 | traverse.threadPoolSize=size
連接器為了平行處理而建立的執行緒數量。單一疊代器會依序擷取作業 (通常是 RepositoryDoc 物件),但 API 會透過這個數量的執行緒平行處理。 預設值為 |
分區大小 | traverse.partitionSize=batchSize
在擷取其他 預設值為 |
遍歷者輪詢要求
Cloud Search 索引佇列的核心是優先順序佇列,內含每個已知存在的項目。清單連接器可要求輪詢索引 API 中的項目。輪詢要求會從索引佇列中取得優先順序最高的項目。
SDK 清單連接器範本會使用下列參數來定義輪詢參數。
擺設 | 參數 |
---|---|
存放區穿越工具 | repository.traversers=t1, t2, t3, ...
建立一或多個個別週遊,其中 t1、t2、t3、... 是每個工具的唯一名稱。每個命名的周遊都有自己的一組設定,系統會使用周遊者的專屬名稱 (例如 |
待輪詢的佇列 | traverser.pollRequest.queue=mySpecialQueue
這個週遊工具輪詢的佇列名稱。預設值為空白字串 (暗示「default」)。 |
traverser.t1.pollRequest.queue=mySpecialQueue
如果你有多個週遊,請為各個週遊設定項目狀態 (其中 t1 代表特定週遊)。 |
|
輪詢行為 | traverser.pollRequest.limit=maxItems
輪詢要求傳回的項目數量上限。預設值為 |
traverser.t1.pollRequest.limit=limit
如果你有多個週遊,請為各個週遊設定項目狀態 (其中 t1 代表特定週遊)。 |
|
項目狀態 | traverser.pollRequest.statuses=statuses
這個週遊工具輪詢的特定項目狀態,其中 statuses 可以是任何 |
traverser.t1.pollRequest.statuses=statusesForThisTraverser
如果你有多個週遊,請為各個週遊設定項目狀態 (其中 t1 代表特定週遊)。 | |
主機負載 | traverser.hostload=threads
輪詢作業的有效平行執行緒數量上限。預設值為 |
traverser.t1.hostload=threadsForThisTraverser
如果你有多個週遊,請為各個週遊設定項目狀態 (其中 t1 代表特定週遊)。 |
|
逾時 | traverser.timeout=timeout
幹擾此週遊調查嘗試的逾時值。 預設值為 |
traverser.t1.timeout=timeoutForThisTraverser
如果你有多個週遊,請為各個週遊設定項目狀態 (其中 t1 代表特定週遊)。 |
|
traverser.timeunit=timeoutUunit
逾時單位。有效值為「 |
|
traverser.t1.timeunit=timeoutUnit
如果你有多個週遊,請為各個週遊設定項目狀態 (其中 t1 代表特定週遊)。 |
在大多數情況下,使用 SDK 清單連接器範本的連接器只需要一組用於輪詢的參數。在某些情況下,如果週遊演算法需要使用不同的佇列來區隔項目處理作業,您可能需要定義多個輪詢條件。
在這種情況下,您可以選擇定義多組輪詢參數。請先使用 repository.traversers
指定參數組合的名稱。請為每個已定義的周遊名稱提供設定檔,並提供上表中的參數,將 t1
替換為週遊名稱。這會為每個已定義的周遊建立一組輪詢參數。
查核點
查核點適合用於追蹤漸進式遍歷的狀態。
擺設 | 參數 |
---|---|
查核點目錄 | connector.checkpointDirectory=/path/to/checkpoint
指定本機目錄路徑,用於增量和完整週遊檢查點。 |
上傳內容
項目內容會在大小未超過指定門檻時以該項目上傳至 Cloud Search。如果內容大小超過門檻,內容就會與商品的中繼資料和結構化資料分開上傳。
擺設 | 參數 |
---|---|
內容門檻 | api.contentUploadThresholdBytes=bytes
這項門檻可判斷內容是否「內嵌」隨商品上傳,還是透過單獨上傳。 預設值為 |
容器
完整連接器範本採用的演算法涉及臨時資料來源佇列切換功能的概念,可用來偵測資料庫中已刪除的記錄。這表示每次完整週遊時,擷取的記錄 (位於新佇列) 都會取代從先前週遊編入索引且位於舊佇列中的現有 Cloud Search 記錄。
擺設 | 參數 |
---|---|
容器名稱標記 | traverse.queueTag=instance
如要同時執行連接器的多個執行個體,為共用的資料存放區建立索引 (無論是在不同的資料存放區,或是一般資料存放區的獨立部分),且不干擾彼此,請為連接器每次執行指派專屬的容器名稱標記。不重複的名稱標記可避免連接器執行個體刪除其他的記錄。 系統會將名稱標記附加至完整週遊連接器切換佇列 ID。 |
停用刪除偵測功能 | traverse.useQueues=true|false
指出連接器是否使用佇列切換邏輯來執行刪除偵測作業。 預設值為 注意:這個設定參數僅適用於實作 |
批次政策
SDK 支援可讓您執行下列動作的批次政策:
- 批次處理要求
- 指定批次佇列中的要求數量
- 管理並行執行批次作業
- 清除批次要求
SDK 會將連接器的要求批次在一起,以在上傳期間加速處理量。上傳批次要求的 SDK 觸發條件,其依據為要求數量或逾時時間 (兩者取其先)。舉例來說,如果批次延遲時間已過期,但未達到批次大小,或是項目批次大小在延遲到期前已到達,則會觸發批次上傳作業。
擺設 | 參數 |
---|---|
批次處理要求 | batch.batchSize
批次處理要求。預設值為 |
批次佇列中的要求數量 | batch.maxQueueLength=maxQueueLength
批次佇列中要執行的要求數量上限。預設值為 |
同時執行批次作業 | batch.maxActiveBatches=maxActiveBatches
可並行執行的批次作業數量。預設值為 |
自動清除批次要求 | batch.maxBatchDelaySeconds=maxBatchDelay
自動清除批次要求前的等待秒數。預設值為 |
在關機時清除批次要求 | batch.flushOnShutdown=true|false
在服務關閉期間清除批次要求。預設值為 |
例外狀況處理常式
例外狀況處理常式參數會決定週遊在發生例外狀況後如何執行。
擺設 | 參數 |
---|---|
發生錯誤時週遊的周遊指示 | traverse.exceptionHandler=exceptions
擲回例外狀況後,遍歷工具應如何繼續。有效的值包括:
|
例外狀況之間的等待時間 | abortExceptionHander.backoffMilliSeconds=backoff
從偵測到的處理常式例外狀況之間等待的輪詢時間,以毫秒為單位 (通常在周遊存放區時使用)。預設值為 |