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 信息，然后 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 方法结合使用，以计算修改状态。长度上限为 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.hostname 和 transport.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, ...

创建一个或多个独立遍历器，其中 t1、t2、t3、... 是每个遍历器的唯一名称。每个命名的遍历器都有自己的一组设置，这些设置使用遍历器的唯一名称（例如 traversers.t1.hostload 和 traversers.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（约 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）--abort 在遍历器遇到指定的 num_exceptions 后中止。

    默认值为 0（出错时一律取消）。

  • ignore - 忽略错误
两次异常之间的等待时间 abortExceptionHander.backoffMilliSeconds=backoff

在检测到的处理程序异常之间等待的退避时间（以毫秒为单位），通常在遍历存储库时使用。默认值为 10。