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 信息,以便控制 Cloud Search 中的内容访问权限。如果您的代码库提供部分 ACL 信息或不提供 ACL 信息,您可以在以下参数中提供默认 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 代码>
  • 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
项的容器的名称,例如文件的名称 system 目录或文件夹。如果 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 方法结合使用以计算修改状态。长度上限为 2048 个字符。如果 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 建议不要在代码库中将这些参数设置为与其默认值不同的值。

代理配置

通过该 SDK,您可以将连接器配置为对传出连接使用代理。

必须使用 transport.proxy.hostnametransport.proxy.port 参数才能通过代理实现传输。如果您的代理要求进行身份验证,或者通过 SOCKS 协议(而不是 HTTP)运行,则您可能需要其他参数。如果未设置 transport.proxy.hostname,则 SDK 将不会使用代理。

设置 参数
主机名 transport.proxy.hostname=hostname

代理服务器的主机名。使用代理时必须提供此参数。

端口 transport.proxy.port=port

代理服务器的端口号。使用代理时必须提供此参数。

代理类型 transport.proxy.type=type

代理的类型。有效值包括:

  • HTTP - 代理通过 HTTP 接受和转发请求。
  • SOCKS - 代理通过 SOCKS 协议接受和转发数据包。

默认值为 HTTP

用户名 transport.proxy.username=username

构建代理授权令牌时使用的用户名。 此参数为可选参数,且仅在您的代理需要身份验证时才应设置。

密码 transport.proxy.password=password

构建代理授权令牌时使用的密码。 此参数为可选参数,且仅在您的代理需要身份验证时才应设置。

遍历器

SDK 允许您指定多个单独的遍历器,以允许对数据存储区进行并行遍历。SDK 模板连接器使用此功能。

设置 参数
线程池大小 traverse.threadPoolSize=size

连接器创建用于支持并行处理的线程数。单个迭代器会串行提取操作(通常为 RepositoryDoc 对象),但 API 则使用此数量的线程并行调用进程。

默认值为 5

分区大小 traverse.partitionSize=batchSize

要在提取其他 APIOperation 之前批量处理的 ApiOperation() 数量。

默认值为 50

遍历轮询请求

Cloud Search 索引队列的核心是优先级队列,其中包含每个已知存在的条目。商品详情连接器可以通过 Indexing API 请求轮询内容。轮询请求会从索引队列中获取优先级最高的条目。

SDK 列表连接器模板使用以下参数来定义轮询参数。

设置 参数
代码库遍历 repository.traversers=t1, t2, t3, ...

创建一个或多个独立遍历器,其中 t1t2t3... 是每个遍历器的唯一名称。每个命名的遍历器都有自己的一组设置,这些设置使用遍历器的唯一名称(如 traversers.t1.hostloadtraversers.t2.hostload)进行标识。

要轮询的队列 traverser.pollRequest.queue=mySpecialQueue

此遍历器轮询的队列名称。默认值为空字符串(表示“默认”)。

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(约 100KB)。

容器

完整连接器模板使用一种算法,该概念涉及临时数据源队列切换开关的概念,用于检测数据库中已删除的记录。 这意味着,每次完整遍历时,新队列中提取的记录都会替换旧队列中已编入索引的所有现有 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