senzing/senzing-poc-server

senzing-poc-server## 概述

Senzing POC API Server 作为 Senzing POC 应用的后端服务。不对该代码库的向后兼容性做任何保证；但所提供的代码可作为扩展https://github.com/Senzing/senzing-api-server%E7%9A%84%E7%A4%BA%E4%BE%8B%E3%80%82

Senzing POC API OAS 规范记录了可用的 API 方法、其参数及响应格式。

图例

1. :thinking: - “思考者”图标表示可能需要额外思考。或许需要做出一些选择，或许是可选步骤。
2. :pencil2: - “铅笔”图标表示执行前可能需要修改说明。
3. :warning: - “警告”图标表示存在需要注意的复杂情况。

内容

1. 使用命令行演示
   1. 依赖项
   2. 构建
   3. 运行
2. 许可证

使用命令行演示

依赖项

要构建 Senzing POC API Server，需要 Apache Maven（建议版本 3.6.1 或更高）以及 OpenJDK 版本 11.0.x（建议版本 11.0.6+10 或更高）。

还需要在 Maven 仓库中安装 Senzing API Server，可通过 mvn install 从 senzing-api-server 子仓库构建。

1. 确保已克隆 GIT 子模块（senzing-api-server 和 senzing-api-server/senzing-rest-api-specification）：

   console
   git submodule update --init --recursive
   

2. 首先使用 https://github.com/Senzing/senzing-api-server 中的说明构建/安装 senzing-api-server 子仓库。

3. 设置环境。API 依赖于本地库，环境必须正确配置以找到这些库：

   1. Linux

      console
      export SENZING_G2_DIR=/opt/senzing/g2
      
      export LD_LIBRARY_PATH=${SENZING_G2_DIR}/lib:${SENZING_G2_DIR}/lib/debian:$LD_LIBRARY_PATH
      

   2. Windows

      console
      set SENZING_G2_DIR="C:\Program Files\Senzing\g2"
      
      set Path=%SENZING_G2_DIR%\lib;%Path%
      

构建

要构建，只需执行：

console
mvn install

JAR 文件将位于 target 目录中，名称为 senzing-poc-server-[version].jar。其中 [version] 是 pom.xml 文件中的版本号。

运行

要执行服务器，需使用 java -jar。假设环境已按照上述“依赖项”部分正确配置。

启动时必须提供 Senzing 本地 API 的初始化参数。可通过 --init-file、--init-env-var 或 --init-json 选项之一指定如何获取初始化 JSON 参数。

其他命令行选项可能对您有用。执行

console
java -jar target/senzing-poc-server-1.0.2.jar --help

可获取描述所有可用选项的帮助消息。例如：

console
$ java -jar senzing-poc-server-1.0.2.jar <选项>

<选项> 包括：

[ 标准选项 ]
   --help
        也可使用 -help。如果提供，应作为第一个且唯一的选项。
        显示此帮助消息。
        注意：如果提供此选项，服务器将不会启动。

   --version
        也可使用 -version。如果提供，应作为第一个且唯一的选项。
        显示 G2 REST API Server 的版本。
        注意：如果提供此选项，服务器将不会启动。

   --read-only [true|false]
        也可使用 -readOnly。禁用会修改实体仓库数据的功能，导致这些功能返回 403 Forbidden 响应。true/false 参数是可选的，未指定则默认为 true。如果指定为 false，则与省略该选项相同，不同之处在于省略时回退到环境变量设置，而显式 false 会覆盖任何环境变量。注意：此选项不仅会禁用向实体仓库加载数据，还会禁用对配置的修改，即使提供了 --enable-admin 选项。
        --> 通过环境变量：SENZING_API_SERVER_READ_ONLY

   --enable-admin [true|false]
        也可使用 -enableAdmin。通过 API 服务器启用管理功能。true/false 参数是可选的，未指定则默认为 true。如果指定为 false，则与省略该选项相同，不同之处在于省略时回退到环境变量设置，而显式 false 会覆盖任何环境变量。如果未指定，管理功能将返回 403 Forbidden 响应。
        --> 通过环境变量：SENZING_API_SERVER_ENABLE_ADMIN

   --http-port <端口号>
        也可使用 -httpPort。设置 HTTP 通信端口。如果未指定，默认端口为 2080。指定 0 表示随机选择可用端口号。如果配置了 SSL 客户端身份验证，则不能指定此选项。
        --> 通过环境变量：SENZING_API_SERVER_PORT

   --bind-addr <ip地址|loopback|all>
        也可使用 -bindAddr。设置 HTTP 通信的绑定地址。如果未提供，绑定地址默认为回环地址。
        --> 通过环境变量：SENZING_API_SERVER_BIND_ADDR

   --url-base-path <基础路径>
        也可使用 -urlBasePath。设置 API 服务器的 URL 基础路径。
        --> 通过环境变量：SENZING_API_SERVER_URL_BASE_PATH

   --allowed-origins <url域名>
        也可使用 -allowedOrigins。为所有端点设置 CORS Access-Control-Allow-Origin 头。无默认值。如果未指定，则响应中不包含 Access-Control-Allow-Origin。
        --> 通过环境变量：SENZING_API_SERVER_ALLOWED_ORIGINS

   --concurrency <线程数>
        也可使用 -concurrency。设置可用于执行 Senzing API 函数的线程数（即引擎线程数）。如果未指定，默认为 8。
        --> 通过环境变量：SENZING_API_SERVER_CONCURRENCY

   --http-concurrency <线程数>
        也可使用 -httpConcurrency。设置 HTTP 服务器可用的最大线程数。此选项的单个参数应为正整数。如果未指定，默认为 200。如果指定的线程数小于 10，则会报告错误。
        --> 通过环境变量：SENZING_API_SERVER_HTTP_CONCURRENCY

   --module-name <模块名>
        也可使用 -moduleName。初始化时使用的模块名。如果未指定，模块名默认为 "senzing-api-server"。
        --> 通过环境变量：SENZING_API_SERVER_MODULE_NAME

   --ini-file <ini文件路径>
        也可使用 -iniFile。用于初始化的 Senzing INI 文件路径。
        示例：-iniFile /etc/opt/senzing/G2Module.ini
        --> 通过环境变量：SENZING_API_SERVER_INI_FILE

   --init-file <json初始化文件>
        也可使用 -initFile。包含用于 Senzing 初始化的 JSON 文本的文件路径。
        示例：-initFile ~/senzing/g2-init.json
        --> 通过环境变量：SENZING_API_SERVER_INIT_FILE

   --init-env-var <环境变量名>
        也可使用 -initEnvVar。从中提取用于 Senzing 初始化的 JSON 文本的环境变量。
         安全警告：如果 JSON 文本包含密码，则可能通过进程监控对其他用户可见。
        示例：-initEnvVar SENZING_INIT_JSON
        --> 通过环境变量：SENZING_API_SERVER_INIT_ENV_VAR

   --init-json <json初始化文本>
        也可使用 -initJson。用于 Senzing 初始化的 JSON 文本。
         安全警告：如果 JSON 文本包含密码，则可能通过进程监控对其他用户可见。
        示例：-initJson "{"PIPELINE":{ ... }}"
        --> 通过环境变量：SENZING_API_SERVER_INIT_JSON

   --config-id <配置ID>
        也可使用 -configId。与 -iniFile、-initFile、-initEnvVar 或 -initJson 选项一起使用，强制使用特定的配置 ID 进行初始化。
        --> 通过环境变量：SENZING_API_SERVER_CONFIG_ID

   --auto-refresh-period <正整数秒|0|负整数>
        也可使用 -autoRefreshPeriod。如果利用数据库中存储的默认配置，此选项用于指定 API 服务器应多久后台检查当前活动配置是否与当前默认配置相同，如果不同则使用当前默认配置重新初始化。如果指定为 0，则禁用自动刷新，仅当请求的配置元素在当前活动配置中未找到时才会刷新。允许指定负整数，但用于仅在手动请求（以编程方式）时启用检查和条件刷新。注意：如果通过 G2CONFIGFILE 初始化选项指定了配置，或者已通过 --config-id 指定锁定到特定配置，则忽略此选项。
        --> 通过环境变量：SENZING_API_SERVER_AUTO_REFRESH_PERIOD

   --stats-interval <毫秒>
        也可使用 -statsInterval。日志记录统计信息之间的最小毫秒数。这是最小值，因为如果 API 服务器处于空闲状态或活跃但未执行与实体评分相关的活动，则统计信息日志记录会被抑制。在这种情况下，统计信息日志记录会延迟到执行与实体评分相关的活动时。默认设置为 15 分钟的毫秒等效值。如果指定为 0，则会抑制统计信息的日志记录。
        --> 通过环境变量：SENZING_API_SERVER_STATS_INTERVAL

   --skip-startup-perf [true|false]
        也可使用 -skipStartupPerf。如果指定，则跳过启动时的性能检查。true/false 参数是可选的，未指定则默认为 true。如果指定为 false，则与省略该选项相同，不同之处在于省略时回退到环境变量设置，而显式 false 会覆盖任何环境变量。
        --> 通过环境变量：SENZING_API_SERVER_SKIP_STARTUP_PERF

   --skip-engine-priming [true|false]
        也可使用 -skipEnginePriming。如果指定，则 API 服务器在启动时不会预加载引擎。true/false 参数是可选的，未指定则默认为 true。如果指定为 false，则与省略该选项相同，不同之处在于省略时回退到环境变量设置，而显式 false 会覆盖任何环境变量。
        --> 通过环境变量：SENZING_API_SERVER_SKIP_ENGINE_PRIMING

   --verbose [true|false]
        也可使用 -verbose。如果指定，则以详细模式初始化。true/false 参数是可选的，未指定则默认为 true。如果指定为 false，则与省略该选项相同，不同之处在于省略时回退到环境变量设置，而显式 false 会覆盖任何环境变量。
        --> 通过环境变量：SENZING_API_SERVER_VERBOSE

   --quiet [true|false]
        也可使用 -quiet。如果指定，则 API 服务器减少输出到标准输出的反馈消息数量。这仅适用于 API 服务器生成的消息，不适用于底层 API 生成的消息（如果提供 --verbose，底层 API 可能会生成大量消息）。true/false 参数是可选的，未指定则默认为 true。如果指定为 false，则与省略该选项相同，不同之处在于省略时回退到环境变量设置，而显式 false 会覆盖任何环境变量。
        --> 通过环境变量：SENZING_API_SERVER_QUIET

   --debug [true|false]
        也可使用 -debug。如果指定，则启用调试日志记录。true/false 参数是可选的，未指定则默认为 true。如果指定为 false，则与省略该选项相同，不同之处在于省略时回退到环境变量设置，而显式 false 会覆盖任何环境变量。
        --> 通过环境变量：SENZING_API_SERVER_DEBUG

   --monitor-file <文件路径>
        也可使用 -monitorFile。指定一个文件，通过监控其时间戳来确定何时关闭服务器。
        --> 通过环境变量：SENZING_API_SERVER_MONITOR_FILE

[ HTTPS / SSL 选项 ]
   以下选项与 HTTPS / SSL 配置相关。--key-store 和 --key-store-password 选项是启用 HTTPS / SSL 通信的最低要求选项。如果启用了 HTTPS / SSL 通信，则 HTTP 通信被禁用，除非指定了 --http-port 选项。但是，如果通过 --client-key-store 和 --client-key-store-password 选项配置了客户端 SSL 身份验证，则禁止通过 --http-port 选项启用 HTTP 通信。

   --https-port <端口号>
        也可使用 -httpsPort。设置安全 HTTPS 通信的端口。如果未指定，默认 HTTPS 端口为 2443，但仅当指定了 --key-store 选项时才启用 HTTPS。指定 0 表示随机选择可用端口号。
        --> 通过环境变量：SENZING_API_SERVER_SECURE_PORT

   --key-store <pkcs12密钥库文件路径>
        也可使用 -keyStore。指定包含服务器用于 HTTPS 通信的私钥的密钥库文件。
        --> 通过环境变量：SENZING_API_SERVER_KEY_STORE

   --key-store-password <密码>
        也可使用 -keyStorePassword。指定用于解密通过 --key-store 选项指定的密钥库文件的密码。
        --> 通过环境变量：SENZING_API_SERVER_KEY_STORE_PASSWORD

   --key-alias <服务器密钥别名>
        也可使用 -keyAlias。可选地指定指定密钥库中私有服务器密钥的别名。如果未指定，则使用在指定密钥库中找到的第一个密钥。
        --> 通过环境变量：SENZING_API_SERVER_KEY_ALIAS

   --client-key-store <pkcs12密钥库文件路径>
        也可使用 -clientKeyStore。指定包含被授权连接的客户端公钥的密钥库文件。如果指定此选项，则需要 SSL 客户端身份验证，并且禁止使用 --http-port 选项。
        --> 通过环境变量：SENZING_API_SERVER_CLIENT_KEY_STORE

   --client-key-store-password <密码>
        也可使用 -clientKeyStorePassword。指定用于解密通过 --client-key-store 选项指定的密钥库文件的密码。
        --> 通过环境变量：SENZING_API_SERVER_CLIENT_KEY_STORE_PASSWORD

[ 异步信息队列选项 ]
   以下选项与配置异步消息队列相关，用于发送加载、删除记录或重新评估实体时生成的“信息”消息。最多可配置一个此类队列。如果配置了“信息”队列，则每次加载、删除和重新评估操作都将使用生成信息消息的变体执行。发送到队列（或主题）的信息消息是相关的“原始数据”JSON 片段。

   --sqs-info-url <url>
        也可使用 -sqsInfoUrl。指定 Amazon SQS 队列 URL 作为信息队列。
        --> 通过环境变量：SENZING_SQS_INFO_QUEUE_URL

   --rabbit-info-host <主机名>
        也可使用 -rabbitInfoHost。用于指定连接到 RabbitMQ 以指定 RabbitMQ 信息队列的主机名。
        --> 通过环境变量：SENZING_RABBITMQ_INFO_HOST
                             SENZING_RABBITMQ_HOST（回退）

   --rabbit-info-port <端口>
        也可使用 -rabbitInfoPort。用于指定连接到 RabbitMQ 以指定 RabbitMQ 信息队列的端口号。
        --> 通过环境变量：SENZING_RABBITMQ_INFO_PORT
                             SENZING_RABBITMQ_PORT（回退）

   --rabbit-info-user <用户名>
        也可使用 -rabbitInfoUser。用于指定连接到 RabbitMQ 以指定 RabbitMQ 信息队列的用户名。
        --> 通过环境变量：SENZING_RABBITMQ_INFO_USERNAME
                             SENZING_RABBITMQ_USERNAME（回退）

   --rabbit-info-password <密码>
        也可使用 -rabbitInfoPassword。用于指定连接到 RabbitMQ 以指定 RabbitMQ 信息队列的密码。
        --> 通过环境变量：SENZING_RABBITMQ_INFO_PASSWORD
                             SENZING_RABBITMQ_PASSWORD（回退）

   --rabbit-info-virtual-host <虚拟主机>
        也可使用 -rabbitInfoVirtualHost。用于指定连接到 RabbitMQ 以指定 RabbitMQ 信息队列的虚拟主机。
        --> 通过环境变量：SENZING_RABBITMQ_INFO_VIRTUAL_HOST
                             SENZING_RABBITMQ_VIRTUAL_HOST（回退）

   --rabbit-info-exchange <交换机>
        也可使用 -rabbitInfoExchange。用于指定连接到 RabbitMQ 以指定 RabbitMQ 信息队列的交换机。
        --> 通过环境变量：SENZING_RABBITMQ_INFO_EXCHANGE
                             SENZING_RABBITMQ_EXCHANGE（回退）

   --rabbit-info-routing-key <路由键>
        也可使用 -rabbitInfoRoutingKey。用于指定连接到 RabbitMQ 以指定 RabbitMQ 信息队列的路由键。
        --> 通过环境变量：SENZING_RABBITMQ_INFO_ROUTING_KEY

   --kafka-info-bootstrap-server <引导服务器>
        也可使用 -kafkaInfoBoot